Стили комментирования и документирования

Это может быть глупый вопрос, но это было в моей голове некоторое время, и я не могу найти достойного ответа где-либо еще.

У меня есть учитель, который говорит, что мы должны явно перечислить каждый параметр с описанием, даже если он только один. Это приводит к большому количеству повторений:

double MyFunction(const int MyParam);
// Function: MyFunction
// Summary: Does stuff with MyParam.
// Input: int MyParam - The number to do stuff with.
// Output: MyParam with stuff done to it.

Насколько подробно вы пишете документацию в коде?

Для начала, я согласен, что строка «Function:» в вашем примере полностью избыточна. Кроме того, по моему опыту, в школе люди учили добавлять комментарии такого типа, продолжая добавлять комментарии такого типа в свой производственный код.

Хорошие комментарии не повторяют то, что в коде. Они отвечают на вопрос "Почему?" вместо "что?" или как?" Они охватывают ожидания относительно входных данных, а также того, как код будет вести себя при определенных условиях. Они охватывают , почему алгоритм X был выбран вместо алгоритма Y. Короче говоря, именно то , что не было бы очевидно для кого - то еще ¹ от чтения кода.

^{1: Кто-то еще, кто знаком с языком, на котором написан код. Не пишите комментарии для обучения, комментируйте для дополнения информации.}

Некоторые языки имеют функции генерации документов API, такие как Ruby, Java, C # и C ++ (с помощью инструмента командной строки). Когда вы думаете об этом таким образом, это делает написание документов API гораздо более важным. В конце концов, это отвечает на вопрос "как мне сделать ...?" Поэтому я не буду делать ничего повторяющегося, например, Function: MyFunctionкогда имя функции понятно всем. Инструменты генерации документов API достаточно умны, чтобы сделать это для меня. Тем не менее, следующие детали полезны, особенно в отношении открытых методов / функций:

• Резюме (что оно делает и когда уместно, резюме того, как его использовать)
• Список параметров и что ожидается
• Что будет возвращаемое значение (выход)
• Любые исключения, которые могут быть сгенерированы явно и почему

Они могут стать полезными справочными инструментами, когда вы пытаетесь отладить код. Многие IDE также будут использовать документы API в своих подсказках, когда вы наводите курсор на имя функции.

Если это язык без этих функций, комментарии помогают, но не так сильно.

Если это публичный метод API, тогда да, вы должны предоставить подробную документацию, особенно о параметрах и ожидаемом поведении. Многие люди чувствуют, что это можно смягчить для частных методов / функций YMMV.

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

Короче говоря, думайте о себе как о немного худшем для ношения в 3 часа ночи через 3 месяца. Вы будете благодарить себя за ваши удивительные публичные документы вместо того, чтобы выяснить, что означает параметр (логический флаг) ...

Это похоже на то, как большинство сред -Doc анализируют документацию в коде (JavaDoc, PHPDoc и т. Д.).

Из Java, автоматически генерируется IDE:

/**
 * [Description]
 * @param str [Description]
 * @param isCondition [Description]
 * @return [Description]
 */
public int testFunction(String str, boolean isCondition) {
    ...
}

Это тот же формат, который используется для создания документации для встроенных языковых функций. Пример: http://download.oracle.com/javase/6/docs/api/java/lang/String.html.

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

Единственный бит, который я часто нахожу несколько избыточным, - это возвращаемое описание - обычно оно почти идентично описанию моего метода.

Есть две цели для комментариев:

1. Они служат для быстрого напоминания о том, что делает ваш код, когда вы возвращаетесь к нему через месяцы / годы. Таким образом, вам не нужно перечитывать и анализировать код, чтобы освежить память.
2. Они передают другим людям, которые могут читать или работать с вашим кодом, что делает ваш код.

Есть, конечно, МНОГИЕ разные способы подойти к этому, но чем тщательнее и последовательнее вы, тем лучше. Эффективное комментирование требует времени, чтобы научиться так же, как эффективное программирование. Имейте в виду, что трудно понять смысл комментариев в школе, потому что ничто из того, над чем вы работаете, никогда не бывает достаточно большим, чтобы действительно это оправдать, но они просто пытаются представить это вам. И обычно то, как вас учат, - это стиль вашего профессора, а не какой-либо стандарт. Разработайте то, что работает для вас. И помните ... есть такая вещь, как глупый комментарий! :) Пример:

a += 1; //adds 1 to the value in a

В самом деле? Спасибо! лол

Мне нравится документация с веб-сайта PHP, поэтому я использую нечто подобное для своих встроенных комментариев и с использованием синтаксиса PHPDoc. Смотрите пример ниже.

/*
* Finds all the locations where you have access to for this client and returns them in an array .
* @author Radu
* @version 1.0
* @param int $id ( The id of the client for which you're requesting access. )
* @param object $db ( A resource of type Mysql, representing a connection to mysql database, if not supplied the function will connect itself. )
* @return array ( Returns array with id's of locations that you are allowed to see, an empty array if you do not have acces to any locations or returns FALSE and triggers a Warning if any error occuread )
* @use array allowed_locations ( $id [, $db] )
*/
function allowed_locations($id, $db=NULL){ ... }

И, как сказал @Larry Coleman, встроенные комментарии должны рассказать, почему вы сделали какой-то кусок кода.

$funcResult = SomeFunction();
if(is_array($funcResult))
{    //Beacause SomeFunction() could return NULL, and count(NULL) = 1
    $c = count($funcResult);
} else {
    $c = 0;
}
if($c == 1)
{
 ... 
}else
{
 ...
}

Если это на службе генерации Doc, то подробные комментарии (хотя и раздражающие), вероятно, хорошая вещь. Хотя вы должны ставить перед собой цель команды, чтобы оставаться в курсе комментариев и держать их в курсе.

Если бы это был просто стиль комментирования, у меня были бы проблемы с ним. Чрезмерные комментарии могут повредить код так же, как помощь. Я не могу сосчитать, сколько раз я встречал комментарии в коде, которые устарели и в результате вводят в заблуждение. Я обычно игнорирую комментарии сейчас и сосредотачиваюсь на чтении кода и тестах кода, чтобы понять, что он делает и какова цель.

Я предпочел бы иметь четкий лаконичный код без комментариев . Дайте мне несколько тестов с описательными утверждениями или методами, и я счастлив и информирован.