Thursday, June 15, 2006

Clean, Clear and Concise Code - part I

I can’t remember a programming assignment in school where somewhere in the list of requirements there wasn’t a point made about clean, clear, concise and commented code. That isn’t to say that sometimes you have to write some pretty large functions with multiple levels of nesting conditionals, but I would expect that there should be some hints to a future reader (possibly yourself) as to what you were thinking when you wrote the code. I think that more often than not, it seems that programmers get under a time crunch, and say things like “I’ll document later”, or “My code is so straightforward, no one will need comments to navigate it”. Maybe you are one of those types that is so brilliant you can remember every line of code you wrote and why you wrote it, but chances are, you aren’t and even if you can, what about the dude who will be picking up your code in a month or ten years, what then? Will that poor junior developer be able to quickly come up to speed with your code, or will he/she spend hours trying to figure out how to channel your chi to know what you were thinking when you wrote that triskaideca-nested(13) if then block, and what exactly it accomplishes.

Being the most junior of developers on a team, I am seeing a lot of different code, written by many different developers. Some of the code is relatively new; some of it may as well be archaic. Some of the developers took the time to carefully comment, others didn’t. Some observed a very consistent naming and formatting scheme, some code has been through some code has been through so many hands that it doesn’t have _a_ style.

I suppose that my point this evening is that I can sympathize with the need to get a project done, and I understand that reading code that you didn’t write is really the last thing that any developer really wants to do. Further, writing good code in a project that isn’t “yours” may also present you with a challenge, after all, if it isn’t your project why should you care what the code looks like? But you see, this is how the problem starts. Maybe you added 75 lines, that’s innocent enough isn’t it? Then again, the next developer thought the same thing, and before you know it, you’ve had hands all over the code, and it really is an unmitigated mess because no one ever bothered to think about maintainability in the long run. All the while, this code is doing important work, and it has been tried and true. It may be harder than hell to read, but it does the job. Perhaps you, sick of looking at that code would go to your manager and ask if you could just re-write the whole thing, but does that really solve the issue at its root?

Every developer that actually believes he/she is one would agree that the answer is a resounding no. The root of the issue is writing clean, clear, concise and commented code. It really is easier said than done, because writing code in this way requires some extra effort on the part of the programmer. It isn’t simply a matter of what gets the job done now, but also what makes for easy expansion in the future, is presented in the most simple and beautiful way, and will be understandable to anyone with reasonable coding skills sometime in the future.

I’ll motivate with a story from school. At the end of my sophomore year in school, my friends and I were taking a computer systems course. It wasn’t a full OS course, as we were just addressing small pieces as isolated units, but one of the most interesting assignments was to write malloc and free functions. Anyone who has gone down that road can attest to the fact that systems code of that nature is some of the most interesting, and non trivial code that a student can write as part of a classroom curriculum. Anyhow, our group of friends split into teams, and got to work. One of the guys was really into the project and coded up a skeleton malloc function and handed it over to his partner to complete the assignment. There was only one problem. This code written in C had no comments, and the variable names were un-intelligible to any person that wasn’t the programmer. One letter variable names, all pointers- in short a nightmare to anyone trying to figure out what was going on. As it turned out, my two friends had to be together in the same room to finish the project because the one who wrote the code had to be in the same room for the other friend to understand what he had written. Needless to say, we gave him an endless amount of torment over his coding style. He is extremely bright, gets amazing grades, works hard, and knows his code, but it was just impossible to read.

Fast forward a year and we are in a compilers course. This time it is just me and my super bright friend. We are working on the compiler together, but something changed this time around. He decided to comment the code, and use variable names that were intelligible. I don’t know what he would say about the experience, but I will still thank him for making it possible for me to understand what he was doing in the code. The final phase of the compiler the code-generator along with a register-allocator was some of the most complex code that we had ever written/seen, it was really cool at the end of the semester to see it actually working, and I don’t think I would have been able to do my part nearly as easily had my friend not taken the time to clearly document and write his code.

Yes, in the commercial world there is pressure to ship the product. Often the desired due date is yesterday, but I still do not believe that this is a ticket to write bad code. Every programmer knows what “spaghetti code” is, and at one time or another we have all contributed to the pasta bowl, but maybe now it is time to repent.


Anonymous said...


Joe said...

Gee thanks! Not only are you anonymous, but you didn't have anything to tell me about how it could have been not "bo-ring"

Some comments are better than no comments right?