codingConventions.doxygen   codingConventions.doxygen 
skipping to change at line 24 skipping to change at line 24
* *
* You should have received a copy of the GNU General Public License * You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software * along with this program; if not, write to the Free Software
* 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
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> <ul>
<li>Source code should use ASCII character set. Characters such as 'é' or 'ö' are not portable when hard-coded. Gettext translated strings should be used for such characters. <li>Source code should use ASCII character set. Characters such as '&egrav e;' or '&ouml;' are not portable when hard-coded. Gettext translated string s should be used for such characters.
<li>Variable names and comments should be in English. <li>Variable names and comments should be in English.
<li>Class names are nouns, in mixed-case, with an initial upper-case <li>Class names are nouns, in mixed-case, with an initial upper-case
letter and the first letter of each subsequent word capitalized (e.g. CoreF actory). letter and the first letter of each subsequent word capitalized (e.g. CoreF actory).
<li>Method names are verbs or nouns in mixed-case, starting with a lower-c ase letter (e.g. update() or addElement()). <li>Method names are verbs or nouns in mixed-case, starting with a lower-c ase letter (e.g. update() or addElement()).
<li>Methods that return a value should take the form getSize(). <li>Methods that return a value should take the form getSize().
<li>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 parame ters of methods. Do not use names starting with underscore. <li>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 parame ters of methods. Do not use names starting with underscore.
<li>The names of macro or static const should be all upper-case words, sep arated by underscore: <li>The names of macro or static const should be all upper-case words, sep arated 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";
skipping to change at line 63 skipping to change at line 65
cout << "You won." << endl; cout << "You won." << endl;
} }
} }
@endcode @endcode
<li>Use blank lines as follows: <li>Use blank lines as follows:
<ul> <ul>
<li>1 between methods, before (block or single line) comment <li>1 between methods, before (block or single line) comment
<li>1 between logical sections of a method <li>1 between logical sections of a method
<li>2 between sections of a source file <li>2 between sections of a source file
</ul> </ul>
<li>@em enums should follow the QT conventions. i.e. CamelCase with First letter capitalization for both enum type and enum values. Document with do xygen. The <b>//!\< </b>tag can be used to add descriptions on the same lin e as an enum value, e.g. <li>@em enums should follow the %Qt conventions. i.e. CamelCase with Firs t letter capitalization for both enum type and enum values. Document with d oxygen. The <b>//!\< </b>tag can be used to add descriptions on the same li ne as an enum value, e.g.
@verbatim @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
skipping to change at line 117 skipping to change at line 119
@code @code
// 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++ function/ST L wherever possible. Use C++ replacement for C functions and %Qt replacements for C++ functions/ STL wherever possible.
<ul> <ul>
<li>Use <a href="http://doc.trolltech.com/4.4/qstring.html">QString</a> in <li>Use <a href="http://doc.trolltech.com/stable/qstring.html">QString</a>
stead of @c std::string or <tt>char *</tt> instead of @c std::string or <tt>char *</tt>
<li>Use <a href="http://doc.trolltech.com/4.4/qiodevice.html">QIODevice</a <li>Use <a href="http://doc.trolltech.com/stable/qiodevice.html">QIODevice
> instead of C file managment with @c fopen() </a> instead of C file managment with @c fopen()
<li>Pass objects as references when needed instead of using pointers. <li>Pass objects as references when needed instead of using pointers.
<li>Include standard headers the C++ way, it is more portable: <li>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://doc.trolltech.com/4.4/containers.html'>Qt containe rs</a> instead of STL ones. They are easier to use, allow for the foreach k eyword. Only if speed is really critical, use STL containers such as @c std ::vector or @c std::map, they are extremely efficient. Documentation is <a href='http://www.sgi.com/tech/stl/'>there</a>. <li>Use <a href='http://doc.trolltech.com/stable/containers.html'>Qt conta iners</a> instead of STL ones. They are easier to use, allow for the foreac h keyword. Only if speed is really critical, use STL containers such as @c std::vector or @c std::map, they are extremely efficient. Documentation is <a href='http://www.sgi.com/tech/stl/'>there</a>.
<li>Avoid public global function and variable. Encapsulate them in classes or namespaces as static members/variable. <li>Avoid public global function and variable. Encapsulate them in classes or namespaces as static members/variable.
<li>Avoid using C macro, use static const variables instead. It is safer b ecause it is type safe. <li>Avoid using C macro, use static const variables instead. It is safer b ecause 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. <li>Use stdc++ math functions instead of C ones. There are more portable a nd 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 Translator class, which is a C++ wrapper around gettext. The strings should be marked using the <tt>q_() </tt> macro: it takes a QString in English and returns the translation as a QString using the current global language. Translatable strings are translated using the StelTranslator class, which i s a C++ wrapper around gettext. The strings should be marked using the <tt> q_()</tt> 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.
<ul> <ul>
<li>Translatable text in sources or data files should be written in English , encoded in ASCII or UTF-8 if needed. <li>Translatable text in sources or data files should be written in English , encoded in ASCII or UTF-8 if needed.
<li>Do not concatenate strings, use <tt>QString::arg()</tt> instead. Concat enated strings are very hard (or even impossible) to translate. <li>Do not concatenate strings, use <tt>QString::arg()</tt> instead. Concat enated 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
<li>When using Qt format strings, if a letter follows a digit immediately, xgettext might erroneously mark the extracted string as a C format string. ''Depending on the actual translation, this might cause errors when uploadi ng the message catalog to Rosetta, or when compiling it to binary format.'' To prevent this, add an <tt>xgettext:no-c-format</tt> comment to the line preceding the format string: <li>When using %Qt format strings, if a letter follows a digit immediately, xgettext might erroneously mark the extracted string as a C format string. ''Depending on the actual translation, this might cause errors when upload ing the message catalog to Rosetta, or when compiling it to binary format.' ' To prevent this, add an <tt>xgettext:no-c-format</tt> comment 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
<li>Translatable text should obey English typo conventions. For example, th ere should be no space before the colon: <li>Translatable text should obey English typographic conventions. For exam ple, 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
<li>You can add clarifying comments for the translators. They will be autom
atically extracted and visible in the .po files and in the web interface:
\code
// TRANSLATORS: Message displayed when an error occurs.
QString errorMessage(q_("Loading failed."));
\endcode
<li>Strings in %Qt .ui files (used for GUI windows) are marked for translat
ion, unless the "translate" flag is unchecked. Note that these strings are
actually extracted from the files generated by the .ui file compiler (uic),
and not from the .ui files themselves, so translation comments in the .ui
files will be ignored.
<li>Translatable strings should be modified only if really necessary. Any m odification to one of them means that all the translators for all the langa ges will have to re-translate the new string. <li>Translatable strings should be modified only if really necessary. Any m odification to one of them means that all the translators for all the langa ges will have to re-translate the new string.
<li>In general no translated text should be output on the console because t here are problems when string and wstring are output on the same console. T his means that you should never use wcout, wcerr or wprintf(). Console outp ut should be used for informations, errors and warnings which are not requi red by the user in nominal use. <li>In general no translated text should be output on the console because t here are problems when string and wstring are output on the same console. T his means that you should never use wcout, wcerr or wprintf(). Console outp ut should be used for informations, errors and warnings which are not requi red by the user in nominal use.
<li>Errors and warnings should be output in the stderr file, not stdout. <li>Errors and warnings should be output in the stderr file, not stdout.
@code @code
std::cout << "Error while opening file " << qPrintable(myFileName) << "." << std::endl; // Bad std::cout << "Error while opening file " << qPrintable(myFileName) << "." << std::endl; // Bad
std::cerr << "Error while opening file " << qPrintable(myFileName) << "." << std::endl; // Good std::cerr << "Error while opening file " << qPrintable(myFileName) << "." << std::endl; // Good
@endcode @endcode
*/ */
 End of changes. 10 change blocks. 
11 lines changed or deleted 26 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/