Я думаю, что я спрашиваю, что было бы лучшим способом убедиться, что мой код достаточно документирован и сформулирован правильно для использования другими людьми?
Что касается открытого исходного кода, наиболее важными комментариями являются комментарии об авторском праве и лицензионном соглашении. Вместо большого длинного комментария в начале каждого файла вы можете использовать короткий и приятный комментарий, который кратко определяет авторские права и направляет читателя в файл license.txt в корневом каталоге.
Я знаю, что вы всегда должны комментировать все, и я собираюсь добавить функцию @params для каждого метода, но есть ли какие-либо другие советы в целом?
Комментировать все? Нет. Комментируйте тот код, который действительно нуждается в комментариях. Комментарий экономно. Как потенциальный пользователь куска кода, какую из следующих двух версий определения класса вы бы предпочли увидеть?
Версия А:
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; }
...
};
Версия Б:
/**
* 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 я задокументировал все - кроме самого класса. Класс вообще не самодокументируется. Комментарии, которые присутствуют в версии A, абсолютно бесполезны или даже хуже, чем бесполезны. Это ключевая проблема с отношением «комментировать все». Этот небольшой краткий комментарий о члене с закрытыми данными ничего не сообщает, а комментарии о кислороде для получателя имеют отрицательное значение. Получатель get_some_name()не нуждается в комментариях. Что он делает и что возвращает, очевидно из кода. Что нет сеттера - вы должны сделать вывод, что его там нет.
В версии B я задокументировал то, что требует комментариев. Получатель не имеет комментария doxygen, но в нем есть комментарий, в котором говорится, что нет установщика.
Сделайте так, чтобы ваши комментарии учитывались, и помните, что комментарии часто не поддерживаются, чтобы отразить изменения в коде.