CODEWITHSUNDEEP
c#.netrider
Lucas
Lucas

Reputation: 359

What is the proper way of creating documentation in .NET (or general)?

I am just starting my professional career with software development and I got first project to get to know with it.

What very suprised me, was the fact ~30% of code are actually comments with 

<param name="">
<summary>

and so on. I think .NET devs know what I mean.

The point is, it is making this code very ugly. I understand it helps Swagger to make documentation, it helps IDE to describe methods and their params, but... it also makes code ugly.

Is it common practice? Or can it be done diffrent way?

BTW, I know it can be hidden in IDE, but this is not what I am asking about.

Upvotes: 4

Views: 345

Answers (2)

Derviş Kayımbaşıoğlu
Derviş Kayımbaşıoğlu

Reputation: 30665

Just to give you an example... check Microsoft Reference Source.

Documentation is necessary and it looks ugly to others if you don't do it. Understandable/maintainable code is good code for everyone.

You cannot go away from it and you must not.

Upvotes: 8

Steven Benitez
Steven Benitez

Reputation: 11055

Including documentation comments in code as shown below is the preferred way to write documentation. Following this approach, developers can read the documentation in their IDEs or an HTML version can be generated for the web.

/// <summary>
/// An effective trap for capturing delicious, tasty roadrunners.
/// </summary>
public class RoadrunnerTrap
{
}

With that said, you can also name your classes, variables, and methods clearly to begin with and avoid having to write as much documentation. Not having documentation is usually bad but too much obvious or repetitive documentation is worse.

Upvotes: 0

Related Questions