Когда комментировать код (Другое "Когда" )

Ответ 1

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

Ответ 2

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

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

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

Ответ 3

Я избегаю комментирования кода, предпочитая писать код достаточно ясно, чтобы не требовать комментариев. Но иногда у вас есть некоторые "племенные знания", встроенные в код. В этом случае вам нужно объяснить, почему код делает то, что он делает, и не столько, что делает код.

Ответ 4

Когда кто-то просмотрит это для вас, и они говорят: "Я не понимаю этот бит".

Ответ 5

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

Ответ 6

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

Что касается WHEN, я предпочитаю "прежде чем писать код". После написания кода вы не будете справляться с этим. Напишите комментарий, объясняющий ваши намерения, затем выполните эти намерения в коде. Проверьте комментарий, чтобы убедиться, что он все еще имеет значение, и вы GTG.

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

Ответ 7

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

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

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

Ответ 8

Я собираюсь снова спеть ту же песню: дайте "Чистый код" (Robert C. Martin) прочитать. Поскольку я защищал в этом сообщении

Там отличная пара глав по соглашениям об именах, читаемости кода, а также КОММЕНТАРИИ. Хорошо поддерживаемый совет о том, как и когда писать комментарии в вашем коде.

Ответ 9

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

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

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

Ответ 10

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

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

Ответ 11

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

Есть много вопросов, связанных с переполнением стека о том, как писать хорошие комментарии (например, Существуют ли стандартные форматы комментариев в коде?), но в основном это происходит различать организации и личные стили. Конечная цель комментариев - помочь понять код.

Пока вы правильно пишете комментарии, когда вы пишете их, не должно быть никакой разницы.

Ответ 12

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

Ответ 13

Я действительно рекомендую вам прочитать эту книгу: Code Craft: Практика написания отличного кода

В этой главе есть целая глава.

Вот некоторые ключевые понятия из этой главы:

• Учитесь писать достаточно комментариев, и не более того. Благодарите качество, а не количество.
• Потратьте свое время на написание кода, который не должен подкрепляться тоннами комментариев.
• Хорошие комментарии объясняют, почему не так.
• Когда вы обнаружите, что пишете плотные комментарии, чтобы объяснить, отступите. Есть ли большая проблема для решения?
• и др.

Ответ 14

Я соглашусь с ребятами выше о комментировании "ДО" кода. Это поможет вам запомнить назначение функции/метода/блока кода. Легко отслеживать стороны при кодировании и забывать о своем первоначальном намерении. Например, если вы пишете функцию getFoo() и не можете вспомнить, что она должна вернуть, значит, вы отстали. Однако, если вы пишете функцию, которая выполняет несколько неприятных вычислений при повторении нескольких наборов данных, комментарии могут просто помочь.

Ответ 15

Я слышал (но не могу найти) "Принцип необходимости" в отношении сферы образования. Говоря прямо, учащиеся учатся, когда и чему им нужно учиться. Существуют аналогия с TDD (только для написания кода с неудачным тестом, чтобы продемонстрировать его потребность) и Lean (Just In Time, в частности). Я думаю, что вы продемонстрировали вчерашнее замечание, так это применение принципа "Необходимость" для комментариев, и я думаю, что так, как вы это делали, и ваш график был в порядке.

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

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

Ответ 16

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

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

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

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

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

Ответ 17

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

Затем, после отправки кода, я добавляю комментарии только в том случае, если кто-то не может понять, что происходит и спрашивает меня. (Кто-то, включая меня).

Ответ 18

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

С другой стороны, они могли бы помочь.

Комментарии, которые были написаны в прошлом, часто более полезны, чем комментарии, которые еще не были написаны.

Если вы намеренно задерживаете написание комментариев, вы можете стать жертвой " le mieux est l'ennemi du bien.

Ответ 19

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

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

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

Ответ 20

По моему опыту, лучше всегда комментировать код, даже если имена методов и переменных не требуют пояснений. Гораздо легче вернуться к фрагменту кода через 2 года и понять его, когда есть комментарии. Комментарии делают код более удобным.