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
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!
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.
"^([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)" π
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.
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.π
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.
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!
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.
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.π
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!
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.π
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.
"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.
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. π
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.π
Thanks!
You're welcome! π
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?
"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.