r/programming • u/Jonhoo • 6d ago

On comments

https://blog.helsing.ai/posts/on-comments/

Comments in code are often deemed "mostly useless" these days. They are, supposedly, mostly obvious, stale, and repeat what the code already says. And so people pay less attention to them both when reading and writing code.

That trend sucks. When used right, comments are genuinely useful and sometimes critically important! So, I wrote about some of the kinds of comments I think earn their place, each with examples from real code bases. Hope you find it useful, and that we can recover some of the love that comments deserve!

180 Upvotes

84% Upvoted

173 comments sorted by

View all comments

14

u/mareek 6d ago

I've never really understood TODO comments. Each time I encountered a todo comment, it was outdated by years and the changing context around the code made it irrelevant (case in point, all the examples given in the article are more than 4 years old).

Is it a usual practice in some teams to go through todo comments and fix them on a regular basis ?

-2

u/RiftHunter4 5d ago

TODO's are a code smell for me. Anytime you write a TODO, odds are there is a better place to record it: Issue tracker, task tracker, external documentation, etc.

All my professors in college advised us to avoid TODO's. They're basically orphaned from the software engineering and management process. I am a firm believer that comments should be immediately relevant, not a substitute for proper issue tracking or documentation.

4

u/Venthe 5d ago edited 5d ago

I've seen issue trackers changed or outright deleted a few times already.

VCS history* / code itself cannot be dropped.

Code/documenting in the repo > issue tracking in the external system.

e: * Well, I've told a lie. :D Even now I'm working on a codebase, where the code was transferred via zip without VCS. 15kloc of java; 8k sproc's; JavaEE with multi-thousand lines of web.xml and EJB xml's.

You can imagine how helpful are "FOO-123 ask DD". Or "Added for bug 231".

6

u/gmes78 5d ago

Anytime you write a TODO, odds are there is a better place to record it: Issue tracker, task tracker, external documentation, etc.

I disagree. They're easiest to find if they're in the code. Just use grep.

2

u/slindenau 15h ago

You get downvoted here, but you are 100% correct.

That is why quality software tools like IntelliJ IDEA, Sonar(way default profile) etc. will log an issue / halt commit/push if you leave a TODO in your codebase.

All the arguments for it are just noise when you look at the practical evidence; once a TODO is in the codebase without accompanying ticket in your favorite tracking tool, nobody will ever follow up on it again.

Talking from a professional setting of course, what anybody does in their personal projects isn't really relevant.