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

Question

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

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

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

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

Спасибо
Cameron

Answer 1

Это похоже на умирающую практику.

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

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

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

Answer 2

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

Я обычно ставлю:

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

Answer 3

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

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

Answer 4

В 2002 году, когда я окончил колледж, а после краха доткомов было мало рабочих мест, я присоединился к сервисной компании, которая создавала программное обеспечение для своих клиентов на Java. Я должен был сидеть в офисе клиента (это была ветхая комната на электрической подстанции, оснащенной AC для обеспечения работы серверов), делясь стульями / компьютерами с другими парнями в команде. Другие инженеры (если я могу назвать их инженерами;) в группе, которые делали изменения в исходном коде ad-hoc, компилировали файлы и запускали их в производство.

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

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

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

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

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

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

Answer 5

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

Answer 6

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

Поэтому, если вы хотите что-то написать, напишите это в связи с верхним элементом программы, а не с файлом.

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

Answer 7

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

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.

Answer 8

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

Answer 9

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

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

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

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

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

Answer 10

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

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