Документ взят из кэша поисковой машины. Адрес
оригинального документа
: http://astro.uni-altai.ru/~aw/stellarium/api/codingStyle.html
Дата изменения: Unknown Дата индексирования: Fri Feb 28 07:19:33 2014 Кодировка: Поисковые слова: п п п п п п п п п п п п п |
![]() |
Stellarium 0.12.3
|
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.
CoreFactory
).update()
or addElement()
).getSize()
.valueChanged()
). Names of Qt slots should use active verbs to avoid confusion with signals: QMetaObject::connectSlotsByName()
.)packetSize
). This also applies to the formal parameters of methods. Do not use names starting with underscore.[--tab-][--tab-][--tab-]someFunction(param, ... [--tab-][--tab-][--tab-][ spaces ]moreparams, ...);This method will handle different tab widths gracefully.
void MyClass::myMethod(int x) { if (x>10) { cout << "You won." << endl; } }
enums
should follow the Qt conventions. i.e. CamelCase with First letter capitalization for both enum type and enum values. Document with doxygen. The //!< tag can be used to add descriptions on the same line as an enum value, e.g. //! @enum EnumName Here is a description of the enum enum EnumName { EnumValueOne, //!< Some doxygen description of EnumValueOne EnumValueTwo, //!< Some doxygen description of EnumValueTwo EnumValueThree //!< Some doxygen description of EnumValueThree };
astyle --style=ansi -tU source.cppNote that this command will replace the file source.cpp with the re-formatted one, and create a backup of the original with the .orig suffix. Also note that the -U option (used to un-pad parenthesis) may not be available in older versions of
astyle
.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.
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:
Use C++ replacement for C functions and Qt replacements for C++ functions/STL wherever possible.
std::string
or char *
fopen()
std::vector
or std::map
, they are extremely efficient. Documentation is there.static const
variables instead. It is safer because it is type safe. Translatable strings are translated using the StelTranslator class, which is a C++ wrapper around gettext. A string literal can be marked for translation in with two different macros, q_()
or N_()
, and you need to pick one for the appropriate purpose:
q_()
macro takes a string in English and returns the translation as a QString using the current global language. This also allows calling q_()
with a QString parameter to return a translation.N_()
macro. It returns the original string.Several guidelines:
QString::arg()
instead. Concatenated strings are very hard (or even impossible) to translate. Further technical notes and tips:
xgettext:no-c-format
comment to the line preceding the format string: .ui
files (used for GUI windows) are marked for translation, unless the "translate" flag is unchecked. Note that these strings are actually extracted from the files generated by the .ui
file compiler (uic
) during compilation, and not from the .ui
files themselves, so translation comments in the .ui
files will be ignored..ui
file with a new QWidget, Qt Designer/Qt Creator sets the widget's windowTitle
property to "Form", which then appears in translation templates and puzzles translators. It needs to be manually reset to an empty string..ui
files, for every property that holds a user-visible string, there's a "disambiguation" sub-property that can be used to indicate the context. It will be extracted together with the message (see above).qc_()
macro can be used in the cases when context needs to be handled in the code itself. It is analogous to the q_()
macro, but with two parameters - the second parameter is the context string.