Mar 302013
 

All developers have been in this situation, sitting around, staring at the monitor, trying to make sense of the code staring us back. It’s a tough, miserable period for developers going through this. Specifically, it’s a tough, miserable period for developers that doesn’t have to happen. No matter what the code that does this to you, there’s 1 common, glaring thing in common with the code that does this to developers – there are hardly any, if any at all, comments in the code. In the interest of sparing developers this pain, here are some simple rules about commenting that will reduce developer suffering whenever somebody has to read your code.

I. Comments are good, therefore thou shalt ****ing write them

Given that this issue starts with the fact that we’re staring at code with no comments, we clearly need to start with the basics. Comments were created for a reason, to make code easier to read and understand. Specifically, to make code you don’t spend all day every day in easier to read and understand. Don’t sit there and pretend you can remember every decision and intent for every line of code you’ve ever written either, you can’t, especially if you’re in a job where you’re context-switching between sections of the code. And if anybody has to try to maintain this code, they’re either going to take a lot longer than what it normally takes to get things done in the code, or leads to you getting less done because people keep asking you questions that could have been answered if you had only put some notes in the software as to what the heck you were doing and why. Stop wasting your time, stop wasting other developers’ time, and stop breaking Wheaton’s Law – comment your code.

1 of the first things I did on my latest program was start asking questions about why things were done the way they were done, or why things weren’t working the way I thought they were. On a few occasions, the answer to my question started with the phrase “Oh yeah, I meant to write a comment, but…” Don’t be that guy who lets other developers write bugs, or makes it harder for people to do their jobs. Comment your code and what it’s supposed to be doing so we can understand what’s going on and why.

II. Documentation comments are still comments, therefore thou shalt ****ing write them too.

While comments in the code itself are tremendous, for a lot of code, the only comments we’ll ever see are the documentation comments you put on your methods and any member variable that’s publicly visible. At the very least, you should be using your language of choice’s version of documentation comments to tell other developers what that code does and why. Not providing documentation comments leaves developers with 3 bad options:

  1. They’ll take a wild guess and hope for the best. Now, if your method name is descriptive, and accurate, this isn’t too bad of a risk, but if there are any preconditions you’re assuming, or things people need to be aware of when they call your code, this is going to crash and people are going to start to wonder if you just wrote crappy code. 
  2. It encourages developers to consider another set of code with better documentation. Developers are trying to get things done, and it’s easier to get things done if we know exactly what the libraries and code we’re working with does. If you don’t document how to work with your code, and people have the option to go with a better-documented option, they’ll take it.
  3. They have to read through the code itself, which probably isn’t documented either if you couldn’t be bothered to document the methods. This wastes time, makes it harder to get work done, and encourages people to screw with code you’ve already written and have working, simply because they’re there and had a thought.

Documentation comments are amongst the most important, and most useful, comments you can write. API documentation, often generated from those very comments, are what we see most often. and can be the first thing we look for when trying to get things working.You’ve probably looked at good function documentation and realized how helpful it can be, now this is your opportunity to be just as helpful to all the developers coming behind you trying to get your crap to work. Be a good human, write documentation comments.

III. Thou shalt document every piece of branching logic in your code

Any time your code can do 1 of multiple things, has the option to go through a loop, etc., you should have at least 1 comment. Clearly, you made some type of decision about how the code should operate, and now is the perfect opportunity to tell people why you made that decision. It’s important not just for developers who aren’t you that may end up looking at your code, but to you if you end up having to go back to it and find yourself wondering why you put that random block of code there. Any point where the control flow of the code can branch is a point where somebody made some kind of design decision about how the code should work. It doesn’t matter if the developer made the decision, a product manager made the decision, a customer dictated it, whatever. The point is, there’s a design decision, business rule, or development decision that is important enough to be put into the code, therefore it’s important enough to be explained in a comment.

The point is, a decision about how the code should behave under what circumstances, and that decision is now in green on black in code. That is precisely the kind of thing that comments are supposed to capture for reference. Every time people talk about the point of comments, or how do you write comments, 1 of the first things you hear is to write comments about why the code is doing what it’s doing, not what it’s doing (if you’re writing code correctly we shouldn’t need help for that). Branching points are where we need that information most.

IV. Thoust cleveriness is worthy of being documented for posterity

