Стандарты Комментирования C

Я работаю с командой под названием the Solar Jackets в Georgia Tech, и у нас был "кризис комментариев". У нас есть много членов, которые заканчивают обучение и оставляют после себя код без комментариев. Я хочу внедрить стандарт комментирования, чтобы этого не произошло, и мне нужны некоторые предложения, чтобы убедиться, что у меня есть все мои базы.

Мне нужна следующая функциональность:

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

  • В самом коде строчное (или близкое к нему) описание.

Есть ли какие-либо предположения о том, что я, возможно, пропустил? Существуют ли какие-либо программы, которые могут автоматически генерировать компиляцию кода? Как я мог сделать это проще для программистов?

4 3
comments commenting

4 ответа:

То, что вы описываете, напоминает мне Доксиген. Он имеет формат для комментирования всех сущностей в коде, включая функции, параметры, переменные... Он может быть использован для обеспечения выполнения всего, что было задокументировано путем проверки предупреждений, генерируемых Doxygen. Он генерирует полный документ из исходного кода в различных форматах, таких как HTML, Latex, PDF,...

Многие IDE знают теги Doxygen и могут быть интегрированы с Doxygen, чтобы помочь разработчику комментировать код.

Вот пример: пример комментария Doxygen: 

/**
 * @brief This function does blah blah.
 * @param test blah blah parameter.
 * @return 0 if blah blah passed.
 */
uint32_t TestFunction( uint32_t test )
{
    return 0;
}
8

  • Внедряйте хорошие навыки кодирования. Имена переменных и заголовки методов должны быть описательными и фокусироваться конкретно на задаче, которую они выполняют. Например, если у вас есть метод для замены двух элементов, достаточно вызвать его swap().

  • Используйте инструменты для создания документов, такие как Doxygen или Sphinx.

  • Рекомендуется использовать другие API, такие как Java 7 API , в качестве руководства для удобства чтения и что делать (или нет делать).

Я должен, вероятно, подчеркнуть, чтослишком много документации может быть чрезвычайно отвлекающим. Пусть программисты, которые являются экспертами в том, что делает их программное обеспечение, дадут обзор высокого уровня ради документации. Если они хотят или должны, то пусть объясняют сложный или запутанный код на своих собственных условиях.
2

Здесь, на моей новой работе, мы стараемся максимально избегать использования комментариев. Код должен быть самодокументированным. Некоторые небольшие комментарии допускаются к сложному коду, исправлениям ошибок и тому подобному, но повседневное программирование вообще не включает комментариев.

Мы используем сеансы проверки кода, чтобы все члены команды могли читать и изучать новый код, и если он не чист и не удобен для чтения, он рефакторизуется. Обычно, включая локальные переменные для именования выражений, не используя переменные повторно и добавляя #defines для постоянные литералы делают свою работу.

1

Строчный комментарий к коду звучит ужасно.

  • Вам нужен комментарий в начале функции, чтобы определить, что она делает.
    • Если параметры etc не очевидны, их следует обсудить.
      • В противном случае она должна быть как можно короче, предпочтительно всего одна строка.
  • Если функция сложна, может быть уместно иметь более широкий комментарий; используйте суждение.
  • обычно требуется комментарий к заголовку файла, содержащий название компании или лицензия на проект и идентификация авторских прав, а также примечание об общей цели файла.
  • Вы должны документировать определенные переменные (которые в основном должны быть переменными static; вы не используете глобалы, не так ли?).
  • Возможно, вам потребуется комментировать абзацы кода внутри функций, предпочтительно с короткими (одна строка) комментариями.
    • Иногда вам нужно задокументировать неочевидное или неясное (возможно, со ссылкой на соответствующий отчет об ошибке).
  • Вы должны редко нуждаться хвост-комментарии, за исключением определений локальных переменных.

    • В противном случае код должен в значительной степени объяснять сам себя, делая комментарии излишними.

    Обратите внимание, что комментарии, которые не описывают текущий код, являются помехой. Только вчера я удалил комментарий, явно добавленный в 1990 году – дата была в комментарии – описывающий статус-кво в 1990 году, когда определенная функция имитировала "переменные аргументы". Код был давно обновлен, так что функция была рассматривается как имеющий 7 фиксированных аргументов; последние четыре могут быть пустыми, когда они не нужны. Таким образом, комментарий был уже не точным, а десятилетним или более. Оно ушло. Почему никто не заметил этого? Вероятно, потому, что никто другой не читал этот файл в первый раз без наставника, который провел бы их мимо ошибочного комментария. Или, возможно, потому, что комментарий был слишком далеко от функции (между комментарием и функцией, которую он неправильно описал, была целая отдельная, хотя и небольшая, функция). Итак, 30 строк (неточного) комментария наконец-то отправились в бит-ведро в небе. Заметьте также, что то, что нужно экспертам и что нужно новичкам для одного и того же фрагмента кода, может быть совершенно различным. Вы должны вынести суждение о том, какой уровень комментариев имеет смысл, но я бы рекомендовал ошибиться на спартанской стороне по поводу эссе, потому что, когда придет время изменить код, одно из двух описаний не будет должным образом поддерживаться, и скорее всего, это будут комментарии, которые не являются таковыми. поддерживается. А вводящие в заблуждение комментарии страшнее для новичков, чем для экспертов! Таким образом, убедитесь, что вы не можете получить комментарии, которые являются неточными, не имея каких-либо предотвратимых комментариев.
    1