Standardize Project Commenting Style

[DoubleDeez]

Right now there's a mix of comment styles on Classes and Members A standard should be determined and the project should be changed to adhere to the standard.

Examples from codebase:

///<summary>A synchronization class with three primary features
///<para>It tracks the ping to each client</para><para></para>
///<para>It tracks what the local OS.GetTicksMsec() is on each connected client relative to the server (server only)</para><para></para>
///<para>Finally it takes care of making sure all players are fully synchronized on request. 
/// Usually when a player joins or level is changed</para>
///</summary>

///<Summary>This contains what we think is the GetTicksMsec offset for each player</summary>

/*
* MDGameSession
*
* Class that manages the current multiplayer state of the game.
*/

// Registers a new node to MDFramework systems

[DoubleDeez]

I'm personally not a fan of the comments with the XML tags as I find it verbose, but I don't have strong feelings on a specific style yet.

[Beider]

The only reason I like the XML tags is because it allows you to hoover over stuff (in most decent editors) when you are writing code against the framework, that way people don't have to go into the class to check for comments.

That being said I am used to javadoc so I may be biased here.

[Meister1593]

Personally, i like XML tags because of that hoover over stuff, this is much better than going to function declaration to see what it does.

[DoubleDeez]

Yeah I was surprised when I just tried and noticed that VS Code doesn't show the tooltip without the XML tags but Visual Studio does.

[DoubleDeez]

I think I'm gonna go with whatever this extension generates: https://marketplace.visualstudio.com/items?itemName=k--kato.docomment

[Beider]

That looks like a good idea. Should we go with any particular rule on what needs these kinds of comments or not? Personally in most projects I worked on the rule was generally that anything that is public needs proper documentation. I guess in C# it also makes sense to properly document anything that is virtual as well. But I wouldn't be too bothered about private/protected stuff.

[Meister1593]

I think I'm gonna go with whatever this extension generates: https://marketplace.visualstudio.com/items?itemName=k--kato.docomment

This works pretty much the same as in Rider, i think this would be nice.

[DoubleDeez]

That looks like a good idea. Should we go with any particular rule on what needs these kinds of comments or not? Personally in most projects I worked on the rule was generally that anything that is public needs proper documentation. I guess in C# it also makes sense to properly document anything that is virtual as well. But I wouldn't be too bothered about private/protected stuff.

The rule I was loosely following originally was pretty much that. Anything public and anything virtual needs a comment.

[DoubleDeez]

Decision

Just to summarize the solution to this so it's all in one comment and easy for a newcomer to implement:

• All comments should follow the style provided by either Rider or this VSCode extension
• At least the summary field should be filled out, there should not be any empty fields (remove or fill them)
• At a minimum, comments should be added for all public and protected classes, fields, properties, methods, etc

Marking with good first issue as this would help someone learn all areas of the framework