Возможный дубликат:
Можно ли написать хороший и понятный код без комментариев?
При кодировании часто слышу, что если комментарии нужны, значит, код слишком сложно понять. Я согласен с тем, что код должен быть читаемым, но часто сам язык заставляет код трудно следовать из-за "сантехники" и странного синтаксиса. Я использую наиболее часто используемые языки:
Java Mootools Рубин Erlang
Любые советы будут оценены? Благодаря
Я не думаю, что вы можете писать код без комментариев.
Вкратце, код документирует как. В комментариях говорится, почему.
Я бы ожидал, что в комментариях будут указаны условия, по которым код был написан так, ограничения, налагаемые требованиями или внешними факторами, влияние, которое может возникнуть в результате изменения кода, и другие ошибки. Комментарии содержат информацию, которая не содержится в самом коде.
Рекомендуемое чтение: Чистый код Роберта К. Мартина.
Вкратце, вы должны
Не бойтесь извлечь даже умеренно сложные выражения из операторов if; который яснее читать, это
if (i >= 0 && (v.size() < u || d == e)) ...
или
if (foundNewLocalMaximum()) ...
(Не пытайтесь найти какой-либо смысл в первом фрагменте кода, я просто сделал это: -)
Комментарии в чистом коде почти никогда не нужны. Единственными исключениями, о которых я могу думать, является использование какой-либо неясной языковой функции (например, метапрограммирование шаблонов С++) или алгоритма, и вы даете ссылку на источник метода/алгоритма и его детали реализации в комментарии.
Основная причина, по которой любые другие комментарии не очень полезны в долгосрочной перспективе, заключается в том, что изменения кода и комментарии не обновляются вместе с изменениями в соответствующем коде. Поэтому через некоторое время комментарий не просто бесполезен, но он вводит в заблуждение: он говорит вам кое-что (примечания по внедрению, рассуждение о выборе дизайна, исправления ошибок и т.д.), Который относится к версии кода, которая давно ушла, и у вас есть не знаю, актуально ли это для текущей версии кода.
Другая причина, по которой я думаю, что "почему я выбрал это решение", чаще всего не стоит документировать в коде, заключается в том, что краткая версия такого комментария почти всегда будет выглядеть как "потому что я думаю, что это лучший способ" или ссылку на, например, "Язык программирования С++, глава 5.2.1" и длинная версия будут трехстраничным эссе. Я думаю, что опытный программист чаще всего видит и понимает, почему код написан так без особого объяснения, и новичок может не понимать даже самого объяснения - не стоит пытаться охватить всех.
И последнее, но не менее важное: модульные тесты IMO почти всегда являются лучшим способом документации, чем комментарии к коду: ваши модульные тесты действительно документируют ваше понимание, предположения и рассуждения о коде довольно эффективно, причем вам автоматически напоминают, что синхронизировать их с кодом, когда вы их сломаете (ну, если вы действительно запускаете их с помощью своей сборки...).
Комментарии по коду должны сообщать вам, почему вы изначально сделали что-то определенным образом. Это не должно означать, что код слишком сложно понять.
Наиболее важные вещи, которые следует соблюдать:
Я думаю, что полезно писать комментарии для ПОЛЬЗОВАТЕЛЕЙ вашего кода - что делают классы/методы/функции, когда их называть и т.д. Другими словами, документируйте API.
Если вам нужно прокомментировать, как работает метод в интересах сопровождающих, я думаю, что код, вероятно, слишком сложный. В этом случае реорганизуйте его в более простые функции, как говорили другие.
Я лично считаю, что никаких комментариев вообще не так плохо, как с чрезмерным комментарием. Вам просто нужно найти правильный баланс. Об использовании длинных описательных имен для вещей, это о суммировании для меня: прочитать это Также читайте Kernighan и Pike на длинных именах.
Вам нужно следовать определенным правилам.
Factory имя FooFactory.