Действительно ли общепринято, что комментарии являются злыми в больших кодах .NET?

Question

Я работаю тестером над проектом для небольшой финансовой компании.Хотя руководство иногда принимает «интересные» решения, команда, с которой я работаю, кажется достаточно компетентной.Так как я обычно нахожусь в части разработки уравнения (этот проект является временной работой), я заинтересовался кодом проекта.Сегодня я заметил, что код кажется довольно легким для комментариев (что не является преувеличением; их нет), и мне сразу же сказали, что это сделано намеренно и что комментарии исходного кода являются вашим злейшим врагом в большом кодеbase. "

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

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

Answer 1

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

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

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

Answer 2

Это довольно странное чувство.

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

Комментарии в некоторых случаях важны для what : часто нужно что-то делать, чтобы сделать что-то хитрое, и комментарий может объяснить, что происходит.

xmldocs очень важны для объяснения контракта метода. Некоторые языки (например, Eiffel) на самом деле имеют синтаксис для указания контрактов, но в большинстве языков это должно указываться в комментариях. Даже принимая во внимание идеал самодокументированного кода, вы не можете объяснить контракт метода в названии метода!

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

Answer 3

В моей корпорации мы достаточно часто слышали строку «код самодокументируется», что шутим по этому поводу. В VisualStudio Magazine есть хорошая статья под названием Комментировать или не комментировать , которую стоит прочитать.
Лично я считаю, что комментарии необходимы и должны поддерживаться вместе с проектной документацией. Проблема в том, что когда нет шаблона или общего понимания того, что означают «комментарии», почти невозможно поддерживать согласованность между кодом и комментариями, поэтому они становятся бесполезными, а программисты склонны их игнорировать.

Answer 4

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

Кроме того, очень легко утопить то, что делает ваш настоящий код во всей xml-документации.Посмотрите в базовых библиотеках java или .net несколько по-настоящему страшных примеров этого.

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

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