Что я должен помещать в комментарии заголовка в верхней части исходных файлов?

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

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

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

Любые советы и комментарии приветствуются.

Спасибо,
Кэмерон

ОТВЕТЫ

Ответ 1

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

Обычно я помещаю:

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

Ответ 2

Это, кажется, умирающая практика.

Некоторые люди здесь, в StackOverflow, вообще не комментируют комментарии кодов (рассуждение о том, что код должен быть написан как самоочевидный). Хотя я не стал бы так далеко, некоторые из точек антикоммунистической толпы имеют смысл, например факт, что комментарии, как правило, устарели.

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

По моему личному мнению, держите комментарии близко к коду. Если вы хотите узнать цель и/или историю файла кода, используйте свою систему контроля версий.

Ответ 3

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

Ответ 4

Вы не упомянули, что используете систему контроля версий, и ваш комментарий в ответе Neil N подтверждает это для вашего старого кода. Хотя использование контроля версий - лучший способ пойти, я также испытал много ситуаций, когда стоимость этого для более старого кода не была оплачена спонсором проекта. Если у вас нет централизованной истории изменений для проекта, тогда историю изменений можно поместить в модули. Хорошо, что вы используете систему управления версиями для своего нового кода.

Your company name
All rights reserved (c) year - or reference to appropriate license

Project or library this file is for

Module it belongs to

Description of what it contains

History
-------
01/08/2010 - Programmer - version
  Initial creation.  
01/09/2010 - Programmer - version
  Change description.
01/10/2010 - Programmer - version
  Change description.

Ответ 5

В большинстве организаций все исходные файлы должны начинаться с легальной рекламы. Если вам действительно повезло, это всего лишь один лайнер, но в большинстве случаев это действительно длинный блок легализации. В результате мало кто когда-либо читал их. Наш глаз просто переходит к первому программному элементу, а затем переходит к его документации.

Итак, если вы хотите что-либо написать, напишите его в сочетании с самым верхним программным элементом, а не с файлом.

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

Ответ 6

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

Ответ 7

Еще в 2002 году, когда я был прямо из колледжа, и рабочие места были немногочисленными, и между ними после распада dot-com, я присоединился к сервисной компании, которая раньше создавала программное обеспечение, настроенное для своих клиентов на Java. Мне пришлось сидеть в офисе клиента (который был ветхой комнатой в электрической подстанции, оснащенной АС, чтобы поддерживать работу серверов), разделяя стулья/ПК с другими парнями в команде. Другие инженеры (если я могу назвать их инженерами;) в группе, используемой для внесения изменений ad-hoc в исходный код, скомпилировать файлы и поместить их в производство.

  • Невозможно понять, кто сделал какие изменения.
  • Невозможно понять, почему было сделано какое-либо изменение.
  • Невозможно перейти к предыдущей версии кода, если инженер не запомнил, что он изменил.
  • Резервное копирование: копирование файлов с рабочего сервера, которые были заменены новыми файлами.
  • Местоположение резервной копии: домашний каталог инженера, копирующего файлы на рабочий сервер.

Отчеты о том, что производственные серверы снижаются из-за неудачных попыток копирования файлов на сервер (пропущен файл, который нужно скопировать, резервные копии, потерянные или неправильные файлы, скопированные или не все скопированные файлы) были выполнены с пожимающими плечами (о нет, это так? посмотрим, что случилось, эй, кто изменил то, что недавно...? ummm...).

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

  • Дата внесения изменений
  • Кто внес изменения
  • Почему было сделано изменение

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

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

Ответ 8

Многое зависит от того, используете ли вы инструмент создания автоматической документации или нет.

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

Ответ 9

Те полезные поля, которые вы упомянули, хороши. Кто изменил файл и когда.

Ваше программное обеспечение для контроля версий должно допускать встраивание ключевых слов в комментарии. Например, в CVS, $Id $будет разрешать файл, изменение даты/времени и пользователя, который изменил файл. Он будет автоматически обновляться при каждой регистрации.

Ответ 10

Включите следующую информацию:

  • Что этот файл для. Это очень полезная часть знаний, и это важнее всего. Вы должны сказать читателю, почему есть такой файл, почему вы группировали функции в отдельный файл/пакет/модуль и почему они используются. Может быть, кратко, одна или две строки, но это должно быть там.
  • Правовые материалы, если это возможно.
  • Оставьте место для специальных команд консольных редакторов, таких как Emacs.
  • Добавьте специальные команды, которые требуется вашей системе автодокументации.

Вещи, которые вы должны не включать

  • Кто создал файл
  • Когда он был создан
  • Кто изменил его в последний раз
  • Когда он был последним изменен
  • Что было добавлено последней модификацией

Вы можете - и должны - получить его через систему управления версиями, где она постоянно и автоматически обновляется. Не говоря уже о том, что большинство из этих пунктов просто бесполезны.

Ответ 11

Кто создал файл Когда он был создан Кто изменил это в последний раз Когда это было последнее изменение Что было добавлено последней модификацией