Комментарии всегда неправы - правы, или нет? [закрыто

Question

Случайно пробежал через это блог На том, как никоим не следует читать комментарии и думать себе все комментарии, которые я прочитал, что были либо неправильными, датированы или просто запутанными. Должен ли один просто никогда не читать комментарии и / или просто использовать Regex заменить шаблон для удаления ... :-) ... просто шучу, но на самом деле, может быть, нет. По крайней мере, кажется, похоже на комментарии, и связанный код должен быть отмечен временными метками. Согласен или нет?

FYI, BLOG, кажется, по этому пользователю Stackoverflow: Носредна

Answer 1

Неточный комментарий так же серьезно из ошибок как неправильный код. Если это постоянная проблема, я бы сказал, что проект имеет серьезные проблемы. Большие проекты, такие как PostgreSQL (94 м, несжатый в каталоге SRC), полагаются на точные комментарии, чтобы помочь программистам понять вещи быстро. Они также очень серьезно относится к комментариям.

редактировать:

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

Answer 2

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

Любой программист, который говорит вам, что комментарии / документация не стоит того времени, необходима для записи / обслуживания, имеет ряд проблем:

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

• Тарифы ошибок, связанные с его кодом будет выше Чем они могли бы быть, потому что все эти предположения и особые случаи, которые он забыл упомянуть, будет постоянно путешествовать людей. (Сколько раз вы должны были сделать что-то «необычное» в вашем коде, чтобы сделать что-то работу, забыть, чтобы прокомментировать его, чтобы сказать, почему вы сделали это таким образом, а потом позже думали, что это выглядело как ошибка и «исправлена», Только чтобы найти, что вы ужасно сломали вещи из-за тонкости, которую вы не помнили?)

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

• Многие такие программисты слишком сосредоточены на «прохладных вещах» (вроде оптимизации каждого последнего цикла из их кода или нахождение умного способа запугивать, казалось бы, простой кусок кода в шаблон MindBogggling) для понимания коммерческих реалий (например, он может иметь неприятности, чтобы получить свой код, работающий и отправляемый в сроки, потому что он сосредоточивается на сжатии ненужных выступлений, а не только для того, чтобы сделать работу)

• Насколько хороши его дизайн? Я делаю большую часть своего дизайна и думая, когда записываю документы / комментарии. Пытаясь объяснить вещи читателю моих комментариев, я выдув много недостатков и допущений, которые я иначе пропустил. Я бы пошел так далеко, чтобы сказать, что я обычно пишу комментарии (мой намерение / дизайн), а затем синхронизируйте код с ними. В большинстве случаев, если в моем коде есть ошибка, это код это не правильно Не комментарий.

• Он не понял, что, используя хорошее переменное наименование, хорошо спроектированные префиксы / конвенции / конвенции, а также комментарии документации, он может сделать гораздо лучшее использование невероятных функций экономии времени его IDE (Auto-Complete, Intellisense Etts) и Code намного быстрее, с более низким уровнем дефектов.

Принципиально он, вероятно, не понимает, как написать хорошие комментарии:

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

2) Способ / класс Комментарии должны описать а также абоненту, все, что им нужно знать, чтобы использовать этот класс, без необходимости заглянуть внутрь «черный ящик» кода реализации. Они смогут быстро понять, как использовать класс / метод и понять все побочные эффекты и «договор», который обеспечивает API - то, что может быть нулевым и тем, что должно быть предоставлено, и какие исключения будут брошены и т. Д. Если вам нужно прочитать код, чтобы получить это, это либо плохо инкапсулировано, либо плохо документировано.

3) Используйте инструменты, как мой Атоминерутилс наркома Ghostdoc., Это означает, что его документация комментариев может быть сохранена в синхронизации с кодом с очень небольшим усилием.

Answer 3

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

Answer 4

Лично я не пишу много комментариев, но общие типы комментариев я пишу:

• (эскиз) доказательства того, что мой код правильный
• Объяснения Почему бы не просто сделать очевидную вещь (например, потребуется оптимизация, API, я называю шокирующе вводить в заблуждение, «очевидная вещь» привела к тонкой ошибке)
• Описание входного края, который требует специального обращения, объясняя, почему появляется специальный код обработки
• Ссылка на требование или спецификацию, которая манирует поведение, реализуемое определенной линией кода
• Описание верхнего уровня серии шагов, предпринятых: («Сначала получите вход», «Теперь полосайте обертку», - наконец-то разбирайте его «), что не нужно, если имена функций вызываемых для каждого шага, хорошо - и однозначно и однозначно в контексте, но я не собираюсь писать обертку ничего не делать для общей функции, просто чтобы дать ему более конкретное имя для одного использования
• Документация должна быть извлечена автоматически. Это большая доля комментариев объема, но я не уверен, что «действительно считается».
• то, что мог Будьте частью задокументированного интерфейса, но не потому, что им может потребоваться измениться в будущем, или потому что они внутренний помощник, которые посторонние не нужны. Следовательно, полезно для того, чтобы исполнитель был в курсе, но не для пользователя. Инварианты частных классов включены в это - действительно ли вы хотите прочитать весь класс каждый раз, когда вы хотите положиться на «этот член, ненутренний», или «размер не более, чем емкость», или «доступ к этому члену должен быть синхронизирован "? Лучше проверить описание члена, прежде чем присвоить ему, чтобы увидеть, разрешено вам. Если у кого-то нет дисциплины, чтобы избежать разрыва явно комментированного инварианта, ну неудивительно, что все их комментарии неверны ...

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

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

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

Иногда хорошее название проходит долгий путь к замене комментариев. Однако имена могут быть просто вводящие в заблуждение в качестве комментариев, если они ошибаются. И, давайте честным, часто имена, по крайней мере, слегка вводящие в заблуждение или неоднозначно. Я сомневаюсь, что автор этого поста в блоге пойдем в протяжении замены всех имен с «var1, var2, func1, func2, class1, class2 ...», просто чтобы убедиться, что они не отвлекаются на оригинальные автора Неправильные намерения для кода. И я не думаю, что это кто-нибудь, чтобы сказать, что «комментарии всегда ошибаются», чем сказать, что «имена переменных всегда ошибаются». Они написаны одним и тем же человеком одновременно с той же целью.

Answer 5

Некоторые комментарии полезны и хорошие, другие комментарии нет.

Да, комментарии и код должны быть временными, но вы не должны семереть самостоятельно. Ваша система управления источником должна управлять этим для вас, и вы сможете получить доступ к этой информации (например, используя cvs annotate или svn blame).

Answer 6

Комментарий Зачем Вы делаете что-то, а не то, что вы сделали синтаксически.