Someone recently DM'd me asking why Sdump lacks godocs. I thought it'd make sense to write my thoughts on this.

TLDR: Most comments are bad, end up unmaintained and most times just redundant. I lean more towards writing readable and non complicated code as against relying on comments all the time.

When it makes sense to write comments

• Esoteric implementations.
• When a non obvious solution is used instead
• Code attribution. If a particular function or logic was lifted off Stackoverflow or a GitHub gist.
• Legacy support for some options/filter/function. This could something as simple as a legacy JSON key or similar.

Exceptions

Libraries

For libraries and OSS projects, I strongly think public APIs need to be documented clearly. Even if they feel or look clear enough. As an example, it can be quite common to see Close methods that are actually no-op in practice. Having comments on those helps to make sense of expected behavior + reduces support tickets.

Team Standard

If the team decides to comment every single function, then I have no choice than to follow suit but grateful for the fact that I am yet to work with any team that would comment a getUserIDFromJWT function saying This function gets a user ID from the JWT. And here is to hoping I don't jinx it

Code at the end of the day should be written for other humans. Making them readable as much as possible gets rid of the need for a large chunk of comments