Illiterate programming #2

Ещё интересного из экосистемы microsoft.

Есть такой пакет для .net, stylecop, для проверки форматирования C# исходников. Кроме условно полезных проверок, типа просьб явно поставить скобки в сложных выражениях, и безполезных, например правила "после закрывающей скобки должен быть перенос", есть и откровенно идиотские. Например, саммари для каждой проперти должна начинаться со слов "Gets or sets ...". Очевидно, что ценность этой воды в точности никакая, и при большом числе пропертей от повторения везде одного и того же безполезного текста начинает рябить в глазах. В особенно клинических случаях требуемая фраза становится достаточно длинной, например "Gets or sets a value indicating whether" или "Initializes a new instance of the {class name} class".

Хуже всего, однако, не это, а то что лень писать эту херню породила класс продуктов "генератор документрующих комментов". Причём их авторы не ограничились на затыкании рта stylecop-у. Они начали... генерить и вовсе всю документацию. Они провели достаточно большую работу по научению своего продукта английскому языку. Теперь метод CreateItem() автоматически сгенерит текст "Creates the item", и так далее.

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

К сожалению, многие windows-девелоперы этого не понимают и с радостью набивают исходники автогенерённым мусором, который потом приходится исправлять.

Литература:
http://stylecop.soyuz5.com/SA1642.html
https://www.youtube.com/watch?v=xeZqoCGcHSU (извините за видео, текстовых примеров авторы не приводят. zeitgeist такой вот)
Всё правильно, ценность комментариев равна ценности кода.
а я давно говорю, что в большинстве случаев doxygen-подобное == «документации нихуя нет».