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

#документация #комментарии

Допустим, я пишу комментарий к функции для документации. Мне нужно описать что она
делает. Форматирование пока опустим. Предположим, это функция загрузки файла с сервера.
По-русски я напишу что-то вроде этих вариантов:

/*
 * Функция загрузки файла
 *  или
 * Загрузка файла
 */


Я слабо владею английским. В русском языке принято описывать алгоритм от третьего
лица, но на английском часто встречал описание от второго лица. Как правильно написать
такую функцию на английском? Нужно ли подразумевать 'it' и писать от третьего лица?
Или вовсе писать в неопределенной форме? Сейчас я пишу так:

/*
 * Loads a file
 */

    

Ответы

Ответ 1

Ваш вариант вполне хорош, он описывает что делает функция, как будто мы объясняем
её кому-то используя только комментарии:

/* Loads a file */
/* Processes the queue */
/* Opens a remote resource */


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

/* Load a file */
/* Process the queue */
/* Open a remote resource */


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


Ответ 2

Используйте Simplified Technical English (STE) 
Пишите коммент как commit message в Git:


Update default policies...
Add support for configuring...
Add shared_storage_test methods...
Add CPU arch filter...

Следуйте модели "50/72":


Первая строка: длина первой строки - не более 50 символов  
Вторая строка: пустая  
Третья и следующие: длина ограничена 72 символами