The Real Art of Commenting Code

The week from my last post sure did fly by, huh?

Today we’ll talk about comments in the code. Regarding comments, nothing had really changed since Bob Martin’s Clean Code: “Your code should explain itself, not comments”. But would this stop me from writing an article on that though? That was a rhetorical question.

Q: Would it be yet another copy-paste article with all the same items?
A: No, it’s the Real Art of Commenting the Code.

We’ll go deep here.

The best part, of course, is saved for last, so you’ll have to go through the entire article thus increasing the read rate, which should probably increase some metrics for the Medium algorithm.

Let’s start with the usual offenders.

English… Do you speak it?

It’s totally fine that English is not your first language. This does not mean I should see comments for code or commits in Russian though.

I once worked on a project where the core codebase was… in French. Fancy a Demandeur or Offre class? Or how about Ville::getAdressePostale?

Never allow anything except English in your code or comments.

I-am-a-student

Check this one out. If you need every line commented, your code probably should never go to prod.

What is the easiest way to show everyone you’re a noob?”

I remember myself studying Computer Science. Seeing other students do this would make me cringe. Don’t do it, even if you’re a student. If your professor demands you comment every line, then he probably has some deep psychological issues, just like Bob whom we’ll meet later in the article.

Chatting in the comments (yes, really)

There was one project that I was asked to fix the loading speed for: it was appallingly slow. It was in Bitrix. What is Bitrix? It’s a disgusting overcomplicated abomination of a CMS that lacks any hint of proper architecture. It’s like Wordpress with its almighty wp_meta, but without the ecosystem and much much worse.

I was young and I needed money.

dev002: please add the “resend SMS” button.
dev001: no need, we have it earlier in the code

“ненадо”…

Outdated comments

So, you removed a piece the code, but the comment that was right up there referring to the code you removed is still there…

I will find you and make you regret that.

Commented out pieces of code

You’ll surely need them later! There’s no way you could browse the file’s history in Git, so if you delete it, you lose it.

The rule of thumb is: the comments should enhance the code, not be the code.

You need refactoring, not comments

Leaving the comment about intersecting intervals may seem like a reasonable thing to do, but consider this:

Is there a world where #2 is worse than #1?

Thanks, Captain Obvious!

Wow, what does this function do? Does it save the element to the database? Does it get the element’s creation date? Oh boy, I definitely need to check the jsdoc.

Now, what you should be commenting:

Documentation

Normally, code should document itself. But what if your Front-end team needs to know what APIs to use?

Just make sure that Swagger doc is maintained.

Explaining some complex logic or crutches

This is that obvious thing that all those copy-paste “The Art of Comments” articles agree on: if you have some complex or not very straightforward logic in your code, comment it. Mindblowing, right?

And here goes the best part…

The Best Part

We all know that you, my dear reader, are an ace of programming. You despise crutches, you always follow the best practices and you have the 100% test coverage.

But some plebs of the programming world have to deal with that pesky stuff. The Legacy code, come places you’d rather not touch or even, God forbid, code that smells.

Sometimes people have to push the not-so-good code to prod. Do not fool yourself: once pushed, this code stays there forever, because all those “temporary” measures are, in fact, permanent. You will not have any “free time” in future to go and fix all the mess you’ve created. But that’s a topic for another Medium post.

All those “temporary” measures are, in fact, permanent

The point is, bad code happens.

“Beware: Bad code ahead” Comments

This comment was left not by the person who wrote that function. Otherwise it would be awkward.

Some might say that commenting something like that is, in fact, a bad thing, because you should fix, not comment. But where does the line lie between “oh, it’s a quick fix, let me do it” and “OK, let’s do some refactoring that might introduce regressions and will take time although we need it in prod ASAP”?

I say:

These comments are a good thing.

Why? First of all, it’s a TODO. Rarely would you go through TODOs, but this is something I wrote about in my previous article:

You should be aware of the bad/risky places in the project

Bad code, or, rather, bad solutions, happen because of three reasons:

1. Incompetence
2. Attitude
3. Lack of time

Incompetence

This is what Code Review is for. If you have incompetent people working for you who produce bad code and shove it to master branch without proper review, then you have a slightly more important problem that “should I allow comments that say the code is bad?”.

The I-don’t-give-a-flying-F attitude

This is arguably worse than Incompetence. Burnout? Lack of sleep? Or maybe the guy is just a selfish jerk? Again, it looks like you’ve got a more important problem than policing what people write in comments.

Lack of time

I pride myself in being able to deliver in tight time. Like, really tight time. Sometimes, especially when working on the existing codebase with a ton of quirks and features, you have to do things that you wouldn’t normally do if you had time.

So, the demo/hotfix/release/whatever happens. There may be things that need to be addressed immediately after that, and then there’s the rest, which is “Okay-ish, I guess”, which you promise to fix in the next refactoring sprint, but then life happens, and the refactoring sprint doesn’t — or, at least, not as soon as you want. So, the code sticks around.

The first two reasons are solved by properly reviewing pull requests, and the last one is more about management than anything.

Q: But Alex, people will see PRs with // this code sucks comments and think that it’s OK if the person acknowledges the poor code quality!
A: Seriously?

And here’s one more thing that most of copy-paste articles agree on: it’s bad to leave such comments because other people will see them and think bad of you.

So, consider 3 cases:

1. A competent developer sees bad code with your // I am sorry, this sucks comment. Since the premise is that they are competent, they would not need your help understanding that what they are looking at is a piece of garbage. What they might learn from your comment is that you at least understand that this code stinks. And that you are sorry.
2. An incompetent developer, who would not otherwise know this code is bad, will learn that. And they would not use this code as a sample of what they should do. Your codebase is an implicit “Do like this” for a Junior Developer who does not know how it should be done yet. So, if you are to give him some bad examples, at least let him know it’s a bad example.
3. A non-technical person that otherwise would not know the code is bad and sort of does not need to know the code is bad. Yeah, why does our Product Owner (who for some reason decided to read the source code instead of this awesome Medium blog) need to know the code stinks? Better convince them that it’s all peachy and so clean one would eat from that just to surprise them later with “Oh, it’s a bug with the legacy code, I do not think we should fix it”.

This is what pisses me off when I read articles like this.

…they end up making the coder who wrote them and their employer look unprofessional and bitter.

Well, color me surprised! Commenting about the code quality makes you and your employer look unprofessional, but pushing this shit to production in the first place somehow doesn’t? Seriously?

Of course (and this is how that article justifies its verdict), calling your colleague a “clueless idiot” is something I would recommend to abstain from.

Use your head (and check out the Afterword of this article too). Do not comment “This will be fixed when I get sober” in your work project so that your colleagues and, eventually, management would know that you follow Hemingway’s advice “Write drunk, edit sober”.

This is what a high-quality comment in a pet-project looks like

The only problem is that you feel less guilty for doing that. But:

1. you’ll forget about it anyways and the guild will go away in both cases
2. the guy reviewing your PR will be your conscience

Any benefits of leaving such comments?

1. You let people know the code is bad. Junior developers will see this and hopefully not do like you did.
2. When another refactoring sprint happens, it’ll be easier for you to find all the places that require attention.
3. When your manager reads my article on Dangerous places (there’s nothing that can stop me from linking to my own posts again and again) and comes to you and asks: “Hey, %username%, I’m concerned! Do we know what are the bad and dangerous places in our codebase?” you won’t mumble, ask for time for research and avoid eye contact. No, you’ll look that guy dead into the eyes and say loud and clear: “I’ve got you covered, baby!”.
4. Since you’re probably committing bad code anyway, your colleagues at least won’t think you’re a clueless idiot who can’t tell bad code from good code and commits crap. At least you know that your code is bad, right?
5. Emotional Intelligence — the next session is dedicated to that.

Let’s get emotional

Imagine this: you work day begins. You take a sip of freshly-brewed coffee, open your laptop, check Jira. And what you see is a new task to fix the bug in the part of the project you’ve never touched. Surprise-surprise, that not the “good” part.

Or your colleague goes on vacation/quits/gets fired for his shitty code and now you are the guy responsible for that nasty, vile abomination of a module.

2 hours after getting into the business, you start asking questions about that masterpiece, ranging from

“Why import entire lodash instead of using Array.forEach?”

and

“Do you know God-objects are an anti-pattern and the controlPanel instance that you’re passing through the hierarchy of 10 components is exactly that?”

to something more radical like:

“Were you molested as a child? Who did that to you? Do you want me to suffer as well?”

And now you’re pissed. Because you’re stuck. Because this code is garbage. And that guy, Bob, who wrote this is now on vacation laying on a beach sipping mojitos, maybe thinking to himself “I wonder, what poor schmuck would maintain my code while I’m here”.

The more you dig, the more pissed you are. Would it be better if Bob apologized? Or gave you some heart-worming “Sorry man. I know this is not cool, but I had to do this because so-and-so”?

Of course, much better would be to have good code in the first place. If seeing someone’s code makes you wonder about that person’s ACE score, then sweet comments won’t fix the thing, and you’ve got a big problem with your codebase. But at least you will not be that angry with Bob, because he apologized and shared your misery and you’re less likely to be angry with a person who apologized.

Some deep stuff here.

Just put that smirk from your face, Bob. After I saw what you did in LocationSettingsService, I will never be able to smile again.

I feel i have to say it: the Bob story with terrible code that makes you question your life choices is an exaggeration for dramatic purposes. If a code is really that bad, no amount of //Sorry will ever help. Go talk to your manager and get this smart-ass fired.

Do not take this as this article as “If I write some witty comment about how bad the code is, I can push whatever I want and it’ll be fine”.

No, it will not.

Bonus points if you make your colleagues smile.

Just to make it clear, once again, this is not “How to commit shitty code and not feel guilty” tutorial.

I’ve always said this:

If you have to write something not nice, make it as local as possible.

No crutches in architecture are allowed. Ones on the local level, though:

Who needs form validation rules anyways?

Some bashing of IE which some people still require the support of in 2019 is always welcome:

Some huge IE rants are questionable but understandable. Just make sure it’s justified and the company policy allows it.

Did my best at censoring.

When you’re not supposed to manipulate DOM, but you have to

Tell me more about how good Dirty-checking is in Angularjs.

Afterword, or the story of One Hundred Penises (yes, really)

If you have ever worked at Itransition (which I do not recommend) or went through their internship program (which I do recommend), then you’ve probably heard about CTO XYEB [sto khu’yev].

The story has it, this was a comment left by one of their programmers in a banking software that later had to undergo some heavy review by some fintech certification authority to make sure there were no backdoors or any other surprises there.

Eventually, they noticed //CTO XYEB and they didn’t understand its meaning. So naturally the team lead was asked to translate this tiny bit of folklore. You see, CTO XYEB in latin letters is almost identical in writing to СТО ХУЕВ in Cyrillic, which means one hundred penises. Since non-latin characters were not allowed in the code (which is the only right way to go, btw), some developer decided to bring a tiny bit of cultural code to his Swiss colleagues.

The moral of this story if: as always, know your limits. If you get fired for taking it too far with some edgy stuff or for adding penises in your code… well, that’s on you.

If you’d like me to work with you, feel free hit me up on Linkedin or drop me a line at alex@xfuturum.com.

Post the best comments you’ve seen in the code… well, in comments.

Cheers!