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

9

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

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

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.

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

Maxpm
источник
ваш пример упрощен На практике вы бы указали гораздо больше ограничений, чем просто тип параметра, если это целое число, то это должно быть целое число, в котором были значения X и Y. Если возвращаемое значение является двойным, вы можете указать его точность. и каким образом это могут быть значения (может существовать функция, которая возвращает ровно 1.01, 2.31 и 5.01!). Будьте более конкретны, и вы не увидите столько повторений ...
Старый аккаунт

Ответы:

17

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

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


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

Ларри Коулман
источник
1
+1, хотя убедитесь, что вы помните, что то, что очевидно для вас, может быть не очевидно для другого программиста.
Джош К
@Josh: хорошая мысль, поэтому я отредактировал ответ.
Ларри Коулман
@ Ларри: Хорошие комментарии должны также включать что: что входит, что выходит, и особенно, какой тип входит и выходит.
Йорис Мейс
@Joris: То, что входит и что выходит, покрыто «ожиданиями относительно входных данных» и «как будет вести себя код». Что касается того, какой тип входит и выходит, я придерживаюсь того, что сказал ранее: «Хорошие комментарии не повторяют того, что в коде».
Ларри Коулман
2
@Larry: я скорее читаю это в комментарии, чем должен проходить через объявления и код каждый раз, когда я хочу повторно использовать функцию. Вопрос стиля, я думаю, я ленивый парень.
Йорис Мейс
6

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

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

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

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

Берин Лорич
источник
Допустимо ли, если выходное описание включено в резюме? Например, Returns the square root of Xтакже описывает, что является возвращаемым значением.
Maxpm
Да; что нужно учить студентов, так это использовать эти функции документирования.
Джереми
Мне нравится, если это возможно, сохранять документацию по API более логичной абстракцией. Например, Returns the color for this rayили Returns the requested Message, or null if it can't be found. Но да, это краткое изложение документации по API.
Берин Лорич
3

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

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

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

Мартейн Вербург
источник
Иногда функции могут иметь поведение в угловом случае, которое отличается от того, что подразумевает алгоритм. Например, округление a floatдо целого числа путем сложения 0,5 и получения значения результата приведет к ошибочному округлению наибольшего значения float ниже 0,5. В таких случаях иногда может быть важно различать, должна ли функция быть определена как округление до ближайшего целого числа (или следующего более высокого целого числа, когда два возможных значения равноудалены), или как сложение 0,5 (возможно, с промежуточным шагом округления) и взять слово результата.
суперкат
1

Это похоже на то, как большинство сред -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

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

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

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

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

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

Кеннет
источник
0

Мне нравится документация с веб-сайта 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
{
 ...
}
Раду Марис
источник
0

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

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

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

dietbuddha
источник