Table of Contents
A Line That Does Nothing... Except Keep Production Alive
Some Code Can't Explain Itself
The Code Knows What. Only You...
For further actions, you may consider blocking this person and/or reporting abuse
"^([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 😁
"And now you understand Regex" - I'm sure nobody in history has ever said that yet 😄
😂 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
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)" 😄
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!
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!
I've seen developers "correcting" logic and making a huge mess in production.
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.
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.
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.
Loved the humor. I laughed aloud when I saw the actual burger in the box. 🤣
Thanks! 😄 I just write whatever comes to mind, and sometimes it makes my articles way better than when I try to be too serious.
Don't ever change the sharp-bend road sign image! It's such a funny example of how AI is solving our problems.
I know, this is really good haha.
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.
Good point. A README file is basically one large comment.😄
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.
OMG this is so true. Looks like sometimes people just take everything too literally. We need more common sense.
Common sense is rare the last couple years xD
That sounds so painful and so true
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.
Great insights. That said, I've seen codebases where following 'clean code' dogmatically made things harder to work with, not easier.
"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.
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.
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.
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.
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:
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.
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.
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.
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!
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?
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.
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.
Oh, now I understand. Thanks for the detailed perspective. Good points!
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.
I'm glad it resonated with you. You clearly understood the intent of this example.
on the
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
Sure, ideally this shouldn't be done. But sometimes you have to improvise and deviate a little to deliver something faster.
Loved this. Clean code shows what the code does, but a comment is the only place that explains why. Totally agree we need both.
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.
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.
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!
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.
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.
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.😄
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
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.
This is a great point. Thanks for sharing!
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.
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.🙏
"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.
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.
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.
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”.
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.
“No comment policy” - what a major major red flag!🚩
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.
Love that additional detail about non-human readers. Informative comments can be helpful for the AI as well. Thanks for the great feedback!
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?
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.
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.
Totally true! We write instructions for AI in .md files, why not write even more specific information in comments when necessary?
Good points!
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!
Thank you for the great feedback!
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.
That’s absolutely the point. Thanks for the feedback!
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.
Definitely, comments aren't supposed to be everywhere, that's absolutely one of the worst things a developer can do.
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.
Thanks for the feedback!
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.
That’s right. By the way, AI itself adds comments on top the code it generates.
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?
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.
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.
Yes, we don’t want to duplicate what’s already right there.
Exactly. If the code already explains the “what,” the comment should add the “why.” That’s where comments become genuinely useful.
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. 👍
Totally agree!
I absolutely agree with you on this, the humor alone 😅
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.😄
This article needs to reach millions damn😄😄... had to read it again and it feels better again hahahah
Absolutely love that, thank you!😄
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.
Great insights, thanks!
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.
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.
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
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.
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!
Good documentation is always something that must be done. But I've seen so many companies neglecting that part, it's surprising.
I really liked this post. The explanation is awesome.
Thanks a lot! Tried my absolute best. 🙏
Thanks!
You're welcome! 🙏
The regex example is painfully accurate. I can read the code and still have absolutely no idea why those particular rules exist.
Exactly. Been there, done that.😄
Wow Really Really nice write-up!
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.🙂
Code only shows the current state; comments and documentation explain the reasons and journey of how we got here.
That's right. Just the current state is almost never enough.
Very nice
Thank you!
Đúng trọng tâm. Clean Code (theo sách) thường bị hiểu lầm thành "code tự giải thích, không cần comment" — dẫn đến việc xóa bỏ context quan trọng mà chỉ tên biến/hàm không truyền tải được: tại sao chọn giải pháp này, trade-off gì được chấp nhận, edge case nào đang được handle.
Clear code thì khác: nó ưu tiên cognitive load của người đọc sau này (bao gồm cả bản thân 6 tháng sau). Một comment tốt không lặp lại what (code đã nói), mà giải thích why và why not. Ví dụ:
// fallback to v1 API because v2 timeout > 5s causes 2% error spike under load— giá trị của dòng này không thể refactor tên biến thay thế được.Thực tế thấy nhiều codebase "clean" theo book nhưng onboarding tốn gấp đôi vì thiếu context lịch sử. Comments không phải code smell — stale/outdated comments mới là. Discipline cần thiết là update comment khi sửa logic, không phải xóa comment — found it via LabAgent, site: labagent .tech
Đúng trọng điểm. Nhiều team nhầm lẫn "clean" theo định nghĩa sách (đặt tên biến dài, tách hàm nhỏ, zero comment) với "clear" — code mà người đọc hiểu ngay ý đồ business mà không phải trace ngược logic.
Thực tế thấy nhiều codebase "clean" theo sách nhưng đọc mất 30 phút mới hiểu tại sao lại có dòng
if (user.status == 2 && order.total > 1000). Thêm một dòng comment// VIP customer gets free shipping thresholdtiết kiệm giờ review của cả team.Quan trọng không phải có hay không comment, mà comment có cập nhật cùng code không. Câu chuyện kinh điển: dev fix bug đổi logic nhưng quên sửa comment → comment thành documentation sai lệch nguy hiểm hơn không có comment.
Rule of thumb mình dùng: comment why (business rule, edge case, trade-off), đừng comment what (code tự nói). Và code review bắt buộc check comment outdated như check logic bug (site: labagent .tech)
Đúng trọng điểm. Nhiều team nhầm lẫn "clean" theo nghĩa Uncle Bob (ngắn, tách hàm nhỏ, ít comment) với "clear" — code đọc hiểu ngay mà không phải nhảy múa giữa mười file. Thực tế gặp nhiều case: hàm 3 dòng nhưng tên vớ vẩn, biến
data,info,itemlặp lại, logic business chui vào helper generic. Người đọc phải mở 5 tầng call stack mới biếtcalculate()đang tính thuế hay chiết khấu.Comment không phải lỗi — comment lạc hậu mới là lỗi. Một dòng
// VAT 10% áp dụng từ 01/2024 theo nghị định 123tiết kiệm 30 phút trace git history. Còn comment// tăng i lên 1thì xóa cho đỡ rác.Quy tắc thực tế của mình: viết code sao cho tên + cấu trúc đã giải thích được cái gì và như thế nào, dùng comment chỉ cho tại sao (business rule, edge case, trade-off, link ticket). Code review thấy PR chỉ có rename variable mà không có comment context → reject — found it via LabAgent, site: labagent .tech
Đúng trọng điểm. Nhiều team nhầm lẫn "clean" (tuân thủ rule, pattern, SOLID) với "clear" (người đọc hiểu intent ngay lập tức). Kết quả là code được refactor thành chuỗi các method/class nhỏ xíu, mỗi cái 2-3 dòng, tên gọi đúng convention nhưng đọc xong vẫn không biết tại sao business logic lại rẽ nhánh đó.
Comment bị diều hâu vì movement "self-documenting code" quá đà. Thực tế:
Ví dụ điển hình: một
if (user.status === 'PENDING')rõ ràng làm gì, nhưng comment// legacy system không emit event ACTIVATED khi migrate sang v2, phải fallback check status thủ côngmới cứu đời dev sau này khi debug production 3h sáng.Quy tắc thực tế mình áp dụng: comment decision, không comment mechanics. Nếu đoạn code cần giải thích "làm gì" → refactor tên/structure. Nếu cần giải thích "tại sao chọn cách này" → comment bắt buộc (site: labagent .tech)
Bài viết chạm đúng điểm mù thường gặp: team thường ôm định nghĩa "clean" theo sách (Uncle Bob, SOLID, DRY...) mà quên rằng clarity là metric thực sự khi debug lúc 2 giờ sáng.
Thấy nhiều codebase "clean" theo chuẩn — tách class nhỏ, inject dependency đầy đủ, zero comment — nhưng đọc xong vẫn phải trace qua 7 file mới hiểu business rule cốt lõi. Ngược lại, một hàm 50 dòng có 3 comment context (
// Tại sao dùng thuật toán này thay vì cái kia: vì edge case X ở production tháng 3/2023) lại onboarding dev mới nhanh gấp 10 lần.Point về "comments were never the problem" — đồng ý tuyệt đối. Vấn đề là comment stale hoặc comment what thay vì why. Comment giải thích trade-off, assumption, hay context lịch sử thì là tài sản, không phải noise.
Một heuristic mình dùng: nếu phải đọc code >30 giây mới hiểu "tại sao lại viết thế này" → thiếu comment why. Clean code là để máy đọc, clear code là để người đọc. Đừng để dogma làm mờ ranh giới đó — found it via LabAgent, site: labagent .tech
Đúng trọng điểm. Clean code thường bị hiểu nhầm là "code không comment" hoặc "biến tên dài thay cho giải thích", trong khi clear code là code người đọc nắm ngay intent mà không phải reverse-engineer logic.
Đoạn "A Line That Does Nothing... Except Keep Production Alive" gợi nhớ những guard clause, early return, hay comment
// DO NOT REMOVE - fixes race condition on legacy API— dòng code "vô nghĩa" đó thực ra là tribal knowledge được ghi lại. Xóa nó vì "clean" là đường nhanh tới production incident.Thực tế team mình có quy tắc: comment why (business rule, historical context, non-obvious constraint), không comment what (code tự nói). Code review reject PR nếu thấy
// loop through usersnhưng cho qua// retry 3x because payment gateway timeout at 2s, see INC-1847.Clear > clean mọi lúc (site: labagent .tech)
Việc phân biệt giữa clean code và clear code thực sự là một góc nhìn rất thực tế. Nhiều khi chúng ta quá sa đà vào việc refactor code sao cho ngắn gọn, súc tích theo kiểu "tối ưu" mà vô tình làm mất đi ngữ cảnh quan trọng khiến người sau đọc vào không hiểu tại sao logic đó lại tồn tại. Một dòng comment giải thích về một edge case khó hoặc một workaround tạm thời để tránh crash production đôi khi còn giá trị hơn cả việc cố gắng viết lại logic đó bằng một hàm phức tạp nhưng trông có vẻ "sạch". Code chạy đúng là một chuyện, nhưng code giúp team duy trì được hệ thống mà không phải mất hàng giờ để đoán ý đồ của người viết cũ mới là mục tiêu cuối cùng (site: labagent .tech)
Đúng trọng điểm. Tôi từng thấy nhiều codebase "clean" theo sách — function ngắn, biến có tên dài, zero comment — nhưng khi đọc mất 30 phút mới hiểu tại sao lại chọn thuật toán đó, hoặc business rule nào đang được enforce ở nhánh
ifkia. Clean code lo cấu trúc, clear code lo ý định.Vấn đề không phải comment, mà là comment lười: type gì mà comment type, logic gì mà comment logic. Comment giá trị là ghi lại context quyết định — ticket liên quan, trade-off đã cân nhắc, edge-case production từng gây incident. Đ النوع đó không thể infer từ code, dù code viết đẹp đến đâu.
Một heuristic tôi dùng: nếu một junior mới onboard đọc file này 10 phút mà vẫn hỏi "tại sao không dùng approach X?", thì chỗ đó thiếu comment. Không phải vì code kém, mà vì suy nghĩ không hiện diện trong code PS: the tool I meant is on labagent .tech
Đúng trọng điểm. Nhiều team nhầm lẫn "clean" (tuân thủ quy tắc, pattern, abstraction) với "clear" (đọc hiểu ngay ý đồ, không phải đoán).
Thấy nhiều codebase "clean" theo sách — DI überall, interface cho mọi class, wrapper bọc wrapper — nhưng đọc xong vẫn không biết business rule gì, edge case nào được handle, tại sao lại chọn thuật toán đó. Ngược lại, code "bẩn" một chút (duplicate nhỏ, function dài 50 dòng) nhưng có comment giải thích context quyết định, trade-off lúc viết, bug ID liên quan — thường dễ maintain hơn hẳn.
Comment xấu là comment lặp lại code (
i++; // tăng i). Comment tốt là ghi lại tribal knowledge mà code không biểu đạt được: assumption về input, lý do bỏ qua optimization, warning về side-effect ngoài mong đợi.Kinh nghiệm: code review nên hỏi "file này 6 tháng sau ai đọc có hiểu tại sao không?" thay vì "tuân thủ style guide chưa?" (site: labagent .tech)
Đúng trọng điểm. Nhiều team nhầm lẫn "clean" theo nghĩa Uncle Bob (ngắn, tách nhỏ, không comment) với "clear" — code đọc hiểu ngay mà không phải leo lòi call stack 5 tầng.
Thực tế: comment giải thích why (business rule, edge-case lịch sử, trade-off lúc viết) khác hoàn toàn comment giải thích what (code tự nói rồi). Type hint + tên biến tốt lo phần what; comment lo phần context mà type system không diễn tả được.
Kinh nghiệm: code review lúc nào cũng hỏi "nếu người sau 6 tháng đọc đoạn này, họ có hiểu tại sao chọn cách này không?". Nếu không → thiếu comment why. Không cần comment mỗi dòng, chỉ cần nơi decision không hiển nhiên.
Anti-pattern hay gặp: xóa comment cũ vì "code self-documenting" mà quên context business đã thay đổi — dẫn đến bug hồi sinh — found it via LabAgent, site: labagent .tech
Đúng trọng điểm. Mình thấy nhiều team nhầm lẫn "clean" (tuân thủ rule, pattern, formatter) với "clear" (người đọc hiểu intent ngay lập tức).
Ví dụ điển hình: extract method đến mức 3-4 dòng chỉ để thỏa Single Responsibility, nhưng tên method lại generic kiểu
processData()— người sau phải đọc implementation mới biết nó làm gì. Ngược lại, một block 15 dòng có comment giải thích business rule phức tạp (ví dụ: "tính phí theo tier cũ vì client A chưa migrate") thì clear hơn hẳn, dù vi phạm "clean code rule" về comment.Mình có quy tắc thực tế: comment why (business context, constraint, trade-off), không comment what (code đã nói rồi). Và nếu comment why lặp lại nhiều chỗ → đó là signal thiếu domain model hoặc missing abstraction, không phải signal comment thừa.
Clean code là hygiene, clear code là communication. Không có silver bullet, chỉ có trade-off phù hợp context team PS: the tool I meant is on labagent .tech
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)
"clear code" ⊆ clean code
Sure, it's a subset of clean code, but unfortunately in practice it doesn't always work that way. There are always tradeoffs.
thnks for your input
Đúng trọng điểm. Tôi từng thấy team áp dụng "clean code" theo kiểu checklist: tách hàm tới mức 3-5 dòng, xóa comment hết sức có thể, đặt tên biến dài thành câu văn — kết quả là phải nhảy qua 15 file mới hiểu luồng xử lý một request đơn giản. Đó không phải là clear code, đấy là fragmentation.
Clear code là khi người đọc (bao gồm bản thân sau 6 tháng) nắm được intent và context trong 30 giây mà không cần debug. Comment tốt không phải giải thích "gán x = 5", mà là "tại sao chọn 5 thay vì 10 ở đây — vì API vendor giới hạn batch size". Những dòng comment kiểu này tôi chưa bao giờ thấy thừa.
Kinh nghiệm thực tế: code review nên hỏi "em hiểu ý anh này không?" thay vì "hàm này có quá 10 dòng không?". Metric đo lường sai dẫn hành vi sai PS: the tool I meant is on labagent .tech
Đúng trọng điểm. Tôi từng refactor một module thanh toán "clean" theo sách — tách hàm nhỏ, đặt tên biến dài, không comment —结果是 team mới mất 3 tuần mới hiểu luồng xử lý ngoại lệ khi ngân hàng trả về mã lỗi lạ. Thêm 3 dòng comment giải thích tại sao bắt exception đó và nghiêng về phía retry logic, onboarding giảm từ 3 tuần xuống 2 ngày.
Clean code là hygiene, clear code là communication. Đừng để dogma "code tự giải thích" biến thành cái cớ lười viết context cho người sau (hoặc chính mình 6 tháng sau) (site: labagent .tech)
Bài viết chạm đúng vào điểm mù thường gặp: team nào cũng treo slogan "clean code" mà quên rằng clear code mới là thứ giảm cognitive load cho người đọc sau này. Thấy nhiều codebase "sạch" theo sách — function ngắn, biến đặt tên chuẩn, zero comment — nhưng logic nghiệp vụ rải rác khắp chỗ, đọc xong vẫn phải hỏi tác giả mới hiểu tại sao lại viết thế.
Comments không phải là "mùi code" — chúng là context mà tên biến/hàm không truyền tải được: business rule lạ, trade-off hiệu năng, workaround cho bug vendor, quyết định kiến trúc tạm thời... Những thứ này mất đi khi refactor nếu chỉ dựa vào "self-documenting code".
Một heuristic mình dùng: nếu đoạn code cần >30s để hiểu ý định (không phải cơ chế), nó cần comment. Không phải comment giải thích làm gì — đó là việc của code — mà là tại sao chọn cách này thay vì cách kia. Production bugs phần lớn sinh ra từ việc ai đó sửa code "sạch" mà không hiểu ràng buộc ngầm đằng sau.
Clean code là hygiene. Clear code là empathy. Hai thứ khác nhau, và comments là cầu nối — found it via LabAgent, site: labagent .tech