Это может быть глупый вопрос, но это было в моей голове некоторое время, и я не могу найти достойного ответа где-либо еще.
У меня есть учитель, который говорит, что мы должны явно перечислить каждый параметр с описанием, даже если он только один. Это приводит к большому количеству повторений:
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 от чтения кода.
1: Кто-то еще, кто знаком с языком, на котором написан код. Не пишите комментарии для обучения, комментируйте для дополнения информации.
источник
Некоторые языки имеют функции генерации документов API, такие как Ruby, Java, C # и C ++ (с помощью инструмента командной строки). Когда вы думаете об этом таким образом, это делает написание документов API гораздо более важным. В конце концов, это отвечает на вопрос "как мне сделать ...?" Поэтому я не буду делать ничего повторяющегося, например,
Function: MyFunction
когда имя функции понятно всем. Инструменты генерации документов API достаточно умны, чтобы сделать это для меня. Тем не менее, следующие детали полезны, особенно в отношении открытых методов / функций:Они могут стать полезными справочными инструментами, когда вы пытаетесь отладить код. Многие IDE также будут использовать документы API в своих подсказках, когда вы наводите курсор на имя функции.
Если это язык без этих функций, комментарии помогают, но не так сильно.
источник
Returns the square root of X
также описывает, что является возвращаемым значением.Returns the color for this ray
илиReturns the requested Message, or null if it can't be found
. Но да, это краткое изложение документации по API.Если это публичный метод API, тогда да, вы должны предоставить подробную документацию, особенно о параметрах и ожидаемом поведении. Многие люди чувствуют, что это можно смягчить для частных методов / функций YMMV.
В целом, я предпочитаю писать чистый код (небольшие методы / функции, которые хорошо выполняют одно и одно) с разумными именами переменных. Это делает большую часть вашего кода самодокументируемой. Тем не менее, я, конечно, всегда документирую любые крайние случаи, использование параллелизма и сложные алгоритмы.
Короче говоря, думайте о себе как о немного худшем для ношения в 3 часа ночи через 3 месяца. Вы будете благодарить себя за ваши удивительные публичные документы вместо того, чтобы выяснить, что означает параметр (логический флаг) ...
источник
float
до целого числа путем сложения 0,5 и получения значения результата приведет к ошибочному округлению наибольшего значенияfloat
ниже 0,5. В таких случаях иногда может быть важно различать, должна ли функция быть определена как округление до ближайшего целого числа (или следующего более высокого целого числа, когда два возможных значения равноудалены), или как сложение 0,5 (возможно, с промежуточным шагом округления) и взять слово результата.Это похоже на то, как большинство сред -Doc анализируют документацию в коде (JavaDoc, PHPDoc и т. Д.).
Из Java, автоматически генерируется IDE:
Это тот же формат, который используется для создания документации для встроенных языковых функций. Пример: http://download.oracle.com/javase/6/docs/api/java/lang/String.html.
Этот формат очень полезен, потому что он ясно показывает любому стороннему пользователю, как взаимодействовать с вашим кодом. Если ваши функции являются частными методами, которые используются только внутренне, то это может быть немного бессмысленно - но я предполагаю, что ваш учитель пытается научить вас хорошей практике, пока вы все не научитесь делать это различие.
Единственный бит, который я часто нахожу несколько избыточным, - это возвращаемое описание - обычно оно почти идентично описанию моего метода.
источник
Есть две цели для комментариев:
Есть, конечно, МНОГИЕ разные способы подойти к этому, но чем тщательнее и последовательнее вы, тем лучше. Эффективное комментирование требует времени, чтобы научиться так же, как эффективное программирование. Имейте в виду, что трудно понять смысл комментариев в школе, потому что ничто из того, над чем вы работаете, никогда не бывает достаточно большим, чтобы действительно это оправдать, но они просто пытаются представить это вам. И обычно то, как вас учат, - это стиль вашего профессора, а не какой-либо стандарт. Разработайте то, что работает для вас. И помните ... есть такая вещь, как глупый комментарий! :) Пример:
В самом деле? Спасибо! лол
источник
Мне нравится документация с веб-сайта PHP, поэтому я использую нечто подобное для своих встроенных комментариев и с использованием синтаксиса PHPDoc. Смотрите пример ниже.
И, как сказал @Larry Coleman, встроенные комментарии должны рассказать, почему вы сделали какой-то кусок кода.
источник
Если это на службе генерации Doc, то подробные комментарии (хотя и раздражающие), вероятно, хорошая вещь. Хотя вы должны ставить перед собой цель команды, чтобы оставаться в курсе комментариев и держать их в курсе.
Если бы это был просто стиль комментирования, у меня были бы проблемы с ним. Чрезмерные комментарии могут повредить код так же, как помощь. Я не могу сосчитать, сколько раз я встречал комментарии в коде, которые устарели и в результате вводят в заблуждение. Я обычно игнорирую комментарии сейчас и сосредотачиваюсь на чтении кода и тестах кода, чтобы понять, что он делает и какова цель.
Я предпочел бы иметь четкий лаконичный код без комментариев . Дайте мне несколько тестов с описательными утверждениями или методами, и я счастлив и информирован.
источник