<!-- mobian-agent-page publisher="dailydev" canonical="https://daily.dev/posts/clean-code-is-not-the-same-as-clear-code-comments-were-never-the-problem-6lmauekpv" -->

---
title: Clean Code Is Not the Same as Clear Code: Comments Were...
description: An engineering opinion piece argues that the 'clean code means no comments' philosophy is misguided, showing that some code (like dense regex) needs...
canonical: https://daily.dev/posts/clean-code-is-not-the-same-as-clear-code-comments-were-never-the-problem-6lmauekpv
twitter:card: summary_large_image
twitter:site: @dailydotdev
og:type: website
og:site_name: daily.dev
og:title: Clean Code Is Not the Same as Clear Code: Comments Were Never the Problem | daily.dev
og:description: An engineering opinion piece argues that the 'clean code means no comments' philosophy is misguided, showing that some code (like dense regex) needs...
og:url: https://daily.dev/posts/clean-code-is-not-the-same-as-clear-code-comments-were-never-the-problem-6lmauekpv
og:image: https://api.daily.dev/og/posts/6lmauEkPV.png
og:image:alt: Clean Code Is Not the Same as Clear Code: Comments Were Never the Problem
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.

# Clean Code Is Not the Same as Clear Code: Comments Were Never the Problem

**[DEV](https://daily.dev/sources/devto)** · 12 min read · 75 upvotes · 14 comments

## Summary

An engineering opinion piece argues that the 'clean code means no comments' philosophy is misguided, showing that some code (like dense regex) needs translation and some decisions (like a seemingly arbitrary constant of 47 instead of 50) need their reasoning explained because that context can't live in the code itself. It counters the common 'put it in the commit message' rebuttal by pointing out git blame decays, nobody investigates code that looks fine, and people who know the reasoning eventually leave. It also catalogs bad comment patterns (echoes, lying comments, dead code, stale TODOs) and proposes a simple heuristic: write a comment whenever you had to stop and think before writing a line.

## Full article

daily.dev links to this article rather than hosting it. Read it at the original source: <https://dev.to/georgekobaidze/clean-code-is-not-the-same-as-clear-code-comments-were-never-the-problem-42n>

## Questions this post answers

### Should I remove all comments to follow clean code principles?

No, comments should be kept when they do one of four jobs the code itself cannot: translating dense logic like regex or bit tricks, explaining a choice that looks wrong or arbitrary, warning what breaks if changed, or recording a decision with an expiry date. Clean code answers what the code does; comments answer why, which often can't be expressed in syntax alone.

_When weighing comments versus clean code trade-offs, developers compare real engineering opinions on daily.dev._

### Why is relying on git commit history instead of comments a bad idea for explaining code decisions?

Commit history fails as documentation because nobody runs git blame on code that already looks fine, so hidden reasoning never surfaces until something breaks. Blame also decays after reformatting, renaming, or squash merges, burying the original reason under unrelated commits, and the person who knew the answer may have already left the team.

_For debates on documentation strategy versus git history, developers follow these engineering discussions on daily.dev._

## Community discussion

Top comments from developers on daily.dev.

**@engineroom** · 6 upvotes

> I’m all for clean code, but following anything blindly to the letter is stupid.
>
> Just as the article suggests, sometimes even a simple line of code requires explanation. In those cases writing a comment is perfectly fine.

**@guglielmorizzo** · 2 upvotes

> My colleagues need to read it

**@lasepp** · 2 upvotes

> A lesson I learned the hard way:
>
> If a comment about a cache says „don‘t turn it on, it will cross-session polute“, it might not be a good idea to then turn it on.
>
>
> Claude got me there:
>
> Claude: Enabling Cache will make response times faster
>
> Me: But the comment says „don‘t turn it on“
>
> Claude: We can exclude sessions from caching, only static assets will be cached
>
> Me: let‘s do other optimizations first
>
> [one hour later]
>
> Claude: still to do: enable caching
>
> Me: are you sure?
>
> Claude [analyzed 1834 files]: nothing found that can break, everything uses clean sessions
>
>
> <the next day>
>
> All...

**@justbrowsing** · 2 upvotes

> If there is conflict, consider clarity as the priority.
>
> ### My opinion on how to comment
>
> - Be concise.
> - Be relevant.
> - Be unafraid to remove obsolete comments. Being concise allows this. Being verbose does not.
>
> ### My opinion on when to comment
>
> - Comment exceptional behaviour. For example, does this C# property perform a calculation?
> - Comment to make notes. If this method/function performs an expensive calculation, that's all you need to note. If it's later cached:
>   - Performs an expensive calculation.
>   - Caching added.
> - Comment unclear naming that is required by upstream. For...

**@xendk** · 1 upvotes

> Spot on

## Similar posts on daily.dev

- [Most of you calling yourselves “senior developers” are actually just professional litterers](https://daily.dev/posts/most-of-you-calling-yourselves-senior-developers-are-actually-just-professional-litterers-4qqappjr4) · Medium · 0 upvotes · 0 comments
- [Clean Code Is a Guide, Not a Gospel: A Reflection on Pragmatic Software Architecture](https://daily.dev/posts/clean-code-is-a-guide-not-a-gospel-a-reflection-on-pragmatic-software-architecture-jfyonyijq) · ITNEXT · 75 upvotes · 5 comments
- [Maybe Comments SHOULD Explain 'What'](https://daily.dev/posts/maybe-comments-should-explain-what--za90dlcug) · Hacker News · 0 upvotes · 0 comments

---

Tags: [#c#](https://daily.dev/tags/c#)

[View this post on daily.dev](https://daily.dev/posts/clean-code-is-not-the-same-as-clear-code-comments-were-never-the-problem-6lmauekpv)

```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":"TechArticle","headline":"Clean Code Is Not the Same as Clear Code: Comments Were Never the Problem","url":"https://daily.dev/posts/clean-code-is-not-the-same-as-clear-code-comments-were-never-the-problem-6lmauekpv","mainEntityOfPage":{"@type":"WebPage","@id":"https://daily.dev/posts/clean-code-is-not-the-same-as-clear-code-comments-were-never-the-problem-6lmauekpv"},"datePublished":"2026-09-22T10:09:26.865Z","dateModified":"2026-09-22T10:09:48.978Z","description":"An engineering opinion piece argues that the 'clean code means no comments' philosophy is misguided, showing that some code (like dense regex) needs...","image":"https://media.daily.dev/image/upload/f_auto,q_auto/v1/posts/5170bd66ca346e5765e120a8576cd412?_a=AQAEuop","thumbnailUrl":"https://media.daily.dev/image/upload/f_auto,q_auto/v1/posts/5170bd66ca346e5765e120a8576cd412?_a=AQAEuop","isAccessibleForFree":true,"articleSection":"DEV","inLanguage":"en","publisher":{"@type":"Organization","name":"daily.dev","url":"https://daily.dev","logo":{"@type":"ImageObject","url":"https://daily.dev/apple-touch-icon.png","width":180,"height":180}},"author":{"@type":"Organization","name":"DEV","logo":"https://media.daily.dev/image/upload/t_logo,f_auto/v1/logos/devto","url":"https://daily.dev/sources/devto"},"commentCount":14,"discussionUrl":"https://daily.dev/posts/clean-code-is-not-the-same-as-clear-code-comments-were-never-the-problem-6lmauekpv","interactionStatistic":[{"@type":"InteractionCounter","interactionType":{"@type":"LikeAction"},"userInteractionCount":75},{"@type":"InteractionCounter","interactionType":{"@type":"CommentAction"},"userInteractionCount":14}],"keywords":"c#","timeRequired":"PT12M"}
{"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://daily.dev"},{"@type":"ListItem","position":2,"name":"DEV","item":"https://daily.dev/sources/devto"},{"@type":"ListItem","position":3,"name":"Clean Code Is Not the Same as Clear Code: Comments Were Never the Problem"}]}
{"@context":"https://schema.org","@type":"WebPage","@id":"https://daily.dev/posts/clean-code-is-not-the-same-as-clear-code-comments-were-never-the-problem-6lmauekpv","comment":[{"@type":"Comment","text":"I’m all for clean code, but following anything blindly to the letter is stupid.\nJust as the article suggests, sometimes even a simple line of code requires explanation. In those cases writing a comment is perfectly fine.","datePublished":"2026-09-22T17:52:35.637Z","url":"https://daily.dev/posts/6lmauEkPV#c-u7vg0Cwkr","author":{"@type":"Person","name":"Yuri Sokolov","url":"https://daily.dev/engineroom","image":"https://lh3.googleusercontent.com/a/ACg8ocIe2ileTLpMf1aQifRvOfXHrlSztuNHQz7JGaBCDsQ-ng8c1tM=s96-c"},"interactionStatistic":{"@type":"InteractionCounter","interactionType":{"@type":"LikeAction"},"userInteractionCount":6}},{"@type":"Comment","text":"My colleagues need to read it","datePublished":"2026-09-22T15:08:36.288Z","url":"https://daily.dev/posts/6lmauEkPV#c-l68udjQkE","author":{"@type":"Person","name":"Guglielmo Rizzo","url":"https://daily.dev/guglielmorizzo","image":"https://media.daily.dev/image/upload/s--qfk7aLrU--/f_auto/v1779708510/avatars/avatar_Mi3xDhiIYMwwEOmBaEzYQ?_a=BAMAMiWQ0"},"interactionStatistic":{"@type":"InteractionCounter","interactionType":{"@type":"LikeAction"},"userInteractionCount":2}},{"@type":"Comment","text":"A lesson I learned the hard way:\nIf a comment about a cache says „don‘t turn it on, it will cross-session polute“, it might not be a good idea to then turn it on.\nClaude got me there:\nClaude: Enabling Cache will make response times faster\nMe: But the comment says „don‘t turn it on“\nClaude: We can exclude sessions from caching, only static assets will be cached\nMe: let‘s do other optimizations first\n[one hour later]\nClaude: still to do: enable caching\nMe: are you sure?\nClaude [analyzed 1834 files]: nothing found that can break, everything uses clean sessions\n\u0026lt;the next day\u0026gt;\nAll users connect to the same IP address instead of the one they are supposed to, because the cache saw no session (there is none, it uses a header field) and happily returned the IP address that would have been correct for the first user\nSo: comment those cases and trust that the comment made 9 years ago might still warn you of a bad idea","datePublished":"2026-09-23T11:41:54.144Z","url":"https://daily.dev/posts/6lmauEkPV#c-7OBtHjXXX","author":{"@type":"Person","name":"Josef","url":"https://daily.dev/lasepp","image":"https://media.daily.dev/image/upload/s--O0TOmw4y--/f_auto/v1715772965/public/noProfile"},"interactionStatistic":{"@type":"InteractionCounter","interactionType":{"@type":"LikeAction"},"userInteractionCount":2}},{"@type":"Comment","text":"If there is conflict, consider clarity as the priority.\nMy opinion on how to comment\n\nBe concise.\nBe relevant.\nBe unafraid to remove obsolete comments. Being concise allows this. Being verbose does not.\n\nMy opinion on when to comment\n\nComment exceptional behaviour. For example, does this C# property perform a calculation?\nComment to make notes. If this method/function performs an expensive calculation, that’s all you need to note. If it’s later cached:\n\nPerforms an expensive calculation.\nCaching added.\n\n\nComment unclear naming that is required by upstream. For example, does get_id() return a database index, a hash, a string, etc? What does Do() do? What does process() mean?\nTo explain code that cannot be meaningfully simplified. By explain, I mean “Why does this complexity exist, and what does it do?”\n\nMy opinion on when to rename\n\nRename to clarify purpose and identity. Map\u0026lt;K, V\u0026gt; is not a good type name. Is it a hash map, an indexed map, a binary tree map, a trait, or even a generic tile map for a video game?\n\nMy opinion on when not to comment\n\nTo explain code. If the code is unclear, it should be re-written to be clear.\n\nMy opinion on overly-clever lack of comments or variable naming\n\nStop. I know it’s called “code”, but it’s meant to be readable.","datePublished":"2026-09-22T17:56:38.744Z","dateModified":"2026-09-22T18:00:55.092Z","url":"https://daily.dev/posts/6lmauEkPV#c-oLF5EhF1o","author":{"@type":"Person","name":"JustBrowsing","url":"https://daily.dev/justbrowsing","image":"https://media.daily.dev/image/upload/s--O0TOmw4y--/f_auto/v1715772965/public/noProfile"},"interactionStatistic":{"@type":"InteractionCounter","interactionType":{"@type":"LikeAction"},"userInteractionCount":2}},{"@type":"Comment","text":"Spot on","datePublished":"2026-09-22T12:42:41.862Z","url":"https://daily.dev/posts/6lmauEkPV#c-abMjP8503","author":{"@type":"Person","name":"Thomas Fini Hansen","url":"https://daily.dev/xendk"},"interactionStatistic":{"@type":"InteractionCounter","interactionType":{"@type":"LikeAction"},"userInteractionCount":1}}]}
{"@context":"https://schema.org","@type":"FAQPage","@id":"https://daily.dev/posts/clean-code-is-not-the-same-as-clear-code-comments-were-never-the-problem-6lmauekpv#faq","mainEntity":[{"@type":"Question","name":"Should I remove all comments to follow clean code principles?","acceptedAnswer":{"@type":"Answer","text":"No, comments should be kept when they do one of four jobs the code itself cannot: translating dense logic like regex or bit tricks, explaining a choice that looks wrong or arbitrary, warning what breaks if changed, or recording a decision with an expiry date. Clean code answers what the code does; comments answer why, which often can't be expressed in syntax alone. When weighing comments versus clean code trade-offs, developers compare real engineering opinions on daily.dev."}},{"@type":"Question","name":"Why is relying on git commit history instead of comments a bad idea for explaining code decisions?","acceptedAnswer":{"@type":"Answer","text":"Commit history fails as documentation because nobody runs git blame on code that already looks fine, so hidden reasoning never surfaces until something breaks. Blame also decays after reformatting, renaming, or squash merges, burying the original reason under unrelated commits, and the person who knew the answer may have already left the team. For debates on documentation strategy versus git history, developers follow these engineering discussions on daily.dev."}}]}
```

