Как правильно называть документацию, которую мы размещаем над объявлением метода?

Question

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

То же самое, что в конечном итоге становится документацией участника JavaDoc.

Это не просто внутренняя документация, и я не уверен, что термин «заголовочная документация» будет подходящим термином.

Обратите внимание, что я ищу общий термин, а не термин, специфичный для конкретного языка (например, Java/Perl).

Answer 1

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

Answer 2

В моей организации мы называем это методом или функцией-комментарием к документу.Документация функционального уровня, вероятно, является более широко используемым термином.

Answer 3

Я всегда называю это комментарием метода (или функции), чтобы отличить его от комментариев класса или файла.

Answer 4

В профессиональном плане его часто называют «пунктом требований» или «пунктом страхования».

Answer 5

Я обычно называю это «встроенной документацией». Для меня это то, о чем есть - тот факт, что ваша документация в ваш исходный код, поэтому больше шансов, что документы будут синхронизироваться с кодом.

(Конечно, это не гарантия, но это побуждает программистов есть овощи.Это означает, что разработчик может изменить документацию. в то же время и в том же месте поведение меняется, а не постфактум и в другом месте.)

Answer 6

Я называю это комментариями к коду, вот так просто.