Myślę, że pytam, jaki byłby najlepszy sposób, aby upewnić się, że mój kod jest wystarczająco udokumentowany i sformułowany w sposób odpowiedni dla innych osób?
Jako otwarte oprogramowanie najważniejsze są komentarze dotyczące praw autorskich i umów licencyjnych. Zamiast długiego komentarza na początku każdego pliku, możesz użyć krótkiego i słodkiego komentarza, który krótko określa prawa autorskie i odsyła czytelnika do license.txt w katalogu głównym.
Wiem, że zawsze powinieneś komentować wszystko i zamierzam wprowadzić funkcję @params dla każdej metody, ale czy są jeszcze jakieś inne wskazówki?
Skomentować wszystko? Nie. Skomentuj ten kod, który naprawdę wymaga komentarza. Komentuj oszczędnie. Jako potencjalny użytkownik fragmentu kodu, którą z dwóch poniższych wersji definicji klasy wolisz zobaczyć?
Wersja 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; }
...
};
Wersja 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; }
...
};
W wersji A wszystko udokumentowałem - z wyjątkiem samej klasy. Klasa ogólnie nie jest samokontraktowana. Komentarze obecne w wersji A są absolutnie bezużyteczne, a nawet gorsze niż bezużyteczne. To jest kluczowy problem z podejściem „komentuj wszystko”. Ten krótki zwięzły komentarz do prywatnego członka danych niczego nie komunikuje, a komentarze doxygen na temat gettera mają wartość ujemną. Getter get_some_name()tak naprawdę nie potrzebuje komentarza. To, co robi i co zwraca, jest oczywiste z kodu. Że nie ma setera - musisz to wywnioskować, ponieważ go nie ma.
W wersji B udokumentowałem to, co wymaga komentarza. Getter nie ma komentarza doxygen, ale ma komentarz mówiący, że nie ma setera.
Licz swoje komentarze i uważaj, że komentarze często nie są utrzymywane, aby odzwierciedlić zmiany w kodzie.