Issue by TheoVerhelst
Sunday Mar 13, 2016 at 22:56 GMT
Originally opened as https://github.com/ulb-infof209/Group5/issues/98
Another boring thing that is worth remembering when writing code: document your code!
It is more important than we can think at first.
When you declare a class, a method or an attribute, keep in mind that the idea you had in order to implement a part of the project is not necessarily clear for everyone if we just read the code.
I know, that is boring to do at first, and when we manage to know what to do to implement a feature, we don't want to spend time to write docs. But once the code is written, things are working and you're about to commit/push, remember to write a bit of doc in front of your declarations, so that everyone can know what do what in your code.
Okay, if the method is named getHealth, a docstring is not needed. But this is an extreme case, and everything else that is apparently obvious is probably not for someone that never read the code.
Reminder:
/// Class description.
class C
{
public:
/// Method descrption.
/// \param parameter Parameter description.
void method(const ParameterType& parameter);
private:
int _attribute; ///< Attribute description.
};Comments starting by '///` aren't needed elsewhere than in header! They are used only to document declarations, not for internal code (although I maybe write it in code sometimes, in order to stay consistent with other code around).
A detail: when documenting an attribute/enum value, if the line get too long
const std::vector<LongNameBoringToTypeManually>& _myVariableName; ///< A description of what do the variable, the line get very too loooong!
Don't limit yourself in the doc in order to save horizontal space, just write your doc before the line:
/// A description of what do the variable, the line get very too loooong!
/// More detailled description here.
const std::vector<LongNameBoringToTypeManually>& _myVariableName;
Sunday Mar 13, 2016 at 22:56 GMT
Originally opened as https://github.com/ulb-infof209/Group5/issues/98
Another boring thing that is worth remembering when writing code: document your code!
It is more important than we can think at first.
When you declare a class, a method or an attribute, keep in mind that the idea you had in order to implement a part of the project is not necessarily clear for everyone if we just read the code.
I know, that is boring to do at first, and when we manage to know what to do to implement a feature, we don't want to spend time to write docs. But once the code is written, things are working and you're about to commit/push, remember to write a bit of doc in front of your declarations, so that everyone can know what do what in your code.
Okay, if the method is named
getHealth, a docstring is not needed. But this is an extreme case, and everything else that is apparently obvious is probably not for someone that never read the code.Reminder:
Comments starting by '///` aren't needed elsewhere than in header! They are used only to document declarations, not for internal code (although I maybe write it in code sometimes, in order to stay consistent with other code around).
A detail: when documenting an attribute/enum value, if the line get too long
Don't limit yourself in the doc in order to save horizontal space, just write your doc before the line: