Stellarium 0.11.4
Home · All Namespaces · All Classes · Functions · Coding Style · Scripting · Plugins · File Structure

Coding Style Conventions in Stellarium

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.

Stylistic Conventions

File Names

The extensions are .hpp/.cpp for C++ headers/code, .h/.c for C headers/code. C++ files should have the same name and case than the class they contain. For example class StelFontMgr should be declared in file StelFontMgr.hpp and implemented in StelFontMgr.cpp.

Doxygen Comments

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

"Doxygen is a documentation system for C++, C, Java, [...] It can generate an on-line documentation browser (in HTML) and/or an off-line reference manual (in LaTeX) from a set of documented source files. [...] The documentation is extracted directly from the sources, which makes it much easier to keep the documentation consistent with the source code. [...] 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.

All public and protected classes and methods from Stellarium should be fully documented in the headers (.hpp).

There are different ways to comment C++ code with Doxygen, in Stellarium use the following for headers files:

 //! 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.
 QList<QString> listMatchingObjectsI18n(const QString& objPrefix, unsigned int maxNbItem=5) const;

Brief descriptions are single line only, and stop at the first full stop (period). Any subsequent sentences which occur before @param or a similar tag are considered to be part of a detailed description.

For methods definitions in .cpp files, a simpler comment for each method is sufficient:

// Find and return the list of at most maxNbItem objects auto-completing the 
// passed object I18n name.
QList<QString> listMatchingObjectsI18n(const QString& objPrefix, unsigned int maxNbItem=5) const
{
     etc..

C/C++ Code

Use C++ replacement for C functions and Qt replacements for C++ functions/STL wherever possible.

Translatable Strings and Console Output

Translatable strings are translated using the StelTranslator class, which is a C++ wrapper around gettext. The strings should be marked using the q_() macro: it takes a QString in English and returns the translation as a QString using the current global language. Note that you can also call q_() with a QString object to return a translation. In cases when a string literal needs to be marked for translation without returning a string, use the N_() macro.

Generated on Sat Aug 25 22:13:31 2012 for Stellarium by  doxygen 1.6.3