Зачем мне использовать эти неприятные комментарии в коде C#/.Net?

Question

Я строй приложения и одним из требований является использование комментариев, как это:

/// <summary> 
/// Creates new client. 
/// </summary> 
/// <param name="uri">The URI.</param> 
/// <param name="param">The param.</param> 
/// <returns></returns> 

Я понимаю, что это легко для различного рода инструментов, чтобы генерировать документы на основе этих XMLs. Но это значительно снижает читаемость кода, и это именно то, чего мы, люди, пытаемся достичь.

Можно ли заменить этот подход любой другой техникой в ​​.Net? И какой лучший способ улучшить удобочитаемость и чистоту кода?

Answer 1

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

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

Answer 2

При использовании сторонней библиотеки dll intellisense причиняет вам вред?

Я не думаю. И это одна из основных причин использования этого комментария.

Предположим, вы исправляете dll (или записываете класс, который будет использовать кто-то другой), не будет ли он полезен для него/нее, что, когда он набирает, он знает, что делает этот метод и что работает с параметрами?

Answer 3

Документация и комментарий VS не уменьшают удобочитаемость кода для большинства людей, это наоборот. если вы чувствуете, что эти комментарии делают код менее читаемым, вы можете свернуть их или даже изменить цвет, который они нарисовали.

, но подумайте, насколько это полезно, когда вы наводите курсор над функцией, и информация о методе и его параметрах появляется. Это читаемость в лучшем случае

Answer 4

Вы должны абсолютно не избегать этих комментариев! Они предоставляют IntelliSense для Visual Studio и могут составлять основу автоматических инструментов документации, таких как SandCastle. Насколько мне известно, ваш единственный вариант с точки зрения техники - это один (чтобы получить все эти функции).

Чтобы облегчить чтение, вы можете свести к минимуму каждый комментарий с помощью [-] рядом с первым тегом в Visual Studio. Таким образом, вы увидите только первую строку. Это может быть полезно при ежедневной работе над кодом.

Я также обнаружил, что выпадающие списки навигации полезны для поиска методов внутри класса, если вы обнаружите, что xml затрудняет навигацию/просмотр.

Но их использование хорошая вещь, и вы привыкнете к тому, их вокруг

Answer 5

Различные форматы документации подходят для различных сценариев.

XML-комментарии лучше всего подходят для автоматической генерации файлов справки и Intellisense. По необходимости они являются более подробными, чем другие методы, поскольку они требуют наличия определенных тегов для создания документации. Хотя синтаксис может быть лучше, помните, что они были созданы обратно, когда все думали, что XML - это крутая идея.

Для общего комментирования вы можете использовать грамотный стиль программирования и инструменты, такие как nocco для создания и отображения HTML-страниц. Инструмент извлекает комментарии и отображает их на странице HTML вместе с кодом. Страница nocco сама является выходом nocco на nocco.cs

Nocco даже использует Markdown для форматирования.

Конечно, вы можете смешивать и сопоставлять методы, например. использовать комментарии XML для общедоступных методов, грамотные комментарии для внутренних комментариев.