XML- комментарии:Использовать или не использовать?

Question

Мои коллеги редко (если вообще когда-либо) используют XML-комментарии при работе над нашим программным обеспечением (не могу сказать, что я чем-то лучше).Недавно я увидел преимущества их использования, но действительно ли они того стоят, если код, который они документируют, написан четко (выразительные / описательные имена переменных / функций, некоторые встроенные комментарии)?

Спасибо!

Answer 1

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

Однако комментарии к документации полезны для пользователя классов, поскольку они (должны) содержать описание функциональности класса или методов, а не описание кода.

Answer 2

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

Linker.Extract(IpoValidator validator, MeanDexIndicator Indicator)

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

 <Summary>Extracts The Fumble <\Summary>

Являются пустой тратой энергии.Следующее лучше:

 <Summary>
 The Fumble needs to be extracted before the bopper can be used. In order for 
 extraction to work a validator and indicator need to be provided. Once extracted 
 the bopper is available in the property Linker.Bopper. On fail this 
 method will raise the CrappedOutException.
 </Summary>

Видите разницу?

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

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

Answer 3

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

Answer 4

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

Answer 5

Что касается внутреннего кода и комментариев, вот сообщение Автор: Джеффри Палермо это я только что прочитал и вынужден согласиться с этим.

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

Answer 6

Нет ли тега аннотации, который функционально игнорируется, но может быть обработан некоторым XSLT для превращения непосредственно в документацию?Комментарии хороши (и я их использую), но я думаю, что значение тега аннотации и его прямое преобразование могут перевесить использование комментария в качестве документации.Итак, вкратце, используйте теги аннотаций для документации, которую будут читать другие, используйте комментарии для заметок для себя или для материалов "за кадром" (например, "БОЖЕ, ИСПРАВЬТЕ ЭТО, ПОКА МИР НЕ ВЗОРВАЛСЯ!").