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

Question

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

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

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

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

Answer 1

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

Answer 2

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

Answer 3

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

Answer 4

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

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

Answer 5

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

Answer 6

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