[CodeStyle] Provide a summary for each method you write

[ViMaSter]

Provide a summary for each method you write, which includes:

• A small description of your method
• A small description of each parameter
• A small description of the return value

---

So... I'm not really a fan of comments for methods. ^{Shocking, coming from the guy who build a documentation generator. : D}
Enforcing comments on methods in my experience ends up in comments that are only "englishifying" information already obtainable from a method's signature or body. With the added risk of not being updated when making changes to it, introducing conflicting information.

/// <summary>Generate a human-readable string from a player name and clan symbol (for example [GGJJ]ViMaSter)</summary>
public string GenerateDisplayName(string playerName, string clanSymbol) => $"[{clanSymbol}] {playerName}"

//  ^  this is not only was redundant, but whenever the space between the clan symbol and player name was added, the comment wasn't updated too

Comments for classes or inside method bodies technically also suffer from the problem of being outdated when underlying code changes, but being either in a higher (class-level) or lower (per-instruction) context, usually means they supply information on why they exist, not what they do.

For example: A DisplayNameHelper class was added, each method taking data and generates human-readable strings. That itself is deductible from the names of methods in classes. So no need for comments.

However, let's say that this class was created, as previously 20 UI elements had to individually generate locale and culture information about a user only to immediately discard it, once whatever they want to display was generated and then be re-generated every time the underlying data changed, resulting in duplicate code and processing overhead.
This kind of information isn't inferable from a method or parameter names and should be present at the same place as the underlying code. A quick excerpt on top of the class (similarly to what gets written into a related GitHub Issue or Pull Request) would serve whoever discovers this code later on well.

The same applies comments inside method bodies for methods that do a lot and aren't worth encapsulating, as that logic is only present once for this specific method. (For example ActionDecoder.OnNewActionLine() or test cases.)

And to address the elephant in the room: I'm totally okay with the comments for ActionDecoder action methods, as they serve another audience (namely our writers). That fact alone, forces whoever is writing comments for a new action to think about who they are writing for and which information is actually critical and non-deductible from method or parameter names.

[PhoebeMitchell]

Mildly torn on this one. I agree a lot of our summaries are kinda pointless, then again, I think having a green section above each method looks nice and orderly and makes the start of methods easy to find 😅.

[ViMaSter]

Admittedly, I think I'm too used to ReSharper's Fuzzy Search navigation and "goto usages/declaration", that I don't actually look at full files anymore. 🙈

If it helps you keep an overview, I think that's a good reason to keep it; still trying to think of alternatives that might achieve the same goal.
Starting out with all methods collapsed when opening a new file would be an idea. That way, anything that's not of interest is hidden until you expand it. It's also purely client-side, instead of being inside the code.

[lyndsiWilliams]

I think I'm on @PhoebeMitchell 's side for this one. In a wall of text, the summary blocks definitely help with scanning for specific methods (especially for less-experienced folk like myself 😅). And on that "less-experienced" note, the summaries help me know what the method is doing without picking apart the code and Googling the stuff I don't understand. The title of method could definitely describe what the method is doing, but I won't always know for sure what it's doing in the context of its application, you know? I like the summaries so I know for sure what it's doing without having to assume. I don't like the idea of collapsing all methods as a resolution because that would make it harder for me to scan the code as a whole. I would def be open to another option if there is one brought up, but for now, summaries seem like the best deal for me.