There is a big difference between working on a single code base for 5 years or working on 50 things at the same time.
I've done both, and it has a lot of impact on how I write comments.
If you hate comments, you probably are working on a long-running project where comments feel obvious or even forced by management.
20 years ago, there was a plugin for Visual Studio that automatically added comments like this:
/// <summary>
/// Gets or sets Customer.
/// </summary>
public Customer GetCustomer {
get ...
set ...
}
Managers loved this because they could say that the team wrote sufficient comments. But looking at this, you probably agree with me that this comment is pretty useless.
When I was a junior programmer, this led me to believe that comments were no good at all. I just did not see their benefit.
As a freelancer, I work on many projects. Most of them are small, with less than 50 code files, but I noticed how hard it is to get into such projects after a while.
I’m in the middle of modernizing 19 Microsoft Store games. They were built between 2010 and 2026. New images, unified navigation. Undoing a lot of overengineering.
Especially game mechanics like dragging and snapping cards. I noticed there was not a lot of documentation.
Sometimes I documented exceptions to a rule, but overall I saw an "I know how it works" attitude.
So when reading the code, I started to document methods. Methods I would never have thought to document while writing them.
Here is an example. I found this undocumented if-statement and wondered why I used Take(board.Count / 2).
// While testing the game and creating new maps, the board might have less than 144 stones.
// For this, the tiles will be limited to exactly or fewer than the stones on the board to prevent an infinite loop in PlacePairsOnEmptyBoard.
if (pairs.Count > board.Count / 2) {
pairs = pairs.Take(board.Count / 2).ToList();
}
When I removed the Take method, the game worked but crashed during development of a new map. So I reverted the code and added the comment. When I revisit the code in 6 months, I will not be tempted to remove this if-statement because I know what edge case it serves.
So I documented a lot of such edge cases and what happened? Something strange!
In the process, I found unused code and thinking errors. With some stuff that worked, I thought: why does it work? Or why is it so complicated?
I started to document across games and found many cross-project concerns. I was able to unify all navigation methods and, in the process, delete a lot of code.
Creating documentation brought me much more than easy-to-understand methods. It brought a unified structure that all games now must follow. In the process, I introduced a few new bugs that, once found, I could fix in 19 games at once.
Here is an example. This is library code that I use in each game. Overrides must call base.Dispose(). 20 years ago, I would never have documented it like this because I would just assume I would remember. These days, I add the comment to the code so I don't have to remember, and when the code crashes, it crashes so close to my comment that it gives me the solution.
/// <summary>
/// Dispose CloseAction so it cannot be called twice when double-clicking buttons.
/// If modal dialogs need to dispose, override and call base.Dispose();
/// </summary>
public virtual void Dispose() {
CloseAction = null;
}
The documentation became part of my scaffolding and instead of seeing it as a future reference, the power of commenting is much more in the writing of them.
Written by Loek van den Ouweland on June 15, 2026.