I'm building application and one of requirements is to use a comments like this one:
/// <summary>
/// Creates new client.
/// </summary>
/// <param name="uri">The URI.</param>
/// <param name="param">The param.</param>
/// <returns></returns>
I understand that it's easy for various kind of tools to generate the docs based on these xmls. But it significantly decreases code readability, and that's exactly what we, humans, trying to achieve.
Could this approach be replaced by any other technique in .Net? And what's the better way to improve code readability and cleanness?
That information should pop up on visual studio when someone uses intellisense while going through your methods. This will save time since whoever is using your code will not need to go into your code (thus meaning that you also do not need to expose any of your code) and see what other comments you have written.
I think that documentation, when is kept short and to the point, is never a bad thing and it does not affect code readability.
While using a third party dll does intellisense hurt you?
I don't think it does. And this is one of the major reasons of using this commenting.
Let's say you are righting a dll (or writing a class that somebody else will use), won't it be helpful to him/her that as he types he knows what the method does and what is working of parameters?
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With