Immagino che ciò che sto chiedendo sia: quale sarebbe il modo migliore per assicurarsi che il mio codice sia sufficientemente documentato e formulato in modo che gli altri possano usarlo?
Come open source, i commenti più importanti di tutti sono i commenti sul copyright e sull'accordo di licenza. Piuttosto che un grande commento lungo all'inizio di ogni file, potresti volerne usare uno breve e dolce che specifica brevemente il copyright e rimanda il lettore a license.txt nella directory principale.
So che dovresti sempre commentare tutto e inserirò la funzione @params per ogni metodo, ma ci sono altri suggerimenti in generale?
Commenta tutto? No. Commenta quel codice che ha davvero bisogno di commenti. Commenta con parsimonia. Come potenziale utente di un pezzo di codice, quale delle seguenti due versioni di una definizione di classe preferiresti vedere?
Versione 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; }
...
};
Versione 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; }
...
};
Nella versione A ho documentato tutto, tranne la classe stessa. Una classe in generale non è auto-documentante. I commenti presenti nella versione A sono assolutamente inutili, o addirittura peggio che inutili. Questo è il problema chiave con l'atteggiamento "commenta tutto". Quel piccolo commento conciso sul membro dei dati privati non comunica nulla e i commenti doxygen sul getter hanno un valore negativo. Il getter get_some_name()non ha davvero bisogno di un commento. Cosa fa e cosa restituisce è palesemente ovvio dal codice. Che non c'è setter, devi dedurlo perché non c'è.
Nella versione B ho documentato ciò che deve essere commentato. Il getter non ha un commento doxygen, ma ha un commento che menziona che non c'è setter.
Fai in modo che i tuoi commenti contino e fai attenzione che i commenti spesso non vengono mantenuti per riflettere le modifiche al codice.