Как вы думаете, что является лучшей структурой комментирования C #? В частности, с Visual Studio

Question

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

Итак, что, по вашему мнению, является наилучшим способом структурирования C # с комментированием в Visual Studio?

Answer 1

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

Кроме того, я бы прокомментировал любые конкретные алгоритмы или фрагменты кода, которые трудно будет расшифровать через шесть месяцев. Такой «эгоистичный» подход к комментированию (т. Е. Предполагается, что вам придется поддерживать этот код позже) часто приводит к лучшему балансу достаточной документации без перерасхода.

Answer 2

Я стараюсь следовать некоторым основным правилам при написании комментариев.

• Комментарии должны быть простыми
• Комментарии должны обеспечить ясность
• Напишите документацию, прежде чем писать реализацию
• Документ почему вы делаете что-то, а не что вы делаете.
• Использовать встроенные (в стиле XML) комментарии для интерфейсов, методов, свойств и классов.
• В верхней части каждого файла указывается сводка (например, Something.cs) с именем, описанием, историей разработки и информацией об авторских правах
• Добавить комментарии для исправления ошибок (с номером ошибки, если необходимо)
• Используйте полезные аннотации, такие как // TODO // BUG и // BUGFIX
• Не комментируйте код, если вы не планируете его использовать
• Добавляйте комментарии над строкой кода, к которой они применяются, а не до конца строки
• Попробуйте ограничить комментарии одной строкой
• Используйте // вместо / * * / для многострочных комментариев
• Будьте ясны - не используйте "foo", "bar" и т. Д.
• При необходимости следовать правилам обсадной колонны (например, CamelCasing и PascalCasing)

Answer 3

"Много и часто" - Бильбо, Хоббит.

Более серьезно, прокомментируйте неочевидные вещи и скажите читателю, какова цель кода и, возможно, почему вы его выбрали.

Это не изменится в зависимости от языка.

Answer 4

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