Coding Standard

(Difference between revisions)
Jump to: navigation, search
Line 30: Line 30:
 
=== Doxygen Comments ===
 
=== Doxygen Comments ===
  
Stellarium source code should be document with Doxygen. From Doxygen webpage:
+
Stellarium source code should be document with [http://www.stack.nl/~dimitri/doxygen/index.html Doxygen]. From Doxygen webpage:
  
 
<i>"Doxygen is a documentation system for C++, C, Java, Objective-C, Python, IDL (Corba and Microsoft flavors) and to some extent PHP, C#, and D.
 
<i>"Doxygen is a documentation system for C++, C, Java, Objective-C, Python, IDL (Corba and Microsoft flavors) and to some extent PHP, C#, and D.
Line 41: Line 41:
  
 
Doxygen is developed under Linux and Mac OS X, but is set-up to be highly portable. As a result, it runs on most other Unix flavors as well. Furthermore, executables for Windows are available."</i>
 
Doxygen is developed under Linux and Mac OS X, but is set-up to be highly portable. As a result, it runs on most other Unix flavors as well. Furthermore, executables for Windows are available."</i>
 +
 +
There are different way to comment C++ code with Doxygen, in Stellarium use the following:
 +
 +
//! Find and return the list of at most maxNbItem objects auto-completing the passed object I18n name
 +
//! @param objPrefix the case insensitive first letters of the searched object
 +
//! @param maxNbItem the maximum number of returned object names
 +
//! @return a vector of matching object name by order of relevance, or an empty vector if nothing match
 +
vector<wstring> listMatchingObjectsI18n(const wstring& objPrefix, unsigned int maxNbItem=5) const;
  
 
=== Low-level C code ===
 
=== Low-level C code ===
 +
Use C++ replacement for C functions wherever possible. This includes the following uses:
 +
* std::string instead of char*
 +
* iostream C++ classes instead of C file managment with fopen()
 +
* pass objects as references when needed instead of using pointers.
 +
* Avoid using pointers when not needed, for example:
 +
wrong:
 +
string mapFileName = getDataDir() + "fontmap.dat";
 +
ifstream *mapFile = new ifstream(mapFileName.c_str());
 +
 +
good:
 +
string mapFileName = getDataDir() + "fontmap.dat";
 +
ifstream mapFile(mapFileName);
 +
 +
=== Translatable strings and text console output ===
 +
In Stellarium, translatable text is translated using the Translator class, which is a C++ wrapper to gettext. The translation process is done using the _() macro which takes in input a std::string in english and return in output a std::wstring translated in another langage, which is a string of wide characters, translated using the current global Translator.
 +
 +
Translatable text in sources or in data files should be written in english, encoded in ASCII or UTF-8 if needed.
  
=== Translatable strings ===
+
In general no translated text (i.e. no wstring) should be output on the console because this is not very protable. This means that you should never use wcout, wcerr or wprintf(). Console output should be used for informations, errors and warnings which are not required by the user in nominal use.

Revision as of 13:16, 19 September 2006

The increasing number of contributors require that we clearly define coding rules and guidelines. Although for historical reasons the current code of Stellarium does not always comply to these rules, they should now be respected for any addition or modification of the code.

Contents

Stylistic Conventions

  • Source code should use ASCII character set. Characters such as 'é' or 'ö' are not portable when hardcoded. Gettext translated strings should be used for such characters.
  • Variable names and comments should be in english.
  • Class names are nouns, in mixed-case, with an initial upper-case letter and the first letter of each subsequent word capitalized (e.g. CoreFactory).
  • Method names are verbs or nouns in mixed-case, starting with a lower-case letter (e.g. update() or addElement()).
  • Methods that return a value should take the form getSize().
  • The names of local variables should be in mixed case, starting with a lower-case letter (e.g. packetSize). This also applies to the formal parameters of methods. Do not use names starting with underscore.
  • The names of macro or static final constants should be all upper-case words, separated by underscores (e.g. MIN_WIDTH).
  • Indentation should be done with tabs, not spaces. This enables each developers to use his favorite indent size without changing the code.
  • Use blank lines as follows:
    • 1 between methods, before (block or single line) comment
    • 1 between logical sections of a method
    • 2 between sections of a source file
  • Use the following layout for braces:
void MyClass::myMethod(int x)
{
   if (x>10)
   {
      cout << "You won." << endl;
   }
}


Doxygen Comments

Stellarium source code should be document with Doxygen. From Doxygen webpage:

"Doxygen is a documentation system for C++, C, Java, Objective-C, Python, IDL (Corba and Microsoft flavors) and to some extent PHP, C#, and D.

It can help you in three ways:

  1. It can generate an on-line documentation browser (in HTML) and/or an off-line reference manual (in $\mbox{\LaTeX}$) from a set of documented source files. There is also support for generating output in RTF (MS-Word), PostScript, hyperlinked PDF, compressed HTML, and Unix man pages. The documentation is extracted directly from the sources, which makes it much easier to keep the documentation consistent with the source code.
  2. You can configure doxygen to extract the code structure from undocumented source files. This is very useful to quickly find your way in large source distributions. You can also visualize the relations between the various elements by means of include dependency graphs, inheritance diagrams, and collaboration diagrams, which are all generated automatically.
  3. You can even `abuse' doxygen for creating normal documentation (as I did for this manual).

Doxygen is developed under Linux and Mac OS X, but is set-up to be highly portable. As a result, it runs on most other Unix flavors as well. Furthermore, executables for Windows are available."

There are different way to comment C++ code with Doxygen, in Stellarium use the following:

//! Find and return the list of at most maxNbItem objects auto-completing the passed object I18n name
//! @param objPrefix the case insensitive first letters of the searched object
//! @param maxNbItem the maximum number of returned object names
//! @return a vector of matching object name by order of relevance, or an empty vector if nothing match
vector<wstring> listMatchingObjectsI18n(const wstring& objPrefix, unsigned int maxNbItem=5) const;

Low-level C code

Use C++ replacement for C functions wherever possible. This includes the following uses:

  • std::string instead of char*
  • iostream C++ classes instead of C file managment with fopen()
  • pass objects as references when needed instead of using pointers.
  • Avoid using pointers when not needed, for example:

wrong:

string mapFileName = getDataDir() + "fontmap.dat";
ifstream *mapFile = new ifstream(mapFileName.c_str());

good:

string mapFileName = getDataDir() + "fontmap.dat";
ifstream mapFile(mapFileName);

Translatable strings and text console output

In Stellarium, translatable text is translated using the Translator class, which is a C++ wrapper to gettext. The translation process is done using the _() macro which takes in input a std::string in english and return in output a std::wstring translated in another langage, which is a string of wide characters, translated using the current global Translator.

Translatable text in sources or in data files should be written in english, encoded in ASCII or UTF-8 if needed.

In general no translated text (i.e. no wstring) should be output on the console because this is not very protable. This means that you should never use wcout, wcerr or wprintf(). Console output should be used for informations, errors and warnings which are not required by the user in nominal use.

Personal tools
Namespaces
Variants
Actions
in this wiki
other languages
Toolbox