This post first appeared on SubMain’s blog.
We often focus on code fails. But what else have we seen and done that makes us drop our heads in shame and frustration? What else do we laugh (and cringe) at when reading code? The comments!
Whether they’re redundant, unreadable, confusing, or there’s just no comments at all, we can learn a lot from failure. And to spice things up, I’m going to throw in a biking analogy. You’re not sure if that’ll work? Me neither. But let’s go on this ride together and find out.
The Biking Analogy
There are similarities between your growth as a developer and riding a bike. More specifically, when you’re just learning to program, you make different mistakes than when you’ve been doing it for 10-15 years.
As you grow in your biking skills, you start to ride faster and take more risks—therefore, you also crash more spectacularly. The same can be said of your skills in writing software. Over time you produce code at a faster rate. You don’t make the simple mistakes that someone learning would make. Instead, you make more complex mistakes that are harder to see and harder still to fix.
Now that you’re on board with the analogy, let’s look at some of the comment fails we make at all different stages of the learning-to-bike/code process.
Say Goodbye to the Tricycle
When you’re new to programming, you’re mostly focused on syntax, getting something to actually work, and following the instructions you are given. Therefore, your commenting fails will be frequent. However, they won’t create any more confusion than your immature code will have already created. Let’s look at a couple examples.
First, let’s say you had one of those professors who insisted you add a comment to every line. If that is what you were taught, then of course you will end up with something like the following snippet that’s all over the place.
// the width double width = 0D;
This comment doesn’t really add value. It takes up space and clutters the code.
Or perhaps your professor was even more misguided and required three lines of comments for every line of code. Yuck! Who does that? And how do you get around it when you’re commenting on a simple field? Oh, here’s how.
// the length of the // box that we will // measure area for. double length = 0D;
Either way, you’re not adding much value with these comments.
Let’s Loosen Those Training Wheels
Now that you’ve grown a bit as a developer, you learn about writing pseudo code or comments first to get the layout of what you’ll be coding before you start. But at this point, you’ve only loosened your training wheels. They’re still on there. Hopefully soon, you’ll be able to remove them.
public void AddOrder(int customerId, Order order)
{
// Get customer
var customer = repository.GetCustomer(customerId);
// Add order
customer.Orders.Add(order);
// Save customer
_repository.Save(customer);
}
In the example above, we have more unnecessary comments. Anyone with more than a few days of programming will know the code above is getting a customer, adding an order, and then saving. It’s a bit more helpful than the tricycle example, where you’re just decorating any noun you come across, but it’s still not actually giving the reader anything more than they can already read!
The Training Wheels Are Coming Off
One of the next hurdles is learning to trust and properly use your version control. You may have heard of another “great” use of comments: that you should be commenting on every change you make in your source code.
// class: PurchaseOrder
// created: March 25, 2018 10:15AM
// Author: Ned
// Revisions: Marge (March 28, 2018 08:15AM) - Added Vendor
// Moe (March 29, 2018 11:32AM) - Changed Vendor to Supplier
public class PurchaseOrder() {
...
}
Now at first glance, you might think this is OK, even helpful. But the more you program and the more you use your source control properly, the more you’ll realize that this is just unnecessary clutter that doesn’t add value. Up against pressure from your team, you will probably follow that sad standard of over-commenting. But you must resist. Version control takes care of this for you and in a much cleaner way.
Here’s another bad habit you may pick up from your team: leaving unused and commented code in your file. Keeping a bunch of commented out code is not doing anyone any favors. Why do you do this? That’s not what comments are for!
Do you know what else comments aren’t for? Logical separators in a large method.
lots of code doing something... //////////////// more lots of code doing something else... //////////////// even more lots of code doing something more than something else...
Here you’re not even using a comment but sticking in something big and visible to show that your method does a lot of things. If you’re doing this, then your method is too big, too complex, and definitely too unreadable. Break it up into smaller methods or decompose new entities. Don’t leave these lying around!
And before we move on, here’s one more example of a comment that is telling you your code is too complicated:
} // end first if
} // end while
} // end 2nd else
} // end 2nd while
} // end method
If you can’t track which loop you’re in without these comments, then there’s a bigger problem developing.
Look, Ma! No Hands!
You’re growing as a developer, and you’re starting to care more about code quality. So you’ve started to use a linter to analyze your code. Just like the professors you studied under early on in your career, your linter suggests that you shouldn’t have any empty methods. So what do you do?
// do nothing
Hey, great. This here is doing nothing. What information does that even give me? Oh yeah, that’s right. Nothing. There’s no value in this comment. However, there are different reasons to have empty methods. And you haven’t clarified as to which case this is. Is it because under this condition, you really should do nothing? Or is it just generic template code that you want to ignore? Or perhaps it’s functionality that future you will have to worry about, but current you doesn’t have an answer for yet. Be explicit with why you’re doing nothing to help clarify the unknown.
Let’s move on to another example. Since your skills are growing, you’re starting to feel pretty good about yourself as a developer. You see shortcomings in other code that you work with. And you might want to add comments that display your knowledge of best practices. You want others to know that it was not your choice to write code in a certain way; you were restricted by the limitations of some half-baked library! So what do you do? Here we come upon the passive aggressive comment.
// Had to do this because of the over-engineered design of x.
And let’s not forget the “soapbox” comments! The rants that go on for 20 lines about your personal truth as it comes to software design. Yes, we get it. You are very smart. But comments is not where you should be using that intelligence.
They See You Rollin’. They Hatin’.
You’ve advanced to a point where others look to you for answers and advice. You know what you should do and what you shouldn’t when it comes to code. You are fairly sure of yourself, and you want to be a good example for others. So when you do something not quite in line with your standards, you add the following:
// Temp hack
Or even better:
// I know I should never do this, but..
This is the “do as I say, not as I do” method of commenting. Just because you’ve stooped to that level doesn’t mean you would allow others to stoop so low.
So what should you do instead? Own the code and give some background as to why it’s the right choice. Or take some time and write code that you would be proud to hang on your fridge. The bottom line is that no one wants to hear your excuses. They want to see good, clean, and functioning code.
You Do Your Own Stunts
You’ve advanced quite a bit in your career. Perhaps you’re writing libraries for other teams in your company to use. You’re designing frameworks and mentoring others. What else are you doing that might still be throwing others off who read your code?
Well, you may be leaving behind some famous last words.
// should never get here
Yes, I get it. Sometimes we truly will never get to a certain part of code. But I’ve also come across many instances where we do, in fact, “get here.” And we aren’t sure how we got here. And worst of all, we have no clue as to what to do when we inevitably do get here.
Another form of famous last words is TODO comments. You know these. You put these in so you don’t forget to come back to something. But then you run out of time, and next thing you know, it’s 2018 and your IDE is telling you there are 325 TODOs in your project. Although you know you should just delete most of them, you don’t. And they’re left there for the next maintainer to wonder about. Unfortunately, that next maintainer doesn’t know the difference between what you considered a “nice to have” TODO comment and one that needs to be fixed as soon as possible to avoid certain doom. Be clear with your TODO’s. And if they’re that important, make sure they’re resolved quickly and removed from the code base.
What Else Have You Seen?
As we evolve, we want to identify not only others’ commenting fails, but our own. Therefore, sharing not just the blunders we see, but the blunders we’ve made will create an environment of learning and growing. Others will come to you with questions if they know you’ve been through some of the same things they’re going through.
Don’t feel bad if you’ve made commenting fails. Only feel bad if you haven’t learned from them. Likewise, don’t hold it against your fellow developer when they fail as well. We’re all learning this stuff as we go. Let’s laugh at the simple mistakes we’ve made and then move on to the new mistakes we’re about to make.