Когда следует добавлять комментарии к моему коду?

Ответ 1

Короткий ответ

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

Длинный ответ:

• Когда я пишу это? - Yes
• После того, как я сделал часть (Single class/function/if-elses)? - Yes
• После того, как я заработал все это? - Yes

Когда я пишу это? - Да

Отбрасывайте комментарии в любое время, когда вы попадаете в место, где код не сразу очищается. Например, опишите класс, когда имя класса нечеткое или может быть интерпретировано слишком широко. Другой пример: если я собираюсь написать неочевидный блок кода, я сначала добавлю комментарий, напоминая мне о том, чего я хочу/нуждаюсь. Или, если я только что добавил код, и я сразу понял, что там есть что-то, напишите комментарий, чтобы напомнить себе. Эти комментарии представляют собой комментарии к разработчикам, а не для будущих сопровождающих, а скорее для того, чтобы помочь вам в процессе кодирования.

Отбрасывайте FIXME - explanation и TODO explanations напоминания, когда вы идете.

Код все еще работает, поэтому я еще не документирую все методы и параметры.

После того, как я сделал часть (Single class/function/if-elses)? - Yes

Когда я разумно выполнил метод или класс, настало время его просмотреть. Наряду с проверкой возможностей методов, методов заказа и другой очистки кода для повышения понятности, теперь пришло время стандартизировать его против ваших стандартов команды. Подумайте, какие комментарии нужны, исходя из аудитории, на которую он будет выпущен (в будущем вы тоже являетесь частью аудитории!) Имеет ли класс заголовок? Существуют ли неочевидные условия, при которых этот метод не следует вызывать? Имеет ли этот параметр какие-либо условия, например. не должно быть нулевым?

Проверить пункты FIXME и TODO - все еще действительны? Любые, с которыми вы должны обратиться сейчас, прежде чем двигаться дальше?

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

После того, как я заработал все это? - Yes

Настало время просмотреть все и доработать комментарии к вашим стандартам.

Все теги FIXME и TODO (исправлены или зафиксированы как известные проблемы)?

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

Теперь грязный маленький секрет

Больше не всегда лучше. Как unit tests, вам нужно сбалансировать использование ваших инструментов, взвешивающих затраты и преимущества. Дело в том, что кодер может набирать столько физических линий в час - какие проценты должны быть комментариями? Низкий процент означает, что у меня много кода, но его запутывает и трудно понять и правильно использовать. Высокий процент означает, что через час, когда кто-то меняет сигнатуру метода или переопределяет интерфейс, все время тратится на полное комментирование всех параметров этих методов, которые только что были обработаны.

Найдите правильный процент, основанный на стабильности кода, как долго он будет жить и насколько широко он будет выпущен. Пока не стабильный - минимальные комментарии, которые помогут вам и вашей команде. Стабильный и готовый к проекту - полностью прокомментирован. Публичный выпуск? - полностью прокомментировал (проверьте еще раз!) с авторскими правами (если применимо). По мере накопления опыта отрегулируйте процент.

Ответ 2

Вы никогда не должны добавлять комментарии - они не являются дополнениями. Комментарии являются частью кода - вы используете их, когда вам это нужно. Спросить, когда вы должны добавить их, - это спросить, когда вы должны добавлять функции или классы. Хотя я и думаю об этом, я помню, как я занимался программным слотом в университете, в котором работал, где один из учеников пришел с примерно 1000 строк Паскаля, без каких-либо функций. Когда я спросил, почему он не использовал функции, его ответ был "Я добавлю их позже, как только у меня это получится".

Ответ 3

Это субъективно, но иногда лучше добавить их до фактического кода, например. когда вы реализуете алгоритм с четко определенными шагами. Тем самым сложнее пропустить шаги.

Ответ 4

Это вопрос стиля. Лично мне нравится писать комментарии во время кодирования, а не после. Потому что я оставляю это после, я обычно ленив и не пишу их вообще. Тем не менее, иногда полезно переходить к завершенному фрагменту кода, выяснить, что не очевидно из самого кода и документировать его. В частности, те части, где сделаны предположения.

Ответ 5