While anywhere control flow can change makes for the ideal place to put comments, sometimes there’s something in the code that’s so wonky, it needs special attention, and documentation. I’m talking about the lines of code that you don’t totally know why they work, but they fixed that 1 weird bug that you spent a week trying to figure out and never totally understood, but you know this little piece of doesn’t-seem-to-make-any-sense code fixes it, and that if you take it away code starts breaking again. Modesty doesn’t apply here kids, comment the crap out it!

These are the lines of code that somebody, somewhere along the line, is going to read, and then they’re going to think that you were smoking crack. After speculating about your drug-induced coding frenzies, they’re going to “fix” that little piece of cleverness/I-don’t-know-why-but-it-fixes-the-problems-so-I’m-going-to-leave-it-alone-code, and in so doing they’re going to unleash hell upon the application. In fact, if you don’t comment such incredible lines of code, you can just go ahead and jot that down as a prophecy right now.

It’s not just hard-to-understand-but-vitally-important lines of code that need comments (although they really comments, just so other people know to leave them alone). Any piece of code that gives you some extensibility or performance benefit that isn’t immediately understandable should be commented as well. Part of this is so people can know exactly what you did and how it works, part of it is to prevent people from being tempted to delete and refactor it with something else that’s long, messy, and may not even work as well as what you put in. Plus, this all goes back to 1 of my original points about answering predictable questions before they’re asked, all because you took a couple of minutes to explain what you were doing before someone interrupted you when you were just about to come up with another awesome, clever, elegant piece of code.

V. Thou shalt not repeat the line of code you’re commenting

This is usually the first thing people say when discussing comments, but I thought the other 4 things needed to be said first before we got to this point. Writing comments isn’t enough, they need to be good comments too. Commandments 3 and 4 beat around this bush, but now I’m saying it outright. Yes, your code should be self-documenting, but that only applies to what your code is doing, it doesn’t tell anyone why you did it. If what you’re doing is counter-intuitive, it doesn’t tell anyone why the intuitive idea didn’t work in that instance.

Telling other developers why you did what you did makes the code more understandable, which is the whole point behind readability. It doesn’t matter how pretty your code looks, if I can’t understand the design decisions that went into it, or the major decisions that made the code what it is, I’m going to be lost when I try to work on it. And lost developers are liable to add bugs through not realizing just what kind of fire they’re playing with. The best case scenario is that QA finds these bugs during testing, forcing the ignorant developer to fix them and hopefully have everything working by the time things go to production, albeit after much longer than initially anticipated. The other alternative is that nobody realizes the clock is ticking on these bugs, and they make it into production, forcing the original developer (the ***hole who couldn’t be bothered to write comments in the first place) to fix them, and wonder just what the hell the other person was thinking. This just breeds aggravation and animosity, emotions that could have been avoided with good, and explanative, comments in the first place. So comment about your code, and if you do it for no other reason, do it for developer peace.

VI. Thou shalt add comments where sinners have left them

Comments don’t belong with just your code, although that’s a good place to start. Comments really belong with all code, even that written by other people. Whenever feasible, you should be adding comments to code written by other people. My general philosophy is to add comments to any method I end up working with. While commenting the entire class would be even nicer, odds are you’re busy, and need to trade off thoroughness for keeping things moving. The important thing to remember is that all the hassles you encountered trying to understand what the logic behind code was will still be there after you check it in. That is, unless you fix the issue by adding comments once you finally understand the code.

For all you know, you could be the next developer to have to deal with that code…3 months from now. You’re never going to remember all the stuff you figured out from that 1 thing you worked on months before. Leave yourself some notes to help get you back in the right mindset quicker. Even if you’re not the next person to deal with the code, you should always be leaving the code better than you found it, and that extends beyond whatever bug you’re fixing of feature you’re adding. The code should be more readable, more maintainable, and generally more friendly on developers after you check it back in than it was when you checked it out. Comments help developers read and understand you’re code better, not to mention understand the reasons why people did what they did before. Not everyone comments their code yet, so it’s up to those of us who do to help try to clean up behind them. Think of it like picking up random pieces of litter you come across during your day-to-day life. It’s not a lot each time your do it, but the more people do it in the more places, the better a place the world is.

VII. Thou shalt remove old code, not comment it out

While I’m clearly a huge proponent of leaving notes throughout the code to help other developers understand what was done and why, I am not a fan of leaving old code in the comments to illustrate. Old commented-out code does nothing to make the code more readable or understandable, nor does it do anything to explain why the code is the way it is now. Commented-out code introduces confusion, which is the opposite of the whole point of having comments. Was that code commented out during development and debugging? Does the code even work? Why was it ever there? Why are we keeping it?

If the code is useless, you should be removing it, not throwing some comments around it and pretending it’s not there. Don’t keep it sitting around so you can look it back up later, that’s the point of having your code under version control. You stopped using that code for a reason, and it’s not going to appreciate your sentimentality, delete it and move on. This helps condition developers to view comments as providing useful and relevant information, not a bunch of useless old code that has to be scrolled past so they can see the part of the codebase that’s actually useful. Remember, comments should be doing something to make the code easier to understand, not harder, commenting out code and just leaving it there is not why God gave us comments, so stop abusing them.

VIII. Thou shalt maintain the comments as well as the code

All of this advice about comments is great, the first time the comments are being written. However, code changes over time, and if the comments don’t change with it, they’ll become even worse than commented-out code. People who look at old comments that no longer apply will be left wondering just what the heck the code is supposed to do. Commenting is too important to just abandon comments as soon as they’re written. They need to be updated to reflect the current code in your codebase.

Remember, what comments are designed to do is help enlighten people about the code, why it is the way it is, the business rules behind it, the design decisions that went into, etc. You need to keep people enlightened on the code that’s in the codebase right now. That means if the code changes, the comments associated with it have to change too. Comments are a form of documentation, and a very important form of documentation for developers, second only to the code itself, and you need to treat them as such. If you keep the comments accurate and up-to-date, developers can understand just what the code was supposed to do. Nobody would be OK with official user documentation being outdated and unmaintained, so stop letting vital developer documentation gather cobwebs.

IX. Thou shalt treat comments as part of thoust coding standards

Obviously, doing comments right means taking comments seriously. And if you really want comments taken seriously, then making good commenting practices part of the coding standards sends that message loud and clear. Making good commenting a requirement means other developers are checking comments along with the code during peer reviews. Code that is missing comments or has bad comments is being sent back to be fixed. Enforcing things like good commenting practices demonstrates a commitment to code quality, readability, and maintainability. It encourages people to think about their code, what they’re trying to do, and ensures that people understand what they’re doing to the codebase before they check it in.

Making comments part of your coding standards gets people in the habit of making sure their code is documented and that the comments are up-to-date. And since good comments are part of maintaining good quality, it gets developers into the habit of thinking about all the little things that contribute to code quality or make life easier on the developers.

X. Thou shalt spread the good word about commenting

Good commenting requires participation from everybody, not just a handful of developers who happen to feel passionately about the issue. The benefits to good commenting are drastically magnified when everyone comments. For that to happen though, everyone needs to be commenting, which is a drastically far cry from the case today. Therefore, commenting needs evangelists. Admittedly, this is the commandment I break the most. After all, I’m busy with my own work, my co-workers are busy with their own work, and for all I know, I’m the only one who will ever benefit from comments.

Right now, the best advice I can offer is to ask for comments during code reviews, or really just any time you’re looking at something that needs comments. Another thing I can think of is to tell people they should leave comments any time they’re working on something that clearly took some thought on their part when it came to figuring out what and how to solve the problem. You should also tell other developers you’re going to add comments with explanations once you get code explained in person that could have been covered in comments. Lastly, make sure the comments you’re putting into the code are good, useful, and thorough. The better the comments other developers see, the more inclined they’ll be to keep them up when maintaining your code.

Look, writing good comments is an important component to writing good code. It may not seem that way as you’re actually working on code, but taking the time to think about your comments and make them good (and present!) now can make maintenance, and event future development, much easier. Most importantly of all, it’s part of doing software development right. Make your life, and the lives of your fellow developers easier, your code readability higher, and your code more understandable, write comments. Write comments that explain the logic behind your decision-making process. Write comments that tell developers what your methods are doing, and the important things people should know when calling your code. Write comments that make the cleverest pieces of your code something easy for someone else to follow. It’s little things like these that make the difference between being a developer, and being a good developer.

 Posted by at 2:54 AM