DEV Community

Discussion on: Do Code Comments Deserve a Special Spot or Can Well-Written Code Speak for Itself?

Collapse
 
bradtaniguchi profile image
Brad

Unless all the code you are working on is "boilerplate", comments should show up once you start doing things that are different than what already exists in the codebase.

Other considerations I usually have are providing external context for a reviewer reviewing my code, such as why such a thing changed and comments to the external reference.

I think of it like "footnotes" in a book, a book can flow freely and be well written without having footnotes, but having those footnotes can help provide context to a reader if such is required.

These "footnotes" are usually more important in situations such as initial review, and refactoring. Odds are if your bug fixing you hopefully aren't running into a wall of comments, as that is a sign you feel into "commenting complex code" rather than just simplifying the code to make it simpler, but that isn't always possible.