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

Question

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

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

Answer 1

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

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

Answer 2

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

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

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

Answer 3

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

• Комментарии должны быть простыми
• Комментарии должны обеспечить ясность
• писать документацию прежде чем писать реализация
• ДОКУМЕНТА почему вы делаете что-то, не какой вы делаете.
• Используйте встроенные (XML-стиль) комментарии для интерфейсов, методов, свойств и классов.
• Предоставьте резюме в верхней части каждого файла (например, Something.cs) с именем файла, описание, история развития, а также информацию об авторских правах
• Добавить комментарии для исправления ошибок (с числом ошибок, если это уместно)
• использование Make полезных аннотаций как // TODO // BUG и // BUGFIX
• не закомментировать код, если вы не планируете использовать его
• Добавить комментарий выше линии (ов) кода они применяются, не в конец строки
• Постарайтесь ограничить комментарии одной строкой
• Использование // вместо/* */для многострочного комментарии
• быть ясно - не использовать «Foo», «бар» и т.д.
• следовать правилам обсадные, где необходимо (например, camelCasing и PascalCasing)

Answer 4

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