--- title: Do Your Comments Help or Hurt? | daily.dev description: 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... canonical: https://daily.dev/posts/do-your-comments-help-or-hurt--10p66dkop twitter:card: summary_large_image twitter:site: @dailydotdev og:type: website og:site_name: daily.dev og:title: Do Your Comments Help or Hurt? | daily.dev og:description: 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... og:url: https://daily.dev/posts/do-your-comments-help-or-hurt--10p66dkop og:image: https://api.daily.dev/og/posts/10p66dKoP.png og:image:alt: Do Your Comments Help or Hurt? og:image:width: 1200 og:image:height: 630 og:locale: en --- > ## Documentation Index > Fetch the complete documentation index at: https://daily.dev/llms.txt > Use this file to discover all available pages before exploring further. # Do Your Comments Help or Hurt? **[Fabian Letsch](https://daily.dev/sources/v7balm8y0o32yjz1hhf5a)** · [@fabianletsch](https://daily.dev/fabianletsch) · 3 min read · 4 upvotes · 1 comments ## Summary 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. ## Content 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:  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! ### 1. Lies, damned lies and Comments 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. ### 2. TODO or NOT TODO, that is the question 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? `// TODO: Refactor this.` 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... ### 3. Comments Are Not a Code Graveyard 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? ___ ## Practical Tips for Writing Good Comments ### 1. Do not write the comment in the first place 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. ### 2. Explain the *Why*, Not the *What* 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:** ```typescript // Wrapper div is needed ``` **Do this instead:** ```typescript // Wrapper div is required for Firefox, see: https://bugzilla... ``` ### 3. Reference Issues and Tickets directly Link to relevant issues, Jira tickets, or merge requests right in your comment. This gives context *and* traceability. ```typescript // Some users don't have an id... Why? See issue: #756 if (!user.id) { ... } ``` 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. ### 4. KEEP IT SIMPLE, STUPID 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. ___ Write [simple code](https://app.daily.dev/posts/being-smart-is-painfull-ojxzh9joy) that speaks for itself, comment only to explain the *why* and don’t litter the code with TODOs nobody will tackle. Cheers! ✌️ ## Community discussion Top comments from developers on daily.dev. **@victorofoegbu** · 1 upvotes > 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! --- Tags: [#code-review](https://daily.dev/tags/code-review) [View this post on daily.dev](https://daily.dev/posts/do-your-comments-help-or-hurt--10p66dkop) ```json {"@context":"https://schema.org","@graph":[{"@type":"Organization","@id":"https://daily.dev/#organization","name":"daily.dev","url":"https://daily.dev","logo":{"@type":"ImageObject","url":"https://daily.dev/apple-touch-icon.png","width":180,"height":180},"sameAs":["https://twitter.com/dailydotdev","https://github.com/dailydotdev","https://www.linkedin.com/company/daily-dev-ltd"]},{"@type":"WebSite","@id":"https://daily.dev/#website","url":"https://daily.dev","name":"daily.dev","publisher":{"@id":"https://daily.dev/#organization"},"potentialAction":{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https://daily.dev/search?q={search_term_string}"},"query-input":"required name=search_term_string"}}]} {"@context":"https://schema.org","@type":"DiscussionForumPosting","mainEntityOfPage":"https://daily.dev/posts/do-your-comments-help-or-hurt--10p66dkop","headline":"Do Your Comments Help or Hurt?","text":"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.","url":"https://daily.dev/posts/do-your-comments-help-or-hurt--10p66dkop","datePublished":"2025-10-01T22:56:32.969Z","dateModified":"2025-10-11T22:32:31.751Z","author":{"@type":"Person","name":"Fabian Letsch","url":"https://daily.dev/fabianletsch","image":"https://lh3.googleusercontent.com/a/ACg8ocKR6BVy_wn23EoOKq7-BlszlcXcLmASlnb7l-GtS-q1bePnkaJf=s96-c","description":"Hey, i'm Fabian and I deeply care about helping devs ship more code with less bugs in less time! 🔥","interactionStatistic":{"@type":"InteractionCounter","interactionType":{"@type":"EndorseAction"},"userInteractionCount":50270}},"image":"https://media.daily.dev/image/upload/s--XANbX56A--/f_auto/v1759359445/posts/10p66dKoP?_a=BAMAK+ZW0","interactionStatistic":[{"@type":"InteractionCounter","interactionType":{"@type":"LikeAction"},"userInteractionCount":4},{"@type":"InteractionCounter","interactionType":{"@type":"CommentAction"},"userInteractionCount":1}],"comment":[{"@type":"Comment","text":"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 😅\nGreat post!","datePublished":"2025-10-02T14:00:02.661Z","url":"https://daily.dev/posts/10p66dKoP#c-en65PQ5T7","author":{"@type":"Person","name":"Victor Ofoegbu","url":"https://daily.dev/victorofoegbu","image":"https://lh3.googleusercontent.com/a/ACg8ocJHSQ0T8YX1JG5y9ejPQo2K76FT6_QUrYjw_0s6HGjBj2NXQZY5Kg=s96-c"},"interactionStatistic":{"@type":"InteractionCounter","interactionType":{"@type":"LikeAction"},"userInteractionCount":1}}],"isPartOf":{"@type":"WebPage","url":"https://daily.dev/sources/v7balm8y0o32yjz1hhf5a","name":"Fabian Letsch"}} {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://daily.dev"},{"@type":"ListItem","position":2,"name":"Fabian Letsch","item":"https://daily.dev/sources/v7balm8y0o32yjz1hhf5a"},{"@type":"ListItem","position":3,"name":"Do Your Comments Help or Hurt?"}]} ```