У меня есть много файлов исходного кода, написанных на разных языках, но ни один из них не имеет стандартного комментария наверху (иногда даже через один и тот же проект). Некоторые из них вообще не имеют комментариев в заголовке: -)
Я думал о создании стандартного шаблона, который я могу использовать в начале моих исходных файлов, и задавался вопросом, какие поля я должен включать.
Я знаю, что хочу включить мое имя и краткое описание того, что содержит/делает файл. Должен ли я включать дату создания? Дата последнего изменения? Программист, который в последний раз модифицировал файл? Какие другие области вы считаете полезными?
Любые советы и комментарии приветствуются.
Спасибо,
Кэмерон
Дата создания, изменение даты и автор, который в последний раз изменил файл, должны быть сохранены в вашем программном обеспечении для управления версиями.
Обычно я помещаю:
Это, кажется, умирающая практика.
Некоторые люди здесь, в StackOverflow, вообще не комментируют комментарии кодов (рассуждение о том, что код должен быть написан как самоочевидный). Хотя я не стал бы так далеко, некоторые из точек антикоммунистической толпы имеют смысл, например факт, что комментарии, как правило, устарели.
Заголовки комментариев больше страдают от этих симптомов. У каждой организации, с которой я был, были эти блоки заголовков, они устарели. У них есть имя автора какого-то парня, который даже не работает там, описание, которое не соответствует коду вообще (если оно когда-либо было) и последняя измененная дата, которая по сравнению с историей управления версиями, кажется, пропустила его последние дюжины обновлений.
По моему личному мнению, держите комментарии близко к коду. Если вы хотите узнать цель и/или историю файла кода, используйте свою систему контроля версий.
Какие поля вам нужны? Если вам нужно спросить, нужно ли размещать какую-либо информацию там, вам не нужна эта информация. Если вы не навязаны какой-то бюрократической некомпетентностью вашего работодателя, я не понимаю, почему вам следует искать больше информации, чем вы уже чувствуете, должно быть там.\
Вы не упомянули, что используете систему контроля версий, и ваш комментарий в ответе 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.
В большинстве организаций все исходные файлы должны начинаться с легальной рекламы. Если вам действительно повезло, это всего лишь один лайнер, но в большинстве случаев это действительно длинный блок легализации. В результате мало кто когда-либо читал их. Наш глаз просто переходит к первому программному элементу, а затем переходит к его документации.
Итак, если вы хотите что-либо написать, напишите его в сочетании с самым верхним программным элементом, а не с файлом.
Любая другая бухгалтерская информация обычно должна быть частью вашего контроля версий, а не поддерживать (плохо) в самом файле.
В дополнение к комментарию выше заявляющей лицензии, к проекту, к которому он принадлежит, и т.д. Я также склоняюсь также к "странным" требованиям наверху (например, "построен с версией X библиотеки Y" ), поэтому вы, или человек, который подбирает его после того, как вы не измените то, на что программа полагается, не осознавая этого (или, если они это сделают, они, по крайней мере, будут знать, что изменить).
Еще в 2002 году, когда я был прямо из колледжа, и рабочие места были немногочисленными, и между ними после распада dot-com, я присоединился к сервисной компании, которая раньше создавала программное обеспечение, настроенное для своих клиентов на Java. Мне пришлось сидеть в офисе клиента (который был ветхой комнатой в электрической подстанции, оснащенной АС, чтобы поддерживать работу серверов), разделяя стулья/ПК с другими парнями в команде. Другие инженеры (если я могу назвать их инженерами;) в группе, используемой для внесения изменений ad-hoc в исходный код, скомпилировать файлы и поместить их в производство.
Отчеты о том, что производственные серверы снижаются из-за неудачных попыток копирования файлов на сервер (пропущен файл, который нужно скопировать, резервные копии, потерянные или неправильные файлы, скопированные или не все скопированные файлы) были выполнены с пожимающими плечами (о нет, это так? посмотрим, что случилось, эй, кто изменил то, что недавно...? ummm...).
В те дни, проведя несколько разочаровывающих дней, пытаясь выяснить, кто и что за кодом, я разработал систему для комментариев в списке в заголовке исходного файла, в котором указано следующее:
Спустя два месяца, когда список угрожал оспорить размер исходного кода в файле, у менеджера была яркая идея получить систему контроля исходной версии.
Мне никогда не приходилось добавлять комментарии в заголовки исходных файлов (за исключением уведомлений об авторских правах) в любой компании, с которой я работал. В моей текущей компании все остальное в основном самоочевидно, если посмотреть на код или перейти к системе отчетов об ошибках, которая интегрирована с системой управления версиями версий.
Многое зависит от того, используете ли вы инструмент создания автоматической документации или нет.
Хотя я согласен со многими комментариями, если вы используете JavaDoc или какой-либо другой инструмент для создания документации, который зависит от комментариев, вам, очевидно, нужно будет включить то, что он хочет видеть.
Те полезные поля, которые вы упомянули, хороши. Кто изменил файл и когда.
Ваше программное обеспечение для контроля версий должно допускать встраивание ключевых слов в комментарии. Например, в CVS, $Id $будет разрешать файл, изменение даты/времени и пользователя, который изменил файл. Он будет автоматически обновляться при каждой регистрации.
Включите следующую информацию:
Вещи, которые вы должны не включать
Вы можете - и должны - получить его через систему управления версиями, где она постоянно и автоматически обновляется. Не говоря уже о том, что большинство из этих пунктов просто бесполезны.
Кто создал файл Когда он был создан Кто изменил это в последний раз Когда это было последнее изменение Что было добавлено последней модификацией