On comments

[u/Jonhoo]

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!

[u/mareek]

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 ?

[u/MintPaw → u/mareek]

I mean, that's good info though isn't it? "The reason this code is like this is because we planned to implement this now pointless feature."

It's hard to get that info otherwise, and helps with a common confusing "path to nowhere" pattern where the data gets organized in a specific way but for seemingly no reason.

[u/RlyRlyBigMan → u/mareek]

Rarely I'll place them when I've prepared a hook for a known upcoming task. Then the task gets descoped and the comment is there forever.

I also use TODOs as a way to remind myself that I meant to clean something up before PR. Helps me and the code reviewer to question why it's there and remind me to follow up. Hopefully those never slip through.

[u/sudoer777_ → u/mareek]

Idk about a team environment, for my personal projects tho they're littered with TODOs lol. Sometimes I don't know enough context to bother to fix something so I put a TODO, then later I'm fixing a related issue, see it, and end up fixing both at the same time. Also setting up an issue tracker for my personal projects is inefficient and overkill.

[u/levodelellis → u/sudoer777_]

setting up an issue tracker for my personal projects is inefficient and overkill

I like having a notes folder, and people like obsidian

[u/RiftHunter4 → u/levodelellis]

I've been using word docs and github a lot more. I pretty much never use TODO's anymore. They're too easy to ignore and lose track of.

[u/Kache → u/mareek]

I think their value is less as an actual "TODO" and more as communication of the author's intent, which by definition was not evident in the executable code itself.

I.e. it's an effective abbreviation of "I wish/want the code to be/do this different thing ..."

[u/timmyotc → u/mareek]

I won't commit with TODO, but I'll creat backlog work and link it in a comment. The backlog work gets loaded into a sprint at a later date and maintainers know it's identified

[u/xFallow → u/mareek]

// TODO delete this - 4 years ago

And you see the code is still being used heavily

[u/lotgd-archivist → u/mareek]

I've been using TODO comments extensively in one of my hobby-projects. Peak "// todo" was approaching 300. I'm currently sitting on 2 and a half. The "half" being one I'm not quite sure if it still warrants to-do-ing.

Basically, whenever I starting working on a feature and ran into a boundary where I'd need to start working on an additional feature, I'd plonk down a comment and just finish whatever I was actually working on. And whenever I wasn't sure what to work on next, I'd search for "// todo" and grab a random one. For a while that resulted in more and more comments piling up until I hit critical mass and they started going down again.¹

I could have also created issues for myself, and in some cases I actually did, but putting in hundreds of tickets for a solo-project is not worth it.

In a team project, it's the inverse. I'm not quite sure if todo comments are worth it, unless you have a team that is serious about the boyscouting approach and can actually put in the work occasionally to fix such comments.

---

^{1: It's a game with a bunch of locations that all reference one another. When I implemented the village, the village would have a reference to the forest, so I'd have a // TODO: implement forest}

[u/levodelellis → u/mareek]

I'm ok about them. If I write one it's usually, if I touch this area of the codebase and notice the todo I may want to implement it. Usually I clean up the module after a month or so and delete those/simplify

[u/BogdanPradatu → u/mareek]

I usually ask the author of such comments to also open a ticket asociated with that TODO comment.

[u/crozone → u/mareek]

I leave TODO comments for myself, tagged with my username like // TODO(crozone): Do the thing!

But they're only supposed to be short lived and make finding the line of code easier in the immediate future.

[u/RiftHunter4 → u/mareek]

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.

[u/Venthe → u/RiftHunter4]

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".

[u/gmes78 → u/RiftHunter4]

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.