Acho que o que estou perguntando é: qual seria a melhor maneira de garantir que meu código esteja suficientemente documentado e redigido corretamente para que outras pessoas o usem?
Como código aberto, os comentários mais importantes de todos são os comentários sobre direitos autorais e contrato de licença. Em vez de um grande e longo comentário no início de cada arquivo, convém usar um pequeno e doce que especifique brevemente os direitos autorais e encaminhe o leitor para license.txt no diretório raiz.
Eu sei que você sempre deve comentar tudo e eu vou colocar o recurso @params para todos os métodos, mas existem outras dicas em geral?
Comentar tudo? Não. Comente o código que realmente precisa de comentários. Comente com moderação. Como usuário potencial de um pedaço de código, qual das duas versões a seguir de uma definição de classe você prefere ver?
Versão 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; }
...
};
Versão 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; }
...
};
Na versão A, eu documentei tudo - exceto a própria classe. Uma classe em geral não é auto-documentada. Os comentários presentes na versão A são absolutamente inúteis ou até piores que inúteis. Esse é o principal problema com a atitude "comentar tudo". Esse pequeno comentário conciso sobre o membro de dados particulares não comunica nada e os comentários do doxygen no getter têm valor negativo. O getter get_some_name()realmente não precisa de um comentário. O que ele faz e o que retorna é obviamente óbvio no código. Que não existe criador - você deve inferir isso porque não existe.
Na versão B, eu documentei o que precisa ser comentado. O getter não tem um comentário doxygen, mas tem um comentário mencionando que não há nenhum setter.
Faça com que seus comentários sejam importantes e lembre-se de que os comentários muitas vezes não são mantidos para refletir as alterações no código.