DEV Community

Cover image for Clean Code Is Not the Same as Clear Code: Comments Were Never the Problem

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

Giorgi Kobaidze on September 21, 2026

Table of Contents A Line That Does Nothing... Except Keep Production Alive Some Code Can't Explain Itself The Code Knows What. Only You...
Collapse
 
unitbuilds profile image
UnitBuilds •

"^([A-Z]{2}|[A-Z]\d|\d[A-Z])(\d{1,4})([A-Z]?)$"

Breakdown for people who wanna learn regex

[A-Z]{2}| - 2 letters
[A-Z]\d| - letter and a digit
\d[A-Z] - digit and a letter
() - represents a group.
([A-Z]{2}|[A-Z]\d|\d[A-Z]) - Group 1
(\d{1,4}) - Group 2 - 1-4 digits
([A-Z]?) - Group 3 - ? means optional, so an optional letter

So First 2 digits are either 2 letters, a letter and a digit, or a digit and a letter.

2nd set is either 1,2,3,4 digits

3rd set is optionally a letter.

"BA123" - 2 letters, 3 digits - so it passes
U21234" - letter digit, followed by 4 digits - so it passes
FlightNumbers.IsValid("9W5A"); - digit letter, 1 digit, letter - so it passes
FlightNumbers.IsValid("99123"); - No letter in first 2, so it fails the first group of the regex.

And now you understand Regex 😁

Collapse
 
georgekobaidze profile image
Giorgi Kobaidze •

"And now you understand Regex" - I'm sure nobody in history has ever said that yet 😄

Collapse
 
unitbuilds profile image
UnitBuilds •

😂 99% of the time, these are all you really need. It's that last 1% where wildcards come in and anchors, which is usually where people mess up

Thread Thread
 
georgekobaidze profile image
Giorgi Kobaidze • • Edited

I remember when LLMs first showed up, one of my first reactions were: "alright, so now I know who writes/reads regex now! (Not me)" 😄

Collapse
 
natia_bekauri_08aeeec9279 profile image
Natia Bekauri •

Rules are always nice to me they give structure and cleanness but practice showed me another thing especially when you work with entitled people- sometimes you need to have comments so others don't suddenly change code (especially without retesting 😂) and the most important - yes, comments should not explain obvious tech nical detsils that's a job of a cleanly written literate code itself, but sometimes business rule can be out of logic and hard to see in shadows so that's where comments help and as always - balance is the key. Thank you for sharing this!

Collapse
 
johnnylemonny profile image
𝗝𝗼𝗵𝗻 •

Absolutely. I've seen that happen more than once in real projects. 😄 Comments become especially valuable when they're documenting business rules, historical decisions, or constraints that aren't obvious from the code itself. A developer can often understand what the code does just by reading it, but not necessarily why it has to work that way. And as you mentioned, a well-placed comment can sometimes prevent someone from making a "harmless" change without realizing the wider impact. Balance is definitely the key: clean code where possible, meaningful comments where necessary. Thanks for sharing your experience!

Collapse
 
georgekobaidze profile image
Giorgi Kobaidze •

I've seen developers "correcting" logic and making a huge mess in production.

Collapse
 
georgekobaidze profile image
Giorgi Kobaidze •

Exactly. And you’re right about rules. They’re good to have as a reference point, but if software engineering was just a strict set of rules, it’d be way too easy and simple.

It’s neither easy, nor simple.

Collapse
 
anthony-gicheru profile image
Anthony Gicheru •

Really liked this. I think comments get a bad reputation, but sometimes the code can tell you what’s happening without telling you why. That’s where a good comment really helps.

Collapse
 
georgekobaidze profile image
Giorgi Kobaidze •

Totally true. I even remember when I was junior engineer and had to learn the codebase. Some of the comments there saved me probably days of wondering what was it doing.

A good comment can sometimes be more valuable than good code.

Collapse
 
mariobermonti profile image
Mario E. Bermonti Pérez •

Loved the humor. I laughed aloud when I saw the actual burger in the box. 🤣

Collapse
 
georgekobaidze profile image
Giorgi Kobaidze •

Thanks! 😄 I just write whatever comes to mind, and sometimes it makes my articles way better than when I try to be too serious.

Collapse
 
ingosteinke profile image
Ingo Steinke, web developer •

Don't ever change the sharp-bend road sign image! It's such a funny example of how AI is solving our problems.

Sharp bend ahead road sign turning to the left while the actual road turns to the right

Collapse
 
georgekobaidze profile image
Giorgi Kobaidze •

