Когда я должен добавить комментарии к своему коду? [закрытый]

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

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

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

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

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

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

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

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

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

Добавьте комментарий В ЛЮБОМ месте программист, читающий ваш код, может сгенерировать WTF-момент.

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

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

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

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

Вам следует попробовать писать комментарии ДО того, как писать какой-либо код. например

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


    //retrieve logged in user


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

}

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

Подходит не для всех ситуаций, но зачастую хороший вариант!

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

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

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

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

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

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

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

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

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

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

Если вы пишете функцию или класс, комментарии - это способ объявить, что должно произойти с функцией. Такие вещи, как входные переменные, тип вывода, особое поведение, исключения и т. Д. ИМХО, такой комментарий должен быть написан до запуска фактического кода, на этапе «разработки кода». У большинства языков есть пакеты, которые обрабатывают такие комментарии в документации (javadoc, epydoc, POD и т. Д., Так что эти материалы будут прочитаны пользователями.

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

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

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

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

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

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