Какую информацию разместить в комментариях вверху файла с исходным кодом?

Question

Какую информацию, по вашему мнению, стоит поместить в комментарии в начале файла с исходным кодом?

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

[РЕДАКТИРОВАТЬ] Чтобы уточнить, я не имею в виду комментарии перед классом, но в первых строках файла, перед тем, как включить утверждения и что еще. Как

/**
 * Author:    Name
 * Created:   11.05.2009
 * 
 * (c) Copyright by Blub Corp.
 **/

Answer 1

Что поместить в заголовок файла:

• Библиотека / компонент , исходный код которого является частью
• Авторские права Подробности
• Краткое и содержательное описание класса (ов) в исходном файле

Что НЕ нужно помещать в заголовок файла:

• Все, что дублирует низкоуровневую логику, которая является частью самого кода. Это может привести к проблемам с обслуживанием, если оно не обновляется при изменении исходного кода.

• Имя автора (ов) . Почему?

  • В мире систем контроля версий, хотя может быть первоначальный автор некоторого кода, в конечном итоге владение становится размытым. Это особенно верно, когда код входит в фазу обслуживания жизненного цикла, где владельцы могут регулярно меняться.
  • Весь код в конечном итоге становится «вики сообщества» после достаточного количества изменений; -)
  • Хотели бы вы, чтобы ваше имя ассоциировалось со всем кодом навсегда, прекрасно зная, что вы не будете нести ответственность за код до его смерти?

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

Answer 2

• Copyright
• Автор (ы)
• Лицензия (если она с открытым исходным кодом)
• Однострочная формулировка или описание цели
• Дополнительная документация и примеры использования

Редактировать: Изменено Автор (ы) на Автор (ы)

Answer 3

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

Answer 4

, учитывая все вышеперечисленное, также помещает подробные сведения о назначении кода в этот файл, что также может помочь в отладке и понимании функциональности. Это поможет в сопровождении и поддержке.

Answer 5

Кодировка файла! (UTF-8) * * +1001

# -*- encoding: utf-8 -*-

Особенно, если вы планируете в какой-то момент поделиться своим кодом с кем-то в другой части мира.