Каковы различные стандарты и методы документирования кода, и которые лучше всего сработали для вас?
Я спрашиваю, потому что я и мой друг начинаем компанию и, возможно, потребуется согласовать какой-то стандарт для комментирования, чтобы мы могли легче читать код друг друга.
Прежде всего, комментарии должны быть четкими, краткими, актуальными для кода, который они комментируют, и обеспечивают ценность, которая не всегда доступна, фактически прочитав код. Например, документирование того, почему был выбран конкретный алгоритм хэширования для остальных хеш-функций для пароля.
Если вы используете один из .NET-языков, вы должны использовать комментарии XML для публичных и частных членов, так как Visual Studio будет использовать эту информацию для отображения intellisense для ваших классов. Вы также можете использовать эти комментарии для автоматического создания документации API с помощью таких инструментов, как SandCastle. Это означает, что информация должна быть обновлена, но это должен быть очень небольшой процент потраченного времени. Если вы не используете один из языков, основанных на .NET, есть другие инструменты (такие как Doxygen или Javadoc), которые предоставляют комментарии и функциональные возможности, похожие на комментарии XML.
Вы также должны быть последовательны в том, что вы документируете и как документируете. Если вы поместите заголовок файла, поместите один и тот же заголовок в каждый файл (изменив только то, что необходимо, например имя файла).
Прежде всего, ваш стандарт должен быть в том, что код не нуждается в комментариях - он должен быть самодокументирован. Как говорят разные, комментарии должны объяснять, почему вы подошли к проблеме определенным образом.
Лично я ненавижу комментарии CS101:
int Count = 0; // initialize Count to zero
Стоит помнить, что комментарии всегда ошибочны. Это особенно актуально, когда вы делаете такие вещи, как запись больших комментариев заголовков функций, в которых перечислены все параметры и возвращаемое значение и т.д. Вы можете сохранить это в течение длительного времени, но в конце концов, когда ваша база кода будет расти, блоки комментариев перестанут синхронизироваться с фактическим кодом. Вы измените имя параметра или добавите новый, и забудьте обновить комментарий. Тогда комментарий ошибочен и поэтому бесполезен.
Как уже упоминалось, ваши комментарии должны объяснить, почему вы что-то делаете, а не то, что вы делаете. На что можно ответить, прочитав код.
I опубликовано об этом, это упростит вашу жизнь, если вы укажете переменные и функции, которые объясняют, о чем они, или что они делают. Поэтому комментарии должны использоваться для объяснения того, почему вы закодировали его так, как вы.
Проще говоря, прокомментируйте, почему, а не как. Я понимаю, что это избыточно, учитывая другие ответы, но этого нельзя сказать достаточно.
Напишите свой код и комментарии, чтобы его было легко читать, когда вы должны вернуться через 6 месяцев и исправить ошибки, которые будут там. Кроме того, если код написан таким образом, что логика и намерение понятны, остерегайтесь чрезмерного комментирования. Это может затруднить чтение кода. Другими словами, будьте милы с человеком, который должен поддерживать код.
Я настоятельно рекомендую читать Code Complete и раздел о комментариях там.
Как говорили другие, код должен быть сам комментирующим, поэтому имена, события, объекты должны отражать и читать как можно проще, что они пытаются достичь.
Кроме того, следует использовать дополнительные комментарии, когда что-то нуждается в дальнейшем объяснении, почему вы пошли по пути (эта формула и значения были выбраны из-за х, см. ошибку и т.д.).
(Если это .NET, и вы также хотите предоставить файл справки Windows, вы также можете посмотреть Ghostdoc и комментарий, который он предоставляет, и Sandcastle [строитель справочного файла Windows, который будет принимать комментарии кода xml и создать файл справки из вашего API].)
Но в целом эмпирическое правило состоит в том, что 99% времени код должен быть читаемым, логичным и разбитым на методы, которые имеют смысл, так что вам действительно не нужно ничего, кроме кода, а затем комментарии заполнить пробелы на том, что действительно нужно объяснить далее.
Я нажимаю на комментарии в заголовках функций, но задаю только внутрифункциональные комментарии, когда они абсолютно необходимы для описания, скажем, обходной ошибки API или какой-либо другой важной, но неочевидной техники.
Комментарии заголовка должны:
Другие комментарии, примечания или примеры использования также могут быть включены, но не требуются.
И да, комментарии могут и становятся неточными. Там не избежать этого, но нет никаких оснований бросать ребенка с водой для ванны. Когда это правильно, комментарии могут сэкономить вам много времени, выкапывая код, пытаясь понять его цель. Доверяйте комментариям, но проверьте - и найдите минуту, чтобы исправить неточности, когда вы сталкиваетесь с ними.
Скомментирующий код - это немного фальши, по-моему. Нет такой вещи. Конечно, код должен быть четким и кратким, но это не касается комментариев. Что касается качества кода.
Комментарии, с другой стороны, должны объяснить, какую проблему решает код и почему. Понятно, как работает код, читая сам код; комментарии должны быть о том, почему код вообще существует.
Я подобрал соглашение о комментировании от другого разработчика, когда я был в университете, который хорошо меня обслуживал на протяжении многих лет. Его идея заключается в том, чтобы вы могли быстро и легко сканировать файл, либо искали что-то, либо получали обзор своей структуры. Я префикс каждого открытого или защищенного метода или свойства со следующей структурой комментариев:
/* ====== MethodName ====== */
/// <summary>
/// XML comments go here
/// </summary>
void MethodName()
Из всех конвенций, которые я видел до сих пор, этот, по крайней мере, по-моему, кажется самым ясным способом сделать каждый метод отличным, и это облегчает сканирование через файл исходного кода, Сказав это, я ненавижу комментарии XML с удвоенной силой из-за визуального беспорядка налога на угловую привязку, и я хочу, чтобы Microsoft решила что-то большее по строкам Javadoc или PHPdoc:
/* ====== methodName ====== */
/**
* Doc comments go here
*
* @param A parameter
* @returns A number
*/
int methodName(String param)
Кроме того, я стараюсь сделать код как можно более самодокументирующимся. Каждый метод должен идеально выполнять одну конкретную задачу (которая, конечно же, может быть разбита на подзадачи), и ее имя должно описывать, что она делает.
Это зависит от языка, конечно, но, как правило, комментарий для каждого метода, описывающего, что он делает, то, что он требует для ввода и вывода для вывода, является стандартным. Вы также можете добавить имя автора и дату, если хотите, но это, скорее всего, будет очевидным в вашем приложении управления версиями.
Как и в других комментариях, используйте их экономно и убедитесь, что вы описываете, почему, а не как, когда документируете определенные строки кода.
Посмотрите, что рекомендуют слова "чиновники". Я следовал за этим, потому что есть вероятность, что тот, с кем вы работаете в будущем, тоже слышал об этом или даже использовал его. Я бы избегал "изобретать" свой собственный стандарт.
Я обычно использую эти указатели.
Я использую "комментарии заголовка" для документирования функций, классов и т.д. Обычно это больше для документации, чем для комментариев. Я использую С# и Visual Studio, и вы получаете некоторые полезные функции, когда используете для этого комментарии XML.
Комментарии должны сообщать , почему вы что-то сделали, а не , что. Ваш код должен быть достаточно ясным, чтобы показать, что если он не изменит код. Комментарии, повторяющие то, что делает код, не так плохи, как дубликат кода. Когда код обновляется, комментарии иногда забываются, вызывая больше вреда, чем пользы.
Комментарии должны быть сведены к минимуму. Комментарии находятся в поиске и нуждаются в обслуживании. Так что без них, если вы можете
Я считаю, что эта статья имеет значение. http://www.codinghorror.com/blog/archives/001150.html
Я бы начал со стандартного для комментариев всех классов (имя файла, теги управления версиями для динамической версии/последнего автора/истории изменений, назначение класса) и методы (использование, параметры, возвращаемые значения) и обеспечить, чтобы все классы и методы документируются в соответствии с этими стандартами.
Вот что я делаю. Сначала я комментирую классы и методы в заголовке с помощью doxygen - это помогает, поскольку я работаю с Java дома и C++ на работе, хотя, если вы используете какой-то вариант.net, вы, вероятно, будете использовать его хэширование Microsoft.
Для встроенных комментариев я предпочитаю комментировать блоки кода: это то, что делает (или должен делать) следующий блок кода. Не комментируйте ни одной строки, так как это бессмысленно и часто менее чем полезно. Исключением является случай, когда обходной путь выполняется, когда в реализации языка есть ошибка - это полезно при работе с VC6.
Как насчет комментариев для людей, которым необходимо пропустить код позже, чтобы узнать, где он сломался или что может потребоваться обновить. Вот пример, который я нашел из Интернета.
http://www.example-code.com/csharp/ssl_async_client.asp
Я думаю, что этот пример хорош, если вы хотите отлаживать этот код. возможно, больше "Почему я делаю это таким образом", но не плохо.
Я нахожу, что многое из того, что я делаю, - это отладка и поддержка приложений, которые совершенно разные, там, где есть база данных, написанная людьми, которые давно ушли или недоступны. Чтобы найти ошибку, иначе вам, возможно, придется читать каждую строку кода, кажется, неэффективно нет?
Я хотел бы увидеть больше примеров хороших комментариев, которые есть у людей.