Я предлагаю писать комментарии всякий раз, когда вы редактируете какой-либо код, пока вы его редактируете. Согласно Роберту К. Мартину в "Чистый код" , недостатком комментариев является то, что код может меняться без комментариев, обновляемых, делая комментарии не только бесполезно, но опасно. Чтобы уменьшить эту проблему, если вы должны использовать комментарии (потому что вы не можете выразить себя в самом коде), обязательно обновляйте их каждый раз, когда вы обновляете код.

Ответ 6

Вы должны попробовать написать комментарии, прежде чем писать код. например,

public string getCurrentUserName() {
    //init user database repository


    //retrieve logged in user


    //return name if a user is logged in, otherwise return null

}

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

Не подходит для всех ситуаций, но часто это хороший вариант!

Ответ 7

Недостатком добавления комментариев является то, что много раз это просто не будет сделано из-за ленивости, других задач и т.д.

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

Ответ 8

Поместите комментарий В ТЕЧЕНИЕ, программист, читающий ваш код, может генерировать момент WTF.

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

Ответ 9

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

Вы должны объяснить те вещи, которые нельзя уменьшить из кода.

Ответ 10

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

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

Ответ 11

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

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

Вкратце напишите основные комментарии по мере продвижения, а затем улучшите их, так как ваш код станет более стабильным.

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

Ответ 12

Вопрос должен быть, когда я добавлю код в свои комментарии?

Моя практика заключается в том, чтобы выписать функциональность модуля/объекта/функции как ряд комментариев. Не комментарии, как "добавить один для борьбы". Комментарии более высокого уровня, такие как msgstr "сортировать список по номеру счета". Подробные комментарии в значительной степени избыточны с кодом. Поэтому я избегаю тех, пока не напишу очень сложный алгоритм. Когда у меня есть функциональность, "спроектированная" в комментариях, я действую как человеческий компилятор и добавьте код после каждой строки комментариев.

Попробуйте и сообщите нам, как это работает!

Ответ 13

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

Ответ 14

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

Ответ 15

Когда вы делаете что-то нетривиальное, как вы его пишете.

Ответ 16

Вы задали много вопросов в своем вопросе. Я думаю, это зависит от того, что вы делаете в то время.

Если вы пишете функцию или класс, комментарии - это способ объявить, что должно произойти с функцией. Такие вещи, как входные переменные, тип вывода, специальное поведение, исключения и т.д. IMHO такой комментарий должен быть написан до того, как будет запущен фактический код, на этапе "дизайн кода". На большинстве языков есть пакеты, которые обрабатывают эти комментарии в документации (javadoc, epydoc, POD и т.д., Так что материал будет читаться пользователями.

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

Затем, как говорили другие, вы хотите избежать моментов WTF, самостоятельно или других. Однажды я получил аттабию для комментария, который я сделал однажды в проекте с открытым исходным кодом. Комментарий был "Да, я действительно хочу = и не == на этой линии".

Ответ 17

а. когда вы решаете произвольное решение, которое трудно будет понять. B. Каждая вещь, которую вы чувствуете, что вы должны помнить при написании кода C. в начале программы объясняют логику и использование Совет - вместо того, чтобы комментировать много, используйте длинные имена для функций и vars, которые действительно объясняют, что делает функция или что означает переменная.

Ответ 18

В основном, когда вы пишете этот код. Вы можете отправиться туда после функции/блока/что угодно и организовать свои комментарии на свежий ум. Большая часть материала, который мы пишем при кодировании, не имеет смысла позже.

Ответ 19

В начале моей карьеры я добавил комментарии почти к каждой строке кода, так как вы можете сделать это в программе ASM. Со временем я столкнулся со многими проблемами, упомянутыми здесь. Это был медведь для поддержания, который привел к тому, что он не обновлял комментарии, а затем они стали в высшей степени застывшими, обычно заплесневелыми.

Я чувствую, что количество комментариев должно отражать, насколько сложным или неочевидным является сам код. В более сложных условиях, таких как ASM, вам, вероятно, понадобятся дополнительные комментарии, чтобы понять, что происходит. В более современных языках, таких как С#, в большинстве случаев вам не нужно много комментариев.

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