codingConventions.doxygen   codingConventions.doxygen 
skipping to change at line 23 skipping to change at line 23
* GNU General Public License for more details. * GNU General Public License for more details.
* *
* 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 @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.
Settings for <a href="http://qt-project.org/doc/qtcreator-2.8/index.html">Q
tCreator</a> IDE you can get <a href="http://www.stellarium.org/files/ide/s
tellarium-ide.xml">here</a> (or <a href="http://www.stellarium.org/files/id
e/stellarium-ide.xml.tgz">TGZ archive</a> for it).
@section stylistic_conventions_sec Stylistic Conventions @section stylistic_conventions_sec Stylistic Conventions
- Source code should use the ASCII character set. Characters such as '&egr ave;' - Source code should use the ASCII character set. Characters such as '&egr ave;'
or '&ouml;' are not portable when hard-coded. Gettext translated strings s hould or '&ouml;' are not portable when hard-coded. Gettext translated strings s hould
be used for text using such characters. be used for text using such characters.
- Variable names and comments should be in English. - Variable names and comments should be in English.
- Class names are nouns, in mixed-case, with an initial upper-case letter and - Class names are nouns, in mixed-case, with an initial upper-case letter and
the first letter of each subsequent word capitalized (e.g. @c CoreFactory) . the first letter of each subsequent word capitalized (e.g. @c CoreFactory) .
- Method names are verbs or nouns in mixed-case, starting with a lower-cas e - Method names are verbs or nouns in mixed-case, starting with a lower-cas e
letter (e.g. @c update() or @c addElement()). letter (e.g. @c update() or @c addElement()).
- Names of methods that return a value should start with a suitable verb, - Names of methods that return a value should start with a suitable verb,
skipping to change at line 136 skipping to change at line 140
// 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.
- Use <a href="http://qt-project.org/doc/qt-4.8/qstring.html">QString</a> - Use <a href="http://qt-project.org/doc/qt-5.1/qtcore/qstring.html">QStri ng</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< /a> - Use <a href="http://qt-project.org/doc/qt-5.1/qtcore/qiodevice.html">QIO Device</a>
instead of C file managment with @c fopen() instead of C file managment with @c fopen()
- Pass objects as references when needed instead of using pointers. - Pass objects as references when needed instead of using pointers.
- 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
- Use <a href='http://qt-project.org/doc/qt-4.8/containers.html'>Qt contai ners</a> instead of STL ones. They are easier to use, allow for the foreach keyword. Only if speed is really critical, use STL containers such as @c s td::vector or @c std::map, they are extremely efficient. Documentation is < a href='http://www.sgi.com/tech/stl/'>there</a>. - Use <a href='http://qt-project.org/doc/qt-5.1/qtcore/containers.html'>Qt containers</a> instead of STL ones. They are easier to use, allow for the foreach keyword. Only if speed is really critical, use STL containers such as @c std::vector or @c std::map, they are extremely efficient. Documentati on is <a href='http://www.sgi.com/tech/stl/'>there</a>.
- Avoid public global functions and variables. Encapsulate them in classes or namespaces as static members/variables. - Avoid public global functions and variables. Encapsulate them in classes or namespaces as static members/variables.
- Avoid using C macros, use <tt>static const</tt> variables instead. - Avoid using C macros, use <tt>static const</tt> variables instead.
It is safer because 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
- Use stdc++ math functions instead of C ones. There are more portable and 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>
@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 s Translatable strings are translated using the StelTranslator class, which i s
a C++ wrapper around <a href="http://www.gnu.org/software/gettext/">gettext </a>. a C++ wrapper around <a href="http://www.gnu.org/software/gettext/">gettext </a>.
A string literal can be marked for translation in with two different macros , A string literal can be marked for translation in with two different macros ,
@c q_() or @c N_() , and you need to pick one for the appropriate purpose: @c q_() or @c N_() , and you need to pick one for the appropriate purpose:
- The @c q_() macro takes a string in English and returns the translation as - The @c q_() macro takes a string in English and returns the translation as
a QString using the current global language. This also allows calling @c q _() a QString using the current global language. This also allows calling @c q _()
with a QString parameter to return a translation. with a QString parameter to return a translation.
skipping to change at line 207 skipping to change at line 210
@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 <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. - 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 <a href="http://qt-project. org/doc/qt-5.1/qtwidgets/qwidget.html">QWidget</a>, %Qt Designer/Qt Creator sets the widget's @c windowTitle property to "Form", which then appears in translation templates and puzzles translators. It needs to be manually res et 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. 8 change blocks. 
5 lines changed or deleted 11 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/