Have you ever seen a stop sign with another sign below it that says, “This is a stop sign”?
…
No, me neither.
Yet, step into any codebase and you’ll trip over comments doing exactly that:
<img src="https://media.daily.dev/image/upload/s--87QeBEGK--/f_auto/v1759359170/ugc/content_c1b1afc5-1024-4ee9-bff3-aa5ae90fc9b8?_a=BAMAK+ZW0" alt="carbon">
The Department of Redundancy Department strikes again!
Now, maybe you’re thinking, “Hey, it’s just some harmless noise.” Sure, but don’t get too comfortable, because i have a whole bunch more!
<h3>1. Lies, damned lies and Comments</h3>
Comments sometimes are like politicians: they promise one thing and deliver another. Maybe someone updated the function but forgot about the comment , or they just copy-pasted without updating it.
No matter what is the cause: The comments might lie, the code will not.
<h3>2. TODO or NOT TODO, that is the question</h3>
Do you know the situation where you leave something in the back of the fridge and months later it’s still there, completely spoiled, and you pretend not to see it? <code>// TODO: Refactor this.</code> is the digital equivalent of exactly that.
Adding those TODOs while developing is fine; But merging a pull request littered with TODOs? Nah. Do your team a favor: turn TODOs into real tasks in your project management tool and actually assign them. But beware because in task management land a place called “Backlog” exists, which is a synonym for “Graveyard”.
Speaking of graveyards…
<h3>3. Comments Are Not a Code Graveyard</h3>
Commented-out code just clutters the codebase. If you’re not using code anymore, delete it. You can always find old versions in the git history if you need them. In nine years as a developer, I’ve rarely had to recover old code from comments.
So then what does a useful comment look like?
<hr>
<h2>Practical Tips for Writing Good Comments</h2>
<h3>1. Do not write the comment in the first place</h3>
Whenever you think you will need a comment to explain what is happening, pause. Can you clarify the code? Comments become unnecessary when the code itself tells the story.
<h3>2. Explain the Why, Not the What</h3>
The computer cares about what the code does. Your fellow developers care about why you made it do that weird thing. If you had to pick a workaround for a browser bug, or hack something to work around an API quirk, write that down.
Do not do this:
<pre><code class="language-typescript">// Wrapper div is needed
</code></pre>
Do this instead:
<pre><code class="language-typescript">// Wrapper div is required for Firefox, see: https://bugzilla...
</code></pre>
<h3>3. Reference Issues and Tickets directly</h3>
Link to relevant issues, Jira tickets, or merge requests right in your comment. This gives context and traceability.
<pre><code class="language-typescript">// Some users don&#x27;t have an id... Why? See issue: #756
if (!user.id) { ... }
</code></pre>
That way, when someone’s looking through the code six months later, they will not end up deleting something that is actually needed or asking you why its there.
<h3>4. KEEP IT SIMPLE, STUPID</h3>
Nobody is going to read a novel in a code comment. If you need more than a couple of lines, consider if the information should go elsewhere, such as developer documentation or a linked issue.
<hr>
Write <a href="https://app.daily.dev/posts/being-smart-is-painfull-ojxzh9joy" target="_blank" rel="noopener nofollow">simple code</a> that speaks for itself, comment only to explain the why and don’t litter the code with TODOs nobody will tackle.
Cheers! ✌️

Fabian Letsch

Most code comments are redundant, outdated, or unhelpful. Comments that simply restate what the code does add no value, can become lies when code changes, and create clutter. TODOs often become forgotten technical debt, and commented-out code should be deleted since version control preserves history. Good comments explain the 'why' behind decisions, reference specific issues or bugs, link to tickets for traceability, and remain concise. The best approach is writing self-explanatory code that minimizes the need for comments altogether.

Do Your Comments Help or Hurt?

Fun fact, found some ToDo in my codebase. I agree with immediately creating tickets for things that should be done rather than adding todos - I can tell you for a fact that I have hundreds of them right now waiting to be done 😅
Great post!