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.
@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 '&egrav e;' or '&ouml;' are not portable when hard-coded. Gettext translated string s 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().
skipping to change at line 146 skipping to change at line 144
@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 StelTranslator class, which i Translatable strings are translated using the StelTranslator class, which i
s a C++ wrapper around gettext. The strings should be marked using the <tt> s a C++ wrapper around gettext. A string literal can be marked for translat
q_()</tt> macro: it takes a QString in English and returns the translation ion in with two different macros, <tt>q_()</tt> and <tt>N_()</tt>, and you
as a QString using the current global language. Note that you can also call need to pick one for the appropriate purpose:
q_() with a QString object to return a translation. In cases when a string - The <tt>q_()</tt> macro takes a string in English and returns the transl
literal needs to be marked for translation without returning a string, use ation as a QString using the current global language. This also allows call
the N_() macro. ing <tt>q_()</tt> with a QString parameter to return a translation.
- When a string literal needs to be marked for translation without returni
<ul> ng a translation, use the <tt>N_()</tt> macro. It returns the original stri
<li>Translatable text in sources or data files should be written in English ng.
, encoded in ASCII or UTF-8 if needed.
<li>Do not concatenate strings, use <tt>QString::arg()</tt> instead. Concat Several guidelines:
enated strings are very hard (or even impossible) to translate. - Translatable text in sources or data files should be written in English,
@code encoded in ASCII or UTF-8 if needed.
text << q_("Distance: ") << distance << q_("AU"); // Bad - Translatable strings should be modified only if really necessary. Any mo
text = q_("Distance: %1AU").arg(distance); // Good dification to one of them means that all the translators for all the langag
@endcode es will have to re-translate the new string.
<li>When using %Qt format strings, if a letter follows a digit immediately, This also means that new strings should be chosen carefully, to avoid the
xgettext might erroneously mark the extracted string as a C format string. need to modify them later.
''Depending on the actual translation, this might cause errors when upload - Do not concatenate strings, use <tt>QString::arg()</tt> instead. Concate
ing the message catalog to Rosetta, or when compiling it to binary format.' nated strings are very hard (or even impossible) to translate.
' 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 text << q_("Distance: ") << distance << q_("AU"); // Bad
text = q_("Distance: %1AU").arg(distance); text = q_("Distance: %1AU").arg(distance); // Good
@endcode @endcode
- Translatable text should obey English typographic conventions. For examp
<li>Translatable text should obey English typographic conventions. For exam le, there should be no space before the colon:
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
- 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.
- Errors and warnings should be output in the stderr file, not stdout. [OB
SOLETE? We use qDebug() and qWarning() now.]
@code
std::cout << "Error while opening file " << qPrintable(myFileName) << "." <
< std::endl; // Bad
std::cerr << "Error while opening file " << qPrintable(myFileName) << "." <
< std::endl; // Good
@endcode
<li>You can add clarifying comments for the translators. They will be autom Further technical notes and tips:
atically extracted and visible in the .po files and in the web interface: - @b Important: When using %Qt format strings, if a letter follows a digit
\code 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
// xgettext:no-c-format
text = q_("Distance: %1AU").arg(distance);
@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:
@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
<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>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.
@code
std::cout << "Error while opening file " << qPrintable(myFileName) << "."
<< std::endl; // Bad
std::cerr << "Error while opening file " << qPrintable(myFileName) << "."
<< std::endl; // Good
@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.
- 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.
- 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.
*/ */
 End of changes. 9 change blocks. 
56 lines changed or deleted 74 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/