Документация по коду: публичный или непубличный?

Я один из тех разработчиков, которые думают, что написанный код должен быть понятен и читать как книга.

ОДНАКО, при разработке кода библиотеки для использования другими людьми, я стараюсь помещать как можно больше документации в файлы заголовков; что поднимает вопрос: стоит ли документировать методы, которые не являются публичными, даже времени? Они не будут использовать их напрямую, на самом деле, они не могут. В то же время, если я распространю необработанный код (хотя и неохотно), эти не-публичные методы будут видны и, возможно, потребуют объяснения.

Просто ищите некоторые стандарты и практики, которые вы все видите или используете в своих путешествиях.

Я бы никогда не подумал об исключении документации для внутренних устройств только потому, что «конечный пользователь» не будет их использовать; поддержка кода - более чем достаточная причина для включения комментариев документации для всех компонентов, особенно для внутренних компонентов, которые, как правило, являются наиболее сложной (и часто меняющейся) частью.

Тем не менее, может существовать обоснованный аргумент в пользу того, чтобы они были ограничены исходным кодом без заголовка (а не публично документированы), чтобы сохранить абстракцию.

Заметьте, все это довольно субъективно.

Хорошо, я добавляю свой способ комментирования / документирования тоже к картинке для разнообразия. Обоснование состоит в том, что я избегаю описания функций или функций-членов, которые объявлены там только в заголовке. С одной стороны, я боюсь добавить слишком много шума в заголовок. С другой стороны, документация вместе с определением проще для сопровождающего. Doxygen не волнует ни один из способов, и он может отфильтровывать ряды при необходимости.

В заголовке класса:

• включены заголовки (почему)
• определения класса всегда (цель и обязанности)
• чистые виртуальные функции всегда (полный контракт)
• встроенные функции, если не требующие пояснения геттеры
• другие объявленные типы, если не требующие пояснений
• члены статических данных (почему)
• другие члены данных, если не говорят сами за себя
• макросы, если таковые имеются (контракт и почему)

В коде реализации класса:

• локальные объявления так же, как в заголовке
• определения функций всегда (полный контракт)
• определения функций-членов всегда (полный контракт или ссылка на корень виртуального переопределения)
• статические переменные определены, если таковые имеются (цель почему)

В заголовке шаблона:

• вышесказанное слилось и
• подходящие / неподходящие типы для аргументов шаблона и
• насколько хорошо определяется пригодность

В private:начале частного раздела находится вся документация, которая нужна пользователям.

Документация того стоит, она помогает кратко объяснить варианты использования и истории. Сколько бы код ни говорил само за себя, он не может объяснить бизнес так легко, как несколько строк истории. Код определенно потребует от пользователя следовать логике в дополнение, чтобы понять, что происходит. :-) Мои 2 цента ...

Определенно!

Этот код должен быть самодокументированным - это лозунг, которым нужно жить. Тем не менее, я бы сказал, что частному коду требуется столько же документации, если не больше, чем общедоступному коду, потому что обычно здесь большинство предположений имеют место просто потому, что кодер предполагает, что он останется в неведении. , Итак, пару месяцев спустя, когда ошибка возникнет у вас на пути, вы потратите время, пытаясь вспомнить, что было написано в коде (возможно, вы сами).

Документация не должна быть там как хороший подарок для других. Документация во всех ее проявлениях (правильно подобранные имена переменных, самодокументируемые имена классов, хорошо организованный код, правильно сегментированные методы и т. Д.) - это подарок для всех, кто может войти в контакт с вашим кодом, включая вас самих.