Страницы

Поиск по вопросам

пятница, 9 ноября 2018 г.

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

Допустим, я пишу комментарий к функции для документации. Мне нужно описать что она делает. Форматирование пока опустим. Предположим, это функция загрузки файла с сервера. По-русски я напишу что-то вроде этих вариантов:
/* * Функция загрузки файла * или * Загрузка файла */
Я слабо владею английским. В русском языке принято описывать алгоритм от третьего лица, но на английском часто встречал описание от второго лица. Как правильно написать такую функцию на английском? Нужно ли подразумевать 'it' и писать от третьего лица? Или вовсе писать в неопределенной форме? Сейчас я пишу так:
/* * Loads a file */


Ответ

Ваш вариант вполне хорош, он описывает что делает функция, как будто мы объясняем её кому-то используя только комментарии:
/* Loads a file */ /* Processes the queue */ /* Opens a remote resource */
Второй вариант, который я встречал, это описание того, что мы хотим сделать этой функцией:
/* Load a file */ /* Process the queue */ /* Open a remote resource */
Эти два варианта самые частовстречающиеся, используйте любой, который предпочитаете лично.

Комментариев нет:

Отправить комментарий