Что я должен поместить в комментарии заголовка в верхней части исходных файлов?
У меня есть много файлов исходного кода, написанных на разных языках, но ни один из них не имеет стандартного комментария вверху (иногда даже в одном и том же проекте). У некоторых из них вообще нет комментариев к заголовкам:-)
Я думал о создании стандартного шаблона, который мог бы использовать в верхней части моих исходных файлов, и мне было интересно, какие поля мне следует включить.
Я знаю, что хочу указать свое имя и краткое описание того, что файл содержит / делает. Должен ли я также включить дату создания? Дата последнего изменения? Программист, кто последний раз изменял файл? Какие еще поля вы считаете полезными?
Любые советы и комментарии приветствуются.
Спасибо,
Cameron
12 ответов
Дата создания, дата изменения и автор, который последним изменил файл, должны быть сохранены в вашем программном обеспечении для контроля версий.
Я обычно ставлю:
- Основное назначение файла и вещей внутри файла.
- Проект / модуль, к которому принадлежит файл.
- Лицензия, связанная с файлом (и файлом LICENSE в корне проекта).
- Кто отвечает за файл (команда, человек или оба)
Это похоже на умирающую практику.
Некоторые люди здесь, в Stackru, вообще против комментариев к коду (полагая, что код должен быть написан так, чтобы он был самоочевидным). Хотя я бы не стал заходить так далеко, некоторые моменты толпы антикомментариев имеют смысл, например, тот факт, что комментарии как правило, устарели.
Заголовочные блоки комментариев страдают от этих симптомов в еще большей степени. У каждой организации, с которой я был, были эти блоки заголовков, они устарели. У них есть имя автора какого-то парня, который там даже больше не работает, описание, которое вообще не соответствует коду (при условии, что оно когда-либо было), и дата последнего изменения, которая когда-то по сравнению с историей контроля версий, кажется, пропустила его последние десятки обновлений.
По моему личному мнению, оставляйте комментарии близко к коду. Если вы хотите узнать назначение и / или историю файла кода, используйте свою систему контроля версий.
В 2002 году, когда я окончил колледж, а после краха доткомов было мало рабочих мест, я присоединился к сервисной компании, которая создавала программное обеспечение, адаптированное для своих клиентов на Java. Я должен был сидеть в офисе клиента (это была ветхая комната на электрической подстанции, оснащенной AC для обеспечения работы серверов), делясь стульями / компьютерами с другими парнями в команде. Другие инженеры (если я могу назвать их инженерами;) в группе использовали для временных изменений исходный код, компилировали файлы и запускали их в производство.
- Нет способа выяснить, кто сделал какие изменения.
- Нет способа выяснить, почему были внесены какие-либо изменения.
- Невозможно перейти к предыдущей версии кода, если инженер не "вспомнил", что он модифицировал.
- Резервное копирование: копирование файлов с рабочего сервера, которые были заменены новыми файлами.
- Расположение резервной копии: Домашний каталог инженера, копирующего файлы на рабочий сервер.
Сообщения об отключении рабочих серверов из-за неудачных попыток копирования файлов на сервер (пропущенный файл для копирования, потерянные резервные копии или копирование неправильных файлов или копирование не всех файлов) были встречены пожиманием плечами (о нет, это не так? давайте посмотрим, что случилось; эй, кто изменил то, что недавно...? ммм...).
В течение этих дней, потратив несколько разочаровывающих дней, пытаясь выяснить, кто и почему стоит за кодом, я разработал систему для комментариев в списке в заголовке исходного файла, в котором подробно описано следующее:
- Дата внесения изменений
- Кто сделал изменения
- Почему было сделано изменение
Два месяца спустя, когда список угрожал оспорить размер исходного кода в файле, у менеджера появилась блестящая идея получить систему контроля версий исходного кода.
Мне никогда не приходилось помещать какие-либо комментарии в заголовки исходных файлов (за исключением уведомлений об авторских правах) ни в одной компании, с которой я работал. В моей нынешней компании все остальное в основном самоочевидно, если посмотреть на код или перейти к системе сообщений об ошибках, которая интегрирована с системой контроля версий исходного кода.
В большинстве организаций все исходные файлы должны начинаться с юридической информации. Если вам действительно повезло, это всего лишь одна строчка, но в большинстве случаев это действительно длинный блок юридического. В результате мало кто когда-либо читал это. Наш взгляд просто переходит к первому элементу программы, а затем переходит к его документации.
Поэтому, если вы хотите что-то написать, напишите это в связи с верхним элементом программы, а не файлом.
Любая другая бухгалтерская информация, как правило, должна быть частью вашего контроля версий, а не храниться (плохо) в самом файле.
Многое зависит от того, используете ли вы инструмент автоматического создания документации или нет.
Хотя я согласен со многими комментариями, если вы используете JavaDoc или какой-либо другой инструмент создания документации, который зависит от комментариев, вам, очевидно, нужно будет включить то, что он хочет увидеть.
Вы не упомянули, что используете систему контроля версий, и ваш комментарий в ответе Нила Н подтверждает это для вашего старого кода. Хотя использование контроля версий - лучший способ, я также сталкивался со многими ситуациями, когда спонсор проекта не оплачивал бы стоимость этого для старого кода. Если у вас нет централизованной истории изменений для проекта, тогда историю изменений можно поместить в модули. Хорошо, что вы используете систему контроля версий для своего нового кода.
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.
Какие поля вам нужны? Если вам нужно спросить, нужно ли поместить туда какую-то информацию, она вам не нужна. Если вас не заставит какая-то бюрократическая некомпетентность вашего работодателя, я не понимаю, почему вы должны искать больше информации, чем, по вашему мнению, должно быть там.\
В дополнение к приведенному выше комментарию с указанием лицензии, проекта, к которому он принадлежит, и т. Д. Я также склонен ставить "странные" требования наверх (например, "построено с версией X библиотеки Y"), чтобы вы или человек, который поднимает это после того, как вы не измените то, на что полагается программа, не осознавая этого (или, если они это сделают, они по крайней мере будут знать, что изменить)
Хотя представлено множество аргументов в пользу отсутствия заголовков файлов, я думаю, что заголовки файлов все еще имеют силу.
Укажите имя модуля/класса/функции и укажите, к какой библиотеке или логическому разделу он принадлежит, и добавьте последнее измененное поле.
Это основные поля, полезные в случаях, когда файл был ошибочно перемещен, переименован и т. д. Дата последнего изменения помогает разработчикам, особенно в тех случаях, когда файл был скопирован в другой проект и его необходимо сравнить с исходным проектом (Git может Помогу тебе в этом).
Пример
/* Notification Log ID Module [Common Notification]
*
* Last updated: August 12, 2023
*/
Если ваша организация требует от вас сохранения уведомления об авторских правах, поместите его в отдельный раздел комментариев под заголовком файла. Разработчикам будет проще свернуть заявление об авторских правах, оставив при этом заголовок файла открытым для чтения.
Включите следующую информацию:
- Для чего этот файл. Это очень полезное знание, и оно важнее всего остального. Вы должны сказать читателю, почему существует такой файл, почему вы сгруппировали функции в отдельный файл / пакет / модуль и почему они используются. Может быть, кратко, одна или две строки, но это должно быть там.
- Юридические вещи, если заявитель.
- Оставьте место для специальных команд консольных редакторов, таких как Emacs.
- Добавьте специальные команды, которые требует ваша система автоматического документирования.
Вещи, которые вы не должны включать,
- Кто создал файл
- Когда он был создан
- Кто изменил это в последний раз
- Когда это было последнее изменение
- Что было добавлено последней модификацией
Вы можете - и должны - получить его через систему контроля версий, где он постоянно и автоматически обновляется. Не говоря уже о том, что большинство этих пунктов просто бесполезны.
Кто создал файл Когда он был создан Кто изменил его в последний раз Когда он был изменен в последний раз Что было добавлено последней модификацией
Те полезные поля, которые вы упомянули, хорошие. Кто изменил файл и когда.
Ваша программа контроля версий должна позволять встраивать ключевые слова в комментарии. Например, в CVS $Id$ будет преобразован в файл, дату и время изменения и пользователя, который изменил файл. Он будет автоматически обновляться при каждой регистрации.