комментирующий код C # visual studio лучшая практика

Question

Я ищу довольно произвольный ответ, так что это может быть больше дискуссия.Мне интересно, как лучше всего комментировать мой код C # в visual studio.Прямо сейчас я использую тройной /// для генерации xml и использую замок из песка для создания файла chm или html.Но моя проблема в том, что я использую комментарии к коду по двум причинам:

1. Когда другие разработчики используют мой код, они могут читать документацию, как intellisence, так и chm.или HTML-файл.
2. Но я также использую комментирование в качестве напоминания для себя.Поэтому я могу вспомнить свои мысли, когда через полгода я вернусь к некоторым сложным методам.

Как можно достичь обеих целей, не мешая друг другу, и в то же время быть быстрой задачей, не занимая много времени кодирования?

Answer 1

Лучший совет, который я могу вам дать:

Не комментируйте плохой код; перепиши это!

Если методы очень сложны, большую часть времени вы делаете что-то не так (не всегда, но очень близко к всегда). Написание читаемого кода сложно, но оно окупается, потому что писать хорошие комментарии, которые вы (или ваши колледжи) поймете год спустя, также сложно (и, возможно, даже сложнее). Чтобы прояснить ситуацию, нужно разбить методы на более мелкие, хорошо именованные и использовать очень четкие имена переменных.

Книга, которая мне очень помогла в создании лучшего кода, была Роберт Мартинс Чистый код . Если вы не читали это, пожалуйста, сделайте. И пусть все разработчики в вашей компании прочтут это.

Удачи.

Answer 2

Используйте /// комментарии для документирования вашего публичного и защищенного API.Используйте <remarks>, чтобы описать, как использовать ваш API.Аудитория этих комментариев - другие разработчики, использующие ваш код.

Используйте комментарии //, чтобы комментировать ваш код всякий раз, когда одного кода недостаточно для полного понимания происходящего.Аудитория этих комментариев - вы, возможно, три месяца в будущем или другой разработчик будет поддерживать ваш код.Вы можете использовать специальные комментарии, такие как TODO или BUGBUG, чтобы пометить коды, к которым вы должны вернуться.

Answer 3

Я комбинирую оба стиля комментирования - /// для «публичной» документации по классам, методам и т. Д. И // для «приватных» комментариев для себя или кодировщиков, которые следуют за мной, чтобы читать.