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

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

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

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

/**
 * Author:    Name
 * Created:   11.05.2009
 * 
 * (c) Copyright by Blub Corp.
 **/
6
задан Michael Klement 11 May 2009 в 06:16
поделиться

5 ответов

What to put in the file header:

  • Library/component that source code is part of
  • Copyright details
  • Brief and meaningful description of class(es) in source file

What NOT to put in the file header:

  • Anything that duplicates low level logic which is part of the code itself. This can lead to maintenance problems if it isn't updated when the source code changes.

  • Author name(s). Why?

    • In the world of revision control systems, while there may be an initial author of some code, eventually ownership becomes blurred. This is especially true when code enters the maintenance phase of the life cycle where owners can change regularly.
    • All code eventually becomes "community wiki" after enough changes ;-)
    • Would you want your name associated with all of the code forever, knowing full well that you will not be responsible for the code until its death?
  • Creation and last changed dates. This is for similar reasons as list above. Revision control includes this information - why duplicate it in the header, making more work for yourself and risking leaving inaccurate information in the comment when things inevitably change?

25
ответ дан 8 December 2019 в 03:01
поделиться
  • Авторские права
  • Первоначальный автор (ы)
  • Лицензия (если это открытый исходный код)
  • Однострочное заявление или описание цели
  • Дополнительная общая документация и примеры использования

Изменить: Изменен Автор (ы) на Оригинальный Автор (ы)

5
ответ дан 8 December 2019 в 03:01
поделиться

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

1
ответ дан 8 December 2019 в 03:01
поделиться

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

0
ответ дан 8 December 2019 в 03:01
поделиться

Кодировка файла! (utf-8)

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

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

0
ответ дан 8 December 2019 в 03:01
поделиться
Другие вопросы по тегам:

Похожие вопросы: