Я здогадуюсь, що я запитую, який би був найкращий спосіб переконатися, що мій код є достатньо задокументованим та сформульованим правильним для використання іншими людьми?
Як відкритий код, найважливіші зауваження до всіх - коментар щодо авторських прав та ліцензійних угод. Замість великого довгого коментаря на початку кожного файлу, ви можете скористатись коротким та солодким, який коротко визначає авторські права та посилає читача на licenc.txt у кореневому каталозі.
Я знаю, що ви завжди повинні все коментувати, і я буду вводити функцію @params для кожного методу, але чи є ще загальні поради?
Прокоментувати все? Ні. Прокоментуйте той код, який справді потребує коментарів. Коментуйте скупо. Як потенційний користувач шмату коду, яку з наступних двох версій визначення класу ви б хотіли бачити?
Версія 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; }
...
};
Версія 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; }
...
};
У версії A я задокументував все - крім самого класу. Клас взагалі не є самодокументуванням. Коментарі, які є у версії А, абсолютно марні, або навіть гірші, ніж марні. Ось ключова проблема у ставленні "прокоментувати все". Цей невеликий лайливий коментар до члена приватних даних нічого не повідомляє, а коментарі доксигену щодо геттера мають негативне значення. Користувачеві get_some_name()насправді не потрібен коментар. Що він робить і що повертає, очевидно з коду. Що немає сеттера - це потрібно зробити, тому що його там немає.
У версії B я задокументував те, що потрібно коментувати. У геттера немає коментаря доксигену, але в ньому є коментар, в якому йдеться про відсутність сеттера.
Зробіть підрахунок ваших коментарів і будьте обережні, що часто коментарі не підтримуються для відображення змін у коді.