I know, this is really good haha.

Collapse
 
pengeszikra profile image
Peter Vivo •

A hardest maintain comment is the README.md a good one is short cllear as your program, clear indicate something wrong if you feel creepy when read it.

My favorite comment format is the single line jsDoc - even working better than TS and compatible! I wrote a few blogpost of jsDoc. Even a jsDoc based react typesafe state handling npm library ( jsdoc-duck ) - best advice if borrowing instead of import. 64LOC long, a large part is comment.

Collapse
 
georgekobaidze profile image
Giorgi Kobaidze •

Good point. A README file is basically one large comment.😄

Collapse
 
ale3oula profile image
Alexandra •

My rule: if there is a regex, there should always be a comment.

Whenever the business logic is not obvious there should be an explanation. I think this paranoia of not adding comments started with books like Clean Code, or better with people that took them too literally.

Collapse
 
georgekobaidze profile image
Giorgi Kobaidze •

OMG this is so true. Looks like sometimes people just take everything too literally. We need more common sense.

Collapse
 
ale3oula profile image
Alexandra •

Common sense is rare the last couple years xD

Thread Thread
 
georgekobaidze profile image
Giorgi Kobaidze •

That sounds so painful and so true

Collapse
 
sinarezaei profile image
Sina Rezaei •

I think the “code tells you what, comments tell you why” distinction is the important part here. A comment that repeats retryCount++ is noise, but a comment explaining why a limit is 47 instead of the documented 50 can save someone from “fixing” something that was already intentional. I also agree that Git history isn't always a replacement for that. If I'm reading a piece of code today, I shouldn't have to reconstruct five years of commits just to understand why an odd-looking value or workaround exists.

The part I'd be careful with is the maintenance argument. Comments can become wrong just like documentation and tests can, so I wouldn't treat comments as automatically valuable. The useful ones are the comments that capture information the code itself can't express, especially constraints, business rules, or reasons behind unusual decisions.

For me, that's the real difference between clean code and clear code. Clean code reduces the effort needed to understand the implementation. Good comments can reduce the effort needed to understand the context behind it.

Collapse
 
georgekobaidze profile image
Giorgi Kobaidze •

Great insights. That said, I've seen codebases where following 'clean code' dogmatically made things harder to work with, not easier.

Collapse
 
naveen_alavilli profile image
Naveen Alavilli •

"Clean code reduces effort to understand the implementation, good comments reduce effort to understand the context" is a clean enough line I'm stealing it. I'd add one case where the context has to survive outside the codebase entirely: regulated environments where the person who needs the "why" is an auditor or a compliance reviewer with no repo access at all. The 47-vs-50 example is exactly the kind of thing that gets "fixed" during a remediation pass by someone confident and wrong — in that setting the comment isn't just for the next engineer, it's the only artifact standing between a fix and an outage.

Thread Thread
 
georgekobaidze profile image
Giorgi Kobaidze •

Yes absolutely. But I’ll add one thing: when it comes to strict regulations, comments shouldn’t be the primary source of truth. There should be an official documentation where everything is explained in details.

Thread Thread
 
sinarezaei profile image
Sina Rezaei •

I think all three points can be correct at the same time. They are not competing solutions; they are different layers of the same system.

Take the 47 vs 50 example.

If I'm reading the code and see limit = 47, a comment can immediately tell me why it is 47 instead of the expected 50.

If I need to understand the full business rule or requirement behind that number, I should go to the official documentation.

And if this is a regulated environment, the official documentation should be the authoritative source, while the comment can still connect that requirement to the actual implementation.

So I don't see this as “comments or documentation.” They are three paths around the same problem.

The challenge determines which layer I need: quick local context, detailed system context, or authoritative documentation.

That's where I think parallel thinking matters. The answers don't have to eliminate each other. You choose the right layer based on the problem you're solving.

Thread Thread
 
georgekobaidze profile image
Giorgi Kobaidze •

Exactly! Documentation and code comments have completely different purposes. Sometimes you just need to have one of them, but having both can be beneficial in plenty of situations as well.

Collapse
 
sameerqaisar17 profile image
Sameer Qaiser •

The line that hit me: "Clean code tells the reader what you did. A good comment tells them what you knew."

I'm a beginner — I started learning Python about two weeks ago and I've been writing beginner tutorials on Dev.to. And reading this, I realized I've been writing comments for a reason I couldn't name until now.

When I write a tutorial, I have to add comments to my code. Not because the code needs explaining to me — I wrote it. But because I know exactly where a beginner is going to get stuck. I know because I was stuck there two weeks ago.

"Line 1 creates a list. Line 3 loops through it." That's an echo comment. Useless. But:

# range(1, 6) gives you 1, 2, 3, 4, 5 — it stops before the second number.
Enter fullscreen mode Exit fullscreen mode

That one exists because I spent 20 minutes confused about it on day one.

That's the difference. The first comment describes the code. The second one records the scar.

I haven't written code for production yet. I don't have a MaxConcurrentRequests = 47 story. But I think the instinct is the same: if I had to stop and think, the next person will too. That's the comment worth writing.

Great post.

Collapse
 
georgekobaidze profile image
Giorgi Kobaidze •

Interesting points, thanks for sharing.

I like your approach as a beginner. Keep it that way.

But be careful not to add too many comments when not necessary, that also a trap.

Collapse
 
nour_dude_314 profile image
nourdude •

on the

# TODO: remove workaround and implement 
Enter fullscreen mode Exit fullscreen mode

thing....
it's okay in a solo project where you're a bit tired and will honestly come back later. but not in an actual commit to an actual work repo

Collapse
 
georgekobaidze profile image
Giorgi Kobaidze •

Sure, ideally this shouldn't be done. But sometimes you have to improvise and deviate a little to deliver something faster.

Collapse
 
kielltampubolon profile image
Kiell Tampubolon •

The split that matters in my corner of the world is comments that record what a check deliberately does not match. In detection code, that line is the difference between a false negative you can fix in minutes and one you rediscover from scratch, and no amount of clean naming carries that information. Your four jobs map onto it: translates and explains rot, but the does-not-match comment only rots when someone changes the rule, and the test suite should catch exactly that. Do you treat those as comments, or promote them to assertion messages so they fail loudly instead of sitting quiet?

Collapse
 
georgekobaidze profile image
Giorgi Kobaidze •

I don't think I fully understand the question, and to be honest, I'm not sure how a test suite could catch that.

I think the correctness of comments relies entirely on the developer, or maybe on AI. By the way, AI models are pretty good at writing comments.

Collapse
 
kielltampubolon profile image
Kiell Tampubolon •

Fair, I phrased that too compactly.

I don't mean the test suite should verify that the comment is correct as text. I mean the thing the comment is preserving should often be expressible as a failing case.

For example, in detection code, a comment might say: "Do not match this pattern because it also appears in benign Terraform output." That can stay as a comment, but the stronger version is a fixture/assertion where that benign Terraform output is tested and expected not to match. Then if someone later broadens the regex, the test fails instead of the comment silently becoming outdated.

So my distinction is: some comments only explain reasoning, and those depend on maintainers. But some comments describe an exclusion, invariant, or known edge case. Those can often be promoted into tests or assertion messages, with the comment explaining why the test exists.

That was the angle I was trying to ask about.

Thread Thread
 
georgekobaidze profile image
Giorgi Kobaidze •

Oh, now I understand. Thanks for the detailed perspective. Good points!

Collapse
 
nigel_amers_a1374d1a583f2 profile image
Nigel Amers • • Edited

Your examples look good but miss even more fundamental engineering that unfortunately most c# code falls into the trap of repeating. Your const is valid except for the fact that if it can conceivably change then it isn't a const is it. Moving into an env var might be a better option, then the name is fine, if there are bursts happening then the consuming code is deficient thus the comment papers over that and leaves buggy code alone. The regex is in a partial, and that smells like generated code to me, so you might want to be careful because it might be lost if regeneration happens. However, the main point of code is that it should be human readable, since the computer/compiler doesn't care, the code is an artefact for the human and unfortunately a lot of the frameworks in c# (not all) are mostly junk. Regex also is self explanatory just not that easy for humans to parse hence why a comment on the regex might be ok if you cannot rewrite to reveal the intent following the 4 rules of simple design. I really do like the point of not want to break the cognition by forcing a reader to jump away from the code, the issue you have with comments is not so much that the comment has to be updated with the code changes, it is that humans don't understand the code and for whatever reason may not even change the comment and that is worse because it will then be telling falsehoods to every future reader from then on. The regex being difficult to parse and the comment claim is different from reality, more dangerous than having a comment. I like the comment about dogma though not a fan at all of dogmatism, if something looks less elegant than 'clean' code but reveals intent, then that is actually clean code and the elegance is aesthetics that misses the point of what code is for... the human.

Collapse
 
nigel_amers_a1374d1a583f2 profile image
Nigel Amers •

Actually want to add that the article is good and my points are not to pick apart the article to trash it, but to make a point that there is nuance and to ensure that the thinking goes into some not so obvious choices engineers have to make while engineering a system. This is not supposed to be a criticism of the author and if it looked like it was then I apologise for that. I want to make sure people realise that deeper thinking is sometimes required, because the authors points are valid but not in all situations, just as my points are valid but also not in all situations. So kudos to the author!

Collapse
 
georgekobaidze profile image
Giorgi Kobaidze •

Thanks for such a thoughtful comment. There's a lot here I agree with, especially the last part. If less "elegant" code reveals intent better, then it is the clean code. That's pretty much the thesis of the series, and you put it better than I did.

You're also right that a lying comment is worse than no comment. A stale comment actively misleads every future reader. I'd just add that names can lie in exactly the same way (we've all met a GetUser() that also writes to the database). I've also seen get requests that would delete an entity as a side effect. So I see it as a maintenance discipline problem for anything humans read, not a reason to avoid comments.

A couple of places where I'd push back a little:

On the constant: an env var makes sense if the value genuinely varies by environment. I've actually though about that argument, but in the example, 47 isn't a tuning knob. It comes from an upstream constraint, the burst window. Moving it to config changes where the number lives, not why it's 47, so the explanation still has to go somewhere. And sometimes the "deficient" code is a third-party API you can't fix, so the comment is recording a constraint you have to live with rather than covering for a bug.

On the partial: [GeneratedRegex] flips the old designer-file model. I write the declaration, and the source generator emits the implementation into a separate file at build time. My file is never regenerated, so the comment is safe. I get the instinct, though. Years of Form1.Designer.cs taught all of us to be suspicious of partial.

Really appreciate you taking the time. This is exactly the kind of discussion I was hoping the post would start.

Thread Thread
 
nigel_amers_a1374d1a583f2 profile image
Nigel Amers •

Thanks, and apologies, clean code is like a red rag to me :-) your title is very correct because "clean" code is wrong used as a shield to not use the code base to communicate. I take your push backs too 👍️ thank you for starting this discussion and sharing your own insights.

Thread Thread
 
georgekobaidze profile image
Giorgi Kobaidze •

I feel the same way about clean code. When I was a junior/mid-level developer, I used to think that was the only way to go, but as I gained more experience, I realized software engineering isn't as simple as just following strict rules.😄

Collapse
 
maame-codes profile image
Maame Afua A. P. Fordjour •

Loved this. Clean code shows what the code does, but a comment is the only place that explains why. Totally agree we need both.

Collapse
 
georgekobaidze profile image
Giorgi Kobaidze •

Absolutely. Just like we need README, design docs, API references, commit messages, you name it.

Everything has its purpose. It’s up to us if we use them for it.

Collapse
 
dannwaneri profile image
Daniel Nwaneri •

Giorgi, the 47 example makes the case on its own. I have the same pattern in RAG work, a chunk size or a similarity threshold that looks arbitrary until you know the one edge case that broke at the round number.

Clean code shows the current value. Only a comment shows why that value and not the obvious one. I follow that same rule now, write down what made me stop and think.

Collapse
 
georgekobaidze profile image
Giorgi Kobaidze •

I'm glad it resonated with you. You clearly understood the intent of this example.

Collapse
 
sizzlebop profile image
Jessica Doering •

I’m definitely on the side of comments being useful, as long as they’re actually useful comments. I don’t want every other line explaining something the code already makes obvious, but a well-placed comment can save a ton of time.

Even beyond explaining why something was done a certain way, I find comments really helpful just for navigating a codebase. If I’m jumping into a larger file looking for a particular piece of logic, a few good comments make it so much easier to scan and find what I need without having to read every function along the way.

I think the problem was never really comments themselves. It’s comments that add noise instead of context.

Collapse
 
georgekobaidze profile image
Giorgi Kobaidze •

Comments, just like anything else in software engineering, can be used in many different ways. It's all about how we use them. Almost nothing is inherently wrong.

Totally agree with your points!

Collapse
 
leonore_fcf3095de32ca8433 profile image
Leonore •

This article makes a strong point about the difference between explaining what code does and documenting why it exists. I especially liked the examples around the 47 request limit and the regex, because those are exactly the kinds of details that can look arbitrary months later. I’ve been reading more software engineering discussions and practical coding content on Codecan.net as well, and this is a topic that deserves more attention—good comments can save a lot of debugging and reverse-engineering time.

Collapse
 
georgekobaidze profile image
Giorgi Kobaidze •

Thanks for the feedback!

Collapse
 
thesnehamk profile image
Sneha M K •

The MaxConcurrentRequests = 47 example is the one that'll stick with me: it's the perfect case for your point because the code is already about as clean as it can be (a well-named constant, a sensible type), and it's still actively misleading without the comment. Someone doing a well-intentioned cleanup pass would "fix" it to 50 and ship an outage. No amount of refactoring the surrounding code closes that gap, because the missing information isn't in the code's structure; it's in a support ticket or a Slack thread from six months ago that git blame won't reliably surface either.

One thing I'd add to your four categories, especially with AI coding assistants now reading and editing code directly: that "record" function of comments matters even more when the next reader might not be a human who can ask a teammate why 47 is 47; it's an agent that only sees the file in front of it, with no access to the tribal knowledge that produced that number. A comment explaining the "why" isn't just documentation for the next developer anymore; it's the only guardrail standing between a plausible-looking refactor and a repeat of the exact outage the original comment was written to prevent.

Collapse
 
georgekobaidze profile image
Giorgi Kobaidze •

Love that additional detail about non-human readers. Informative comments can be helpful for the AI as well. Thanks for the great feedback!

Collapse
 
build996 profile image
build996 •

The four jobs split on an axis worth naming: Translates only rots when the code under it changes, and a diff puts that in front of a reviewer. Explains, when it encodes something measured about somebody else's system, rots while your repo sits completely still - no diff, no review, nothing that fires. So "update the comment when you update the code" fully covers the first kind and is structurally incapable of covering the second. Do you treat those as one maintenance problem, or does the 47 kind get something the regex kind doesn't?

Collapse
 
georgekobaidze profile image
Giorgi Kobaidze •

Great question. I'd approach it the same way: if that 47 becomes 51, there's almost certainly a reason behind the change, and the developer should make that reason explicit.

Collapse
 
porto2112 profile image
Porto •

Great topic and text. I once worked in a project where the lead engineers had a strict "no comment policy". It made me nuts, because the code was a big mess and the team had a high fluctuation, changing engineers almost every two weeks. Not that comments alone would've been able to solve all the issues with the project, but I do believe they would've helped in some aspects.
Bottom line for me is that it's a good thing to have guidelines and rely on clean code, but blindly following them without questioning may make life unnecessary hard for all people in a project.

Collapse
 
georgekobaidze profile image
Giorgi Kobaidze •

“No comment policy” - what a major major red flag!🚩

Collapse
 
mikachu profile image
Mika Flowers •

You did it again! This is such a clear way to reframe the whole "clean code vs. comments" debate, and I think you nailed the actual distinction people keep missing.

The 47-vs-50 example is going to stick with me though lol.
I also appreciated that you didn't let this turn into a "comment everything" pitch. The rule you landed on, if you paused to think, write down what you thought — feels like the kind of thing that's actually usable day to day, not just a nice-sounding principle.

Thanks for writing this up, really enjoyed it.

Collapse
 
georgekobaidze profile image
Giorgi Kobaidze •

Thank you! I'd been putting this article off for too long and finally had to write it. Glad you feel the same way about comments.🙏

Collapse
 
jess_stone_947212fc438515 profile image
Jess stone •

Something I keep running into on React codebases that fits this exactly: the code often IS clear at the line level, but the decisions that shaped it aren't. Why did we memoize this? Why did we hoist state up to this layer? Why does this component take 11 props instead of composing children?

I've started leaving what I call "why not what" comments. Not // maps items to list elements (obvious from the code), but // we mount this above the modal because Portal + Suspense boundaries stack in this order — see PR #843 for the incident this fixed. It's the second one that saves you six months later when you're wondering why the ordering matters.

The "code should be self-documenting" crowd usually means "variable names should be self-documenting." Those are different claims.

Collapse
 
georgekobaidze profile image
Giorgi Kobaidze •

Excellent points. In most cases we should leave the “what” part to the code itself, but sometimes, no matter how intuitive and clean you code is, there are still going to be questions that require 2-3 hours of staring at the code to answer.

So yes, I definitely don’t mind comments that explain a little bit of the “what” alongside the “why”.

Collapse
 
marsomelody profile image
Keerthi •

I agree with this. Good comments shouldn't explain obvious code; they should explain the reasoning behind unusual decisions, workarounds, or complex logic. Code tells us what is happening, while a useful comment can tell us why. That context can save a lot of time for the next developer who works on the code.

Collapse
 
georgekobaidze profile image
Giorgi Kobaidze •

That’s absolutely the point. Thanks for the feedback!

Collapse
 
to21as profile image
Tobias •

The why-comments that survive in my repos are the ones naming something outside the file: the upstream issue, the spec clause, the vendor doc. Anything I cannot link tends to rot into a lie within a year.

So the rule I landed on is that a workaround comment has to carry the condition that ends it. Not "temporary, remove later" but "remove once ships". That also makes it falsifiable, because the next person can open the link and see the bug is closed.

Does that work for the flight-number case, or is the regex one where the why has no external source to point at?

Collapse
 
georgekobaidze profile image
Giorgi Kobaidze •

I see your point. But I've also seen plenty of codebases with outdated documentation, README files, API descriptions, and whatnot. They rot over time too if nobody keeps them up to date.

So I don't think comments are the issue here. The issue is whoever maintains them.

Collapse
 
glenallen profile image
Glen Allen •

The “current state vs historical reasoning” distinction has an interesting implication for AI-assisted development too. An agent can read clean code and understand what it does, but without the reasoning behind unusual constraints, it may confidently “improve” something that was intentionally designed that way. That makes certain comments more than documentation—they become guardrails against incorrect refactoring. I’d argue the most valuable comments for both humans and coding agents are the ones that explain a constraint, its origin, or the consequence of changing it. In that sense, a good comment isn't competing with clean code; it preserves information that neither the syntax nor a refactor can reliably reconstruct later.

Collapse
 
georgekobaidze profile image
Giorgi Kobaidze •

Totally true! We write instructions for AI in .md files, why not write even more specific information in comments when necessary?

Good points!

Collapse
 
nikhil_patel_10 profile image
Nikhil Patel •

This is a great point. Code can be perfectly “clean” and still leave the next developer wondering why a particular decision was made. I think the best comments preserve context and intent, rather than explaining something the code already makes obvious.

Collapse
 
georgekobaidze profile image
Giorgi Kobaidze •

Yes, we don’t want to duplicate what’s already right there.

Collapse
 
nikhil_patel_10 profile image
Nikhil Patel •

Exactly. If the code already explains the “what,” the comment should add the “why.” That’s where comments become genuinely useful.

Collapse
 
suraj09 profile image
Suraj Suradkar •

This is especially interesting for AI-assisted development.

An agent can understand what the code does, but the “why” behind an unusual constraint can be easy to lose — especially when the original decision happened months ago.

I think those moments where someone stopped and thought “hmm, why is this like this?” are often the most valuable context to preserve.

Collapse
 
georgekobaidze profile image
Giorgi Kobaidze •

That’s right. By the way, AI itself adds comments on top the code it generates.

Collapse
 
johnnylemonny profile image
𝗝𝗼𝗵𝗻 •

I completely agree with the main point. Too often "clean code" gets interpreted as "remove all comments," when the real goal should be improving understanding. Well-named functions and variables can explain what the code does, but comments are still invaluable for explaining why a particular decision was made, documenting trade-offs, or preserving important business context. Clear code isn't comment-free code, it's code that helps the next developer understand the intent as quickly as possible. Great perspective and a refreshing take on a topic that's often oversimplified. 👍

Collapse
 
georgekobaidze profile image
Giorgi Kobaidze •

Totally agree!

Collapse
 
prasad-dev profile image
Prasad V •

One thing you missed in "what worst can happen" is:

Write comment-then code: After awhile some one makes a change (add new code) and the comment gets burried somewhere and loose the relevance.

Comments have its place (like your regex example OR cases like we choose random number and that is allowed to change as we evolve etc.,) , but don't need to be everywhere in the code is what we should aim for in my opinion.

As we add more comments and they stay in code but loose relevance as new code added/deleted is more pain to deal with.

Collapse
 
georgekobaidze profile image
Giorgi Kobaidze •

Definitely, comments aren't supposed to be everywhere, that's absolutely one of the worst things a developer can do.

Collapse
 
botsailorofficial profile image
BotSailor •

Really enjoyed this perspective. There’s often a misconception that “clean code” means removing every comment, but the real goal should be making code easier for humans to understand and maintain. Good comments are not there to explain obvious syntax, they preserve the context, decisions, and lessons that the code alone cannot communicate. Writing code for the next developer who reads it is just as important as writing code that works today. Great discussion!

Collapse
 
georgekobaidze profile image
Giorgi Kobaidze •

Thank you for the great feedback!

Collapse
 
verhasi profile image
Istvan Verhas •

Even if I agree with the statement of the industry that the code is the documentation it is still too general. The question is who need the "documentation" and answering this question we will split readers from the class^method point of view

  • maintainer: Me or another developer who maintains the code
  • client: who want to use the class/method

