Pros and Cons of XML Documentation

Source: https://github.com/lodgeit/svcs-au_win/pull/4422

XML документация часто устаревает, и парой она мешает понимаю кода

Есть некий метод с следующей XML документацией

Вопрос такой: что делает данный метод?

Скорей всего ответ будет такой - сохраняет Request documents в store.

Но если мы взглянем на сам метод.

Судя по всему, метод сохраняет мето-инфу, а не сам документ.

И возникает вопрос: XML документация врет или метод ?

XML документация дублирует код

Вот пример, который наглядно илюстрирует то, что XML документация дублирует код

Summary

Я не против XML документации или комментов, если они не вредят понимаю коду. Предлагаю использовать XML документацию и комменты когда:

• есть какие-то магические цифры: лимиты, константы и т.д.
• есть не тривиальная логика
• когда есть, какие-то абстрации: ISbrProxyV1Client, IPdfRenderer, etc.