Нужны ли комментарии и колонтитулы комментариев в коде?

Ответ 1

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

Заявление об авторских правах строго не требуется (авторское право является автоматическим) ¹ но если вы публикуете источник, то, скорее всего, это будет считаться более безопасным ². Полный оператор лицензии, вероятно, будет лучше в отдельном файле, а затем ссылается (это то, что делает Boost).

¹Wikipedia имеет разумное резюме, но вам действительно нужно принять ваши собственные юридические консультации.

² Специально адвокаты, играющие это безопасно.

Ответ 2

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

Ответ 3

Я работаю в очень большой корпоративной корпорации с множеством странных стандартов.

Это НЕ одно из них. Мы не обязаны добавлять верхние или нижние колонтитулы в исходный код. Авторское право не обязательно должно указываться в каждом файле класса. не говоря уже о пересмотре, которые обрабатываются любой доступной системой управления исходным кодом.

Ответ 4

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

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

Стандартные комментарии к заголовку - это боль, и они должны быть ОЧЕНЬ минималистичными или даже лучше не существующими. Бросьте это огромное ASCII-искусство до нижнего колонтитула или в readme, мне все равно, но, пожалуйста, оставьте мой заголовок один:)

Вы думаете, что google willv'e был успешным, если первые 800 пикселей вашего результата поиска были заполнены огромными логотипами Google и заявлениями об авторских правах?: P

Ответ 5

Интересно видеть, что Google требует уведомления об авторских правах на своем С++-суме. Это всегда казалось мне лишним, особенно учитывая, что файлы будут (будем надеяться!) Подкреплены и также будут находиться в Source Control, если наступит битва авторских прав. Я также не уверен в том, что вы создаете источник с именем автора: нужно ли другим людям запрашивать разрешение на редактирование/использование файла?!

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

Ответ 6

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

Где я работаю, авторские права и история изменений не требуются в верхних или нижних колонтитулах кода.

Ответ 7

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

История изменений может быть полезна, но очень ограничена. Если вы попытаетесь сделать запись о каждой точке с запятой или оператором, которую вы измените, она скоро станет старой. Более того, история изменений не дает вам подробностей о том, что именно изменил конкретный автор. Это скорее кто был здесь и что-то сделал.

Ответ 8

Нет необходимости требовать авторские права (зависит от юрисдикции). Обычно у вас есть авторское право для вашей работы.

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

Я никогда не видел внутреннего кода без какой-либо комбинации заголовка/нижнего колонтитула.

Ответ 9

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

Ответ 10

Многие из этих вещей - историческое похмелье. Но это не значит, что это бесполезно.

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

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