Я один из тех разработчиков, которые думают, что написанный код должен быть понятен и читать как книга.
ОДНАКО, при разработке кода библиотеки для использования другими людьми, я стараюсь помещать как можно больше документации в файлы заголовков; что поднимает вопрос: стоит ли документировать методы, которые не являются публичными, даже времени? Они не будут использовать их напрямую, на самом деле, они не могут. В то же время, если я распространю необработанный код (хотя и неохотно), эти не-публичные методы будут видны и, возможно, потребуют объяснения.
Просто ищите некоторые стандарты и практики, которые вы все видите или используете в своих путешествиях.
источник
Хорошо, я добавляю свой способ комментирования / документирования тоже к картинке для разнообразия. Обоснование состоит в том, что я избегаю описания функций или функций-членов, которые объявлены там только в заголовке. С одной стороны, я боюсь добавить слишком много шума в заголовок. С другой стороны, документация вместе с определением проще для сопровождающего. Doxygen не волнует ни один из способов, и он может отфильтровывать ряды при необходимости.
В заголовке класса:
В коде реализации класса:
В заголовке шаблона:
источник
В
private:
начале частного раздела находится вся документация, которая нужна пользователям.источник
Документация того стоит, она помогает кратко объяснить варианты использования и истории. Сколько бы код ни говорил само за себя, он не может объяснить бизнес так легко, как несколько строк истории. Код определенно потребует от пользователя следовать логике в дополнение, чтобы понять, что происходит. :-) Мои 2 цента ...
источник
Определенно!
Этот код должен быть самодокументированным - это лозунг, которым нужно жить. Тем не менее, я бы сказал, что частному коду требуется столько же документации, если не больше, чем общедоступному коду, потому что обычно здесь большинство предположений имеют место просто потому, что кодер предполагает, что он останется в неведении. , Итак, пару месяцев спустя, когда ошибка возникнет у вас на пути, вы потратите время, пытаясь вспомнить, что было написано в коде (возможно, вы сами).
Документация не должна быть там как хороший подарок для других. Документация во всех ее проявлениях (правильно подобранные имена переменных, самодокументируемые имена классов, хорошо организованный код, правильно сегментированные методы и т. Д.) - это подарок для всех, кто может войти в контакт с вашим кодом, включая вас самих.
источник