Feb 02, 2024
No comments and that is fine too
2 min read
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.
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.
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