Я думаю, что комментарии к коду очень важны, особенно для открытых методов и свойств. Люди могут иметь в виду хорошо, когда говорят, что их код описательный, а может, и так, но подумайте о новом парне, который смотрит на это:
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>
Видите разницу?
Я склонен использовать только сводные параметры и возвраты, поскольку все они отображаются в intellisense, все остальное, как замечания, и может быть пустой тратой времени, поскольку они не всегда отображаются.
Что касается парня, который отказывается обновлять свои комментарии после изменения чего-либо. Обзоры кода должны это уловить. Лично я использую xml-комментарии о частных методах и поддерживаю два, но этот - личный выбор. На общедоступные методы и свойства? Я не является обязательным.