codingConventions.doxygen   codingConventions.doxygen 
skipping to change at line 27 skipping to change at line 27
* Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, U SA. * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, U SA.
*/ */
/*! /*!
@page codingStyle Coding Style Conventions in Stellarium @page codingStyle Coding Style Conventions in Stellarium
@tableofcontents @tableofcontents
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 respec ted for any addition or modification of the code. 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 respec ted for any addition or modification of the code.
@section stylistic_conventions_sec Stylistic Conventions @section stylistic_conventions_sec Stylistic Conventions
<ul> - Source code should use the ASCII character set. Characters such as '&egr
<li>Source code should use ASCII character set. Characters such as '&egrav ave;'
e;' or '&ouml;' are not portable when hard-coded. Gettext translated string or '&ouml;' are not portable when hard-coded. Gettext translated strings s
s should be used for such characters. hould
<li>Variable names and comments should be in English. be used for text using such characters.
<li>Class names are nouns, in mixed-case, with an initial upper-case - Variable names and comments should be in English.
letter and the first letter of each subsequent word capitalized (e.g. CoreF - Class names are nouns, in mixed-case, with an initial upper-case letter
actory). and
<li>Method names are verbs or nouns in mixed-case, starting with a lower-c the first letter of each subsequent word capitalized (e.g. @c CoreFactory)
ase letter (e.g. update() or addElement()). .
<li>Methods that return a value should take the form getSize(). - Method names are verbs or nouns in mixed-case, starting with a lower-cas
<li>The names of local variables should be in mixed case, starting with a e
lower-case letter (e.g. packetSize). This also applies to the formal parame letter (e.g. @c update() or @c addElement()).
ters of methods. Do not use names starting with underscore. - Names of methods that return a value should start with a suitable verb,
<li>The names of macro or static const should be all upper-case words, sep such as @c getSize().
arated by underscore: - For methods, only names of Qt signals should be in passive voice
(@c valueChanged()). Names of Qt slots should use active verbs to avoid
confusion with signals:
@code
// BAD:
void buttonBoomClicked(); // Causes an explosion.
// BETTER:
void handleButtonBoom(); // Connected to buttonBoom::clicked().
// EVEN BETTER:
void explode(); // Connected to buttonBoom::clicked().
@endcode
The only exception is names of slots that use Qt's automatic connections t
o
controls in .ui files. (See @c QMetaObject::connectSlotsByName().)
- The names of local variables should be in mixed case, starting with
a lower-case letter (e.g. @c packetSize). This also applies to the formal
parameters of methods. Do not use names starting with underscore.
- The names of macro or static const should be all upper-case words, separ
ated by underscore:
@code @code
#define MIN_WIDTH 3 #define MIN_WIDTH 3
static const QString VERSION = "0.10.1"; static const QString VERSION = "0.10.1";
@endcode @endcode
<li>Indentation should be done with tabs, not spaces. This allows each dev - Indentation should be done with tabs, not spaces. This allows developers
elopers to use his favorite indent size without changing the code. to use their favorite indent size without changing the code.
<li>When wrapping lines from long function calls, where the wrapped line d - When wrapping lines from long function calls, where the wrapped line doe
oes not start at the same level of indentation as the start of the function s not start at the same level of indentation as the start of the function c
call, tab up to the start of the function call, and then use spaces to the all, tab up to the start of the function call, and then use spaces to the o
opening parenthesis. pening parenthesis.
@verbatim @verbatim
[--tab-][--tab-][--tab-]someFunction(param, ... [--tab-][--tab-][--tab-]someFunction(param, ...
[--tab-][--tab-][--tab-][ spaces ]moreparams, ...); [--tab-][--tab-][--tab-][ spaces ]moreparams, ...);
@endverbatim @endverbatim
This method will handle different tab widths gracefully. This method will handle different tab widths gracefully.
<li>Use the following layout for braces: - Use the following layout for braces:
@code @verbatim
void MyClass::myMethod(int x) void MyClass::myMethod(int x)
{ {
if (x>10) if (x>10)
{ {
cout << "You won." << endl; cout << "You won." << endl;
} }
} }
@endcode @endverbatim
<li>Use blank lines as follows: - Use blank lines as follows:
<ul> - 1 between methods, before (block or single line) comment
<li>1 between methods, before (block or single line) comment - 1 between logical sections of a method
<li>1 between logical sections of a method - 2 between sections of a source file
<li>2 between sections of a source file - @c enums should follow the %Qt conventions. i.e. CamelCase with First l
</ul> etter capitalization for both enum type and enum values. Document with doxy
<li>@em enums should follow the %Qt conventions. i.e. CamelCase with Firs gen. The <b>//!\< </b>tag can be used to add descriptions on the same line
t letter capitalization for both enum type and enum values. Document with d as an enum value, e.g.
oxygen. The <b>//!\< </b>tag can be used to add descriptions on the same li @verbatim
ne as an enum value, e.g.
@verbatim
//! @enum EnumName Here is a description of the enum //! @enum EnumName Here is a description of the enum
enum EnumName enum EnumName
{ {
EnumValueOne, //!< Some doxygen description of EnumValueOne EnumValueOne, //!< Some doxygen description of EnumValueOne
EnumValueTwo, //!< Some doxygen description of EnumValueTwo EnumValueTwo, //!< Some doxygen description of EnumValueTwo
EnumValueThree //!< Some doxygen description of EnumValueThree EnumValueThree //!< Some doxygen description of EnumValueThree
}; };
@endverbatim @endverbatim
<li>You can use the <a href='http://astyle.sourceforge.net/'>astyle</a> pro - You can use the <a href='http://astyle.sourceforge.net/'>astyle</a> prog
gram to format your code according to these conventions. Use the following ram
options: to format your code according to these conventions. Use the following opti
ons:
@verbatim @verbatim
astyle --style=ansi -tU source.cpp astyle --style=ansi -tU source.cpp
@endverbatim @endverbatim
Note that this command will replace the file source.cpp with the re-formatt Note that this command will replace the file source.cpp with the re-formatt
ed one, and create a backup of the original with the .orig suffix. Also no ed one, and create a backup of the original with the .orig suffix. Also no
te that the -U option (used to un-pad parenthesis) is only available recent te that the -U option (used to un-pad
version of astyle. parenthesis) may not be available in older versions of @c astyle.
</ul>
@section file_names_sec File Names @section file_names_sec File Names
The extensions are .hpp/.cpp for C++ headers/code, .h/.c for C headers/code . 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. F or example class StelFontMgr should be declared in file StelFontMgr.hpp and implemented in StelFontMgr.cpp. C++ files should have the same name and case than the class they contain. F or example class StelFontMgr should be declared in file StelFontMgr.hpp and implemented in StelFontMgr.cpp.
@section comments_sec Doxygen Comments @section comments_sec Doxygen Comments
Stellarium source code should be documented with <a href='http://www.doxyge n.org'>Doxygen</a>. From Doxygen webpage: Stellarium source code should be documented with <a href='http://www.doxyge n.org'>Doxygen</a>. From Doxygen webpage:
skipping to change at line 118 skipping to change at line 136
// Find and return the list of at most maxNbItem objects auto-completing th e // Find and return the list of at most maxNbItem objects auto-completing th e
// passed object I18n name. // passed object I18n name.
QList<QString> listMatchingObjectsI18n(const QString& objPrefix, unsigned i nt maxNbItem=5) const QList<QString> listMatchingObjectsI18n(const QString& objPrefix, unsigned i nt maxNbItem=5) const
{ {
etc.. etc..
@endcode @endcode
@section cpp_code C/C++ Code @section cpp_code C/C++ Code
Use C++ replacement for C functions and %Qt replacements for C++ functions/ STL wherever possible. Use C++ replacement for C functions and %Qt replacements for C++ functions/ STL wherever possible.
<ul> - Use <a href="http://qt-project.org/doc/qt-4.8/qstring.html">QString</a>
<li>Use <a href="http://qt-project.org/doc/qt-4.8/qstring.html">QString</a instead of @c std::string or <tt>char *</tt>
> instead of @c std::string or <tt>char *</tt> - Use <a href="http://qt-project.org/doc/qt-4.8/qiodevice.html">QIODevice<
<li>Use <a href="http://qt-project.org/doc/qt-4.8/qiodevice.html">QIODevic /a>
e</a> instead of C file managment with @c fopen() instead of C file managment with @c fopen()
<li>Pass objects as references when needed instead of using pointers. - Pass objects as references when needed instead of using pointers.
<li>Include standard headers the C++ way, it is more portable: - Include standard headers the C++ way, it is more portable:
@code @code
#include <stdio.h> // Bad #include <stdio.h> // Bad
#include <cstdio> // Good #include <cstdio> // Good
#include <QString> // Good #include <QString> // Good
@endcode @endcode
<li>Use <a href='http://qt-project.org/doc/qt-4.8/containers.html'>Qt cont - Use <a href='http://qt-project.org/doc/qt-4.8/containers.html'>Qt contai
ainers</a> instead of STL ones. They are easier to use, allow for the forea ners</a> instead of STL ones. They are easier to use, allow for the foreach
ch keyword. Only if speed is really critical, use STL containers such as @c keyword. Only if speed is really critical, use STL containers such as @c s
std::vector or @c std::map, they are extremely efficient. Documentation is td::vector or @c std::map, they are extremely efficient. Documentation is <
<a href='http://www.sgi.com/tech/stl/'>there</a>. a href='http://www.sgi.com/tech/stl/'>there</a>.
<li>Avoid public global function and variable. Encapsulate them in classes - Avoid public global functions and variables. Encapsulate them in classes
or namespaces as static members/variable. or namespaces as static members/variables.
<li>Avoid using C macro, use static const variables instead. It is safer b - Avoid using C macros, use <tt>static const</tt> variables instead.
ecause it is type safe. It is safer because it is type safe.
@code @code
#define RADIUS 12 // Bad #define RADIUS 12 // Bad
static const int RADIUS = 12; // Good static const int RADIUS = 12; // Good
@endcode @endcode
<li>Use stdc++ math functions instead of C ones. There are more portable a nd are also overrided for float, thus may be faster. - Use stdc++ math functions instead of C ones. There are more portable and are also overrided for float, thus may be faster.
@code @code
double cosLat = cos(lat); // Bad double cosLat = cos(lat); // Bad
double cosLat = std::cos(lat); // Good double cosLat = std::cos(lat); // Good
@endcode @endcode
</ul> </ul>
@section translation_sec Translatable Strings and Console Output @section translation_sec Translatable Strings and Console Output
Translatable strings are translated using the StelTranslator class, which i Translatable strings are translated using the StelTranslator class, which i
s a C++ wrapper around gettext. A string literal can be marked for translat s
ion in with two different macros, <tt>q_()</tt> and <tt>N_()</tt>, and you a C++ wrapper around <a href="http://www.gnu.org/software/gettext/">gettext
need to pick one for the appropriate purpose: </a>.
- The <tt>q_()</tt> macro takes a string in English and returns the transl A string literal can be marked for translation in with two different macros
ation as a QString using the current global language. This also allows call ,
ing <tt>q_()</tt> with a QString parameter to return a translation. @c q_() or @c N_() , and you need to pick one for the appropriate purpose:
- When a string literal needs to be marked for translation without returni - The @c q_() macro takes a string in English and returns the translation
ng a translation, use the <tt>N_()</tt> macro. It returns the original stri as
ng. a QString using the current global language. This also allows calling @c q
_()
with a QString parameter to return a translation.
- When a string literal needs to be marked for translation without returni
ng
a translation, use the @c N_() macro. It returns the original string.
Several guidelines: Several guidelines:
- Translatable text in sources or data files should be written in English, encoded in ASCII or UTF-8 if needed. - Translatable text in sources or data files should be written in English, encoded in ASCII or UTF-8 if needed.
- Translatable strings should be modified only if really necessary. Any mo dification to one of them means that all the translators for all the langag es will have to re-translate the new string. - Translatable strings should be modified only if really necessary. Any mo dification to one of them means that all the translators for all the langag es will have to re-translate the new string.
This also means that new strings should be chosen carefully, to avoid the need to modify them later. This also means that new strings should be chosen carefully, to avoid the need to modify them later.
- Do not concatenate strings, use <tt>QString::arg()</tt> instead. Concate nated strings are very hard (or even impossible) to translate. - Do not concatenate strings, use @c QString::arg() instead. Concatenated strings are very hard (or even impossible) to translate.
@code @code
text << q_("Distance: ") << distance << q_("AU"); // Bad text << q_("Distance: ") << distance << q_("AU"); // Bad
text = q_("Distance: %1AU").arg(distance); // Good text = q_("Distance: %1AU").arg(distance); // Good
@endcode @endcode
- Translatable text should obey English typographic conventions. For examp le, there should be no space before the colon: - Translatable text should obey English typographic conventions. For examp le, there should be no space before the colon:
@code @code
QString myTranslatedText(q_("Distance of the planet :")); // Bad QString myTranslatedText(q_("Distance of the planet :")); // Bad
QString myTranslatedText(q_("Distance of the planet:")); // Good QString myTranslatedText(q_("Distance of the planet:")); // Good
@endcode @endcode
- In general no translated text should be output on the console because th ere are problems when string and wstring are output on the same console. Th is means that you should never use wcout, wcerr or wprintf(). Console outpu t should be used for informations, errors and warnings which are not requir ed by the user in nominal use. - In general no translated text should be output on the console because th ere are problems when string and wstring are output on the same console. Th is means that you should never use wcout, wcerr or wprintf(). Console outpu t should be used for informations, errors and warnings which are not requir ed by the user in nominal use.
skipping to change at line 180 skipping to change at line 206
- @b Important: When using %Qt format strings, if a letter follows a digit immediately, xgettext might erroneously mark the extracted string as a C f ormat string. <em>Depending on the actual translation, this might cause err ors when uploading the message catalog to Rosetta, or when compiling it to binary format.</em> To prevent this, add an <tt>xgettext:no-c-format</tt> c omment to the line preceding the format string: - @b Important: When using %Qt format strings, if a letter follows a digit immediately, xgettext might erroneously mark the extracted string as a C f ormat string. <em>Depending on the actual translation, this might cause err ors when uploading the message catalog to Rosetta, or when compiling it to binary format.</em> To prevent this, add an <tt>xgettext:no-c-format</tt> c omment to the line preceding the format string:
@code @code
// xgettext:no-c-format // xgettext:no-c-format
text = q_("Distance: %1AU").arg(distance); text = q_("Distance: %1AU").arg(distance);
@endcode @endcode
- You can add clarifying remarks for the translators by adding a special c omment before the line marking the string. They will be automatically extra cted and visible in the .po files and in the web interface: - You can add clarifying remarks for the translators by adding a special c omment before the line marking the string. They will be automatically extra cted and visible in the .po files and in the web interface:
@code @code
// TRANSLATORS: Message displayed when an error occurs. // TRANSLATORS: Message displayed when an error occurs.
QString errorMessage(q_("Loading failed.")); QString errorMessage(q_("Loading failed."));
@endcode @endcode
- User-visible strings in %Qt <tt>.ui</tt> files (used for GUI windows) ar e marked for translation, unless the "translate" flag is unchecked. Note th at these strings are actually extracted from the files generated by the .ui file compiler (uic) during compilation, and not from the .ui files themsel ves, so translation comments in the .ui files will be ignored. - User-visible strings in %Qt <tt>.ui</tt> files (used for GUI windows) ar e marked for translation, unless the "translate" flag is unchecked. Note th at these strings are actually extracted from the files generated by the <tt >.ui</tt> file compiler (@c uic) during compilation, and not from the <tt>. ui</tt> files themselves, so translation comments in the <tt>.ui</tt> files will be ignored.
- When creating a <tt>.ui</tt> file with a new QWidget, %Qt Designer/Qt Cr eator sets the widget's @c windowTitle property to "Form", which then appea rs in translation templates and puzzles translators. It needs to be manuall y reset to an empty string. - When creating a <tt>.ui</tt> file with a new QWidget, %Qt Designer/Qt Cr eator sets the widget's @c windowTitle property to "Form", which then appea rs in translation templates and puzzles translators. It needs to be manuall y reset to an empty string.
- Stellarium also supports <a href='http://www.gnu.org/software/gettext/ma nual/gettext.html#Contexts'>gettext contexts</a> for the cases when identic al English strings are used in different places with different meanings and therefore need to have different translations. Contexts are short strings used to indicate the difference both to the program and the people making t he translations. - Stellarium also supports <a href='http://www.gnu.org/software/gettext/ma nual/gettext.html#Contexts'>gettext contexts</a> for the cases when identic al English strings are used in different places with different meanings and therefore need to have different translations. Contexts are short strings used to indicate the difference both to the program and the people making t he translations.
- In <tt>.ui</tt> files, for every property that holds a user-visible st ring, there's a "disambiguation" sub-property that can be used to indicate the context. It will be extracted together with the message (see above). - In <tt>.ui</tt> files, for every property that holds a user-visible st ring, there's a "disambiguation" sub-property that can be used to indicate the context. It will be extracted together with the message (see above).
- The <tt>qc_()</tt> macro can be used in the cases when context needs t o be handled in the code itself. It is analogous to the <tt>q_()</tt> macro , but with two parameters - the second parameter is the context string. - The <tt>qc_()</tt> macro can be used in the cases when context needs t o be handled in the code itself. It is analogous to the <tt>q_()</tt> macro , but with two parameters - the second parameter is the context string.
*/ */
 End of changes. 12 change blocks. 
76 lines changed or deleted 97 lines changed or added

This html diff was produced by rfcdiff 1.41. The latest version is available from http://tools.ietf.org/tools/rfcdiff/