Before we start to write a comment or instead a javadoc/XML Doc ew must decide who is th target reader. Lets see one by one. The maintainer must know to read the regex whats more write the regex and the example comment will not teach him that. The client only want to decide whether he needs this class/method or not and does not want to read the source code and does not interested in the implementation details. He only needs a perfect API documentation. He does not care it is implemented with regex or not at all.
So even a clean code must have javadoc/XML Doc to tell the client how to use. The how to use is the reason why it is implemented that way.
It would be very funny if I got into a car without any prior knowledge of what the gas pedal does, and instead had to trace the Bowden cable all the way to where it pulls the carburetor lever, thereby altering the air-fuel mixture ratio.
Another area where the documentation is a must have the interfaces as there is no code at all. Where from would you know what should the implementation do? Only from the method and parameters names? Sometimes also need a hint to the implementor in details that can not be required in the given software development language.
On the other hand the elements not part of the api should not require more documentation than itself just as an exception.

Collapse
 
georgekobaidze profile image
Giorgi Kobaidze •

This is a great point. Thanks for sharing!

Collapse
 
blobdole profile image
Doug • • Edited

"When I imagine another person reading through this code, which parts do I think they will understand and which parts would it be helpful to give them some additional information?"

It is frustrating that no matter how many rules and schemas you can make, they fail to fully solve these incredibly human problems rooted in needing to empathize and communicate with others. Some day maybe, but until then we are going to have to keep trying to predict the internal worlds of others.

Collapse
 
georgekobaidze profile image
Giorgi Kobaidze •

That's why I always encourage the developers I work with to be explicit as much as possible. Sometimes things seem obvious, but from another perspective, they're not even remotely close to being clear.

Collapse
 
james_koppel_3aa6e45753b4 profile image
James Koppel •

Next to "Recheck if they publish new limits," I would suggest putting the date

E.g.: "// NOTE 2026.09.23: Recheck if they publish new limits"

If you see that comment, it would make a big difference if the date is 1 year old or 1 week old.

And yes, theoretically that information's in the git blame, but....theoretically.

Collapse
 
georgekobaidze profile image
Giorgi Kobaidze •

This is actually a brilliant idea! 💡
Specifying the date also tells you how much you can trust that comment. If it's too outdated, it's better to take it with a grain of salt.

Collapse
 
sharpartzgh profile image
Frederick •

I absolutely agree with you on this, the humor alone 😅

Collapse
 
georgekobaidze profile image
Giorgi Kobaidze •

Thank you. Yeah I needed to mix in some humor, because usually when people discuss this topic, it gets pretty heated. 😄

I need to change that trend.😄

Collapse
 
sharpartzgh profile image
Frederick •

This article needs to reach millions damn😄😄... had to read it again and it feels better again hahahah

Thread Thread
 
georgekobaidze profile image
Giorgi Kobaidze •

Absolutely love that, thank you!😄

Collapse
 
jessy_fullbuster_258890c8 profile image
jessy fullbuster • • Edited

yo pongo los comentarios para saber donde esta cada cosa de un vistazo 🗿 odio estar buscando las cosas y me pierdo entre el mar de letras y letras jajjj llámenme novata, pero no me importa, si quiero cambiar cierta cosa, ¡Zas! ahí esta sin estar intentando recordar para que serbia ese código, hay que mantener la casa bien ordenada XD

Collapse
 
georgekobaidze profile image
Giorgi Kobaidze •

That's what separates senior engineers from juniors. Seniors aren't bound by rules for their own sake, they make the work easier by using whatever tools and approaches fit the problem.

Collapse
 
naveen_alavilli profile image
Naveen Alavilli •

The flight number regex is the perfect example, and I'd push it a step further. That pattern encodes a rule that lives outside your codebase, in a standard someone else maintains. So the comment you actually need isn't only "what does this match," it's "who decided this, and when."

Most of my career has been in public sector systems where that is the whole job. A validation rule isn't arbitrary, it's a statute or a program policy, and the useful comment is a citation. Not "check eligibility" but "eligibility per [rule], revised 2019." Because the failure mode there isn't a future developer misreading the code. It's the rule changing while the code still looks correct and every test still passes, because the tests encode the old rule too.

That's the case "just write clearer code" can't touch. No naming scheme tells you that the thing your function implements faithfully was superseded two years ago. Only a pointer to the authority does, because it gives the next person somewhere to go check.

Clean code tells you what it does. Tests tell you what it did when you wrote them. A citation is the only one that tells you whether it should still be doing it.

Collapse
 
georgekobaidze profile image
Giorgi Kobaidze •

Great insights, thanks!

Collapse
 
lucasdemond profile image
Lucas •

Here at The Printing World, we deal with weird custom packaging specs all the time. Good documentation saves us when a rush job comes in and nobody knows why a specific die-cut setting was used!

Collapse
 
georgekobaidze profile image
Giorgi Kobaidze •

Good documentation is always something that must be done. But I've seen so many companies neglecting that part, it's surprising.

Collapse
 
kushyarr7 profile image
Kushyar Rashidzadeh •

I really liked this post. The explanation is awesome.

Collapse
 
georgekobaidze profile image
Giorgi Kobaidze •

Thanks a lot! Tried my absolute best. 🙏

Collapse
 
ubaid_jan_d8877a83d5a9d81 profile image
Ubaid Jan •

Very nice

Collapse
 
georgekobaidze profile image
Giorgi Kobaidze •

Thank you!

Collapse
 
technogamerz profile image
𝐓𝐡𝐞 𝐋𝐚𝐳𝐲 𝐆𝐢𝐫𝐥 •

Wow Really Really nice write-up!

Collapse
 
georgekobaidze profile image
Giorgi Kobaidze •

Appreciate that! 🙏 I had something different planned, but I've been putting this article off for so long that it just didn't feel right to wait any longer. So, here it is, finally.🙂

Collapse
 
hyraxai1 profile image
Hyrax AI •

Thanks!

Collapse
 
georgekobaidze profile image
Giorgi Kobaidze •

You're welcome! 🙏

Collapse
 
vidfoil profile image
VidFoil •

Code only shows the current state; comments and documentation explain the reasons and journey of how we got here.

Collapse
 
georgekobaidze profile image
Giorgi Kobaidze •

That's right. Just the current state is almost never enough.

Collapse
 
capestart profile image
CapeStart •

The regex example is painfully accurate. I can read the code and still have absolutely no idea why those particular rules exist.

Collapse
 
georgekobaidze profile image
Giorgi Kobaidze •

Exactly. Been there, done that.😄

Collapse
 
shane_missler_a02aa4d55e6 profile image
Shane Missler •

As the world of crypt0currency continues to evolve, the risk of falling victim to scams and fraudulent activities also increases. Unfortunately, I recently found myself in this predicament, having lost a significant amount of cryptocurrency to scammers. The experience was not only financially devastating but also emotionally taxing.
However, I was fortunate enough to come across Brunoe Quick Hack, a team of experts specializing in crypt0currency recovery. Their professional and efficient services were instrumental in helping me recover my lost funds. From the initial consultation to the final recovery, the team at Brunoe Quick Hack demonstrated exceptional expertise and dedication to their craft.
What impressed me most about Brunoe Quick Hack was their ability to navigate the complex and often murky world of crypt0currency transactions. Their advanced tools and techniques allowed them to track down the scammers and recover my funds in a relatively short period. Throughout the process, they maintained open and transparent communication, keeping me informed of every step and progress.
If you or someone you know has fallen victim to a cryptocurrency scam, I highly recommend reaching out to Brunoe Quick Hack. Their services are a beacon of hope for those who have lost their hard-earned money to fraudulent activities. With their help, you can recover your lost cryptocurrency and regain control of your financial well-being.
It's essential to remember that cryptocurrency scams can happen to anyone, regardless of their level of expertise or caution. However, with the right help and support, it's possible to mitigate the damage and recover from such incidents. Brunoe Quick Hack is an excellent resource for anyone looking to recover their lost cryptocurrency, and I'm grateful for their assistance in my time of need.
In conclusion, I would like to extend my gratitude to Brunoe Quick Hack for their exceptional service and expertise in recovering my lost crypt0currency. Their professionalism, efficiency, and dedication to their craft are a testament to their commitment to helping victims of crypt0currency scams. If you're in a similar situation, don't hesitate to reach out to them – you won't regret it.  Contact: Email>>> BrunoeQuickHackATgmail.com  
WhatsApp at:: +170578 (42635)

Collapse
 
austriasoftwaroftwaredeveloper profile image
Jack •

"clear code" ⊆ clean code

Collapse
 
georgekobaidze profile image
Giorgi Kobaidze •

Sure, it's a subset of clean code, but unfortunately in practice it doesn't always work that way. There are always tradeoffs.

Collapse
 
austriasoftwaroftwaredeveloper profile image
Jack •

thnks for your input