Как правильно использовать термин для документации, которую мы помещаем непосредственно над объявлением метода?
Я пишу технический документ и понял, что не уверен, какой официальный термин означает внутреннюю документацию, которую мы помещаем в виде блока комментариев перед объявлением определения.
То же самое, что в конечном итоге становится документацией для членов JavaDoc.
Это не просто внутренняя документация, и я не уверен, что «заголовочная документация» будет подходящим термином.
Обратите внимание, что я ищу общий термин, а не конкретный для конкретного языка (например, Java / Perl).
Ответы 6
В профессиональном плане это часто называют «оговоркой о требованиях» или «оговоркой о страховании».
В моей организации мы называем это методом или функцией doc-comment. Документация на уровне функций, вероятно, является более широко используемым термином.
Я всегда называю это комментарием метода (или функции), чтобы отличить его от комментариев класса или файла.
Я называю это комментариями кода, вот так просто.
Это называется спецификация метода или спецификация процедуры. То есть он определяет поведение процедуры, а не детали реализации. В некоторых учебниках это называется контрактом метода, но это может быть немного двусмысленным.
Я обычно называю это «встроенной документацией». Для меня это то, о чем идет речь - тот факт, что ваша документация является в вашим исходным кодом, поэтому больше шансов, что документы будут синхронизироваться с кодом.
(Это, конечно, не гарантия, но это действительно побуждает программистов есть свои овощи. Это означает, что разработчик может изменить документацию в то же время и в том же месте, чтобы поведение изменилось, а не постфактум и в другом месте.)