Je suppose que ce que je demande, c'est quelle serait la meilleure façon de s'assurer que mon code est suffisamment documenté et rédigé correctement pour que d'autres personnes puissent l'utiliser?
En tant qu'open source, les commentaires les plus importants de tous sont les commentaires sur les droits d'auteur et l'accord de licence. Plutôt qu'un long et long commentaire au début de chaque fichier, vous souhaiterez peut-être utiliser un court et doux qui spécifie brièvement les droits d'auteur et renvoie le lecteur à license.txt dans le répertoire racine.
Je sais que vous devriez toujours tout commenter et je vais mettre la fonctionnalité @params pour chaque méthode, mais y a-t-il d'autres conseils en général?
Commenter tout? Non. Commentez ce code qui a vraiment besoin de commentaires. Commentez avec parcimonie. En tant qu'utilisateur potentiel d'un morceau de code, laquelle des deux versions suivantes d'une définition de classe préféreriez-vous voir?
Version A:
class Foo {
private:
SomeType some_name; //!< State machine state
public:
...
/**
* Get the some_name data member.
* @return Value of the some_name data member.
*/
SomeType get_some_name () const { return some_name; }
...
};
Version B:
/**
* A big long comment that describes the class. This class header comment is very
* important, but also is the most overlooked. The class is not self-documenting.
* Why is that class here? Your comments inside the class will say what individual parts
* do, but not what the class as a whole does. For a class, the whole is, or should be,
* greater than the parts. Do not forget to write this very important comment.
*/
class Foo {
private:
/**
* A big long comment that describes the variable. Just because the variable is
* private doesn't mean you don't have to describe it. You might have getters and
* setters for the variable, for example.
*/
SomeType some_name;
public:
...
// Getters and setters
...
// Getter for some_name. Note that there is no setter.
SomeType get_some_name () const { return some_name; }
...
};
Dans la version A, j'ai tout documenté - sauf la classe elle-même. Une classe en général n'est pas auto-documentée. Les commentaires présents dans la version A sont absolument inutiles, voire pires qu'inutiles. C'est le problème clé de l'attitude "commenter tout". Ce petit commentaire laconique sur le membre de données privées ne communique rien, et les commentaires doxygen sur le getter ont une valeur négative. Le getter get_some_name()n'a pas vraiment besoin d'un commentaire. Ce qu'il fait et ce qu'il retourne est clairement évident dans le code. Qu'il n'y a pas de poseur - vous devez inférer cela parce qu'il n'est pas là.
Dans la version B, j'ai documenté ce qui doit être commenté. Le getter n'a pas de commentaire doxygen, mais il a un commentaire mentionnant qu'il n'y a pas de setter.
Faites en sorte que vos commentaires comptent et prenez garde que les commentaires ne sont souvent pas conservés pour refléter les modifications apportées au code.