Sunday, September 13, 2009

Care to Comment?

I'm not sure the importance of formatting and comments are really beaten into your head as you go through computer science classes. In beginning classes, there isn't a whole lot of need for formatting and comments. Most assignments are typically "correct" or "incorrect". Of course, if the output of your assignment is incorrect, you may still hope for some partial credit. Then a poor TA has to read your code and decide what your grade should be based on what they could understand. In later classes, professors kindly ask that your code be commented because they need to read it. That's the point where your code is no longer some trivial assignment but more of a project.

And readability in large projects is important because they tend to have many people working on the same code base. One person may be using some methods that another has written. People who maintain the project may be working on code that someone else had written in order to fix bugs found after release. And even if there aren't multiple people working on a project, readability helps when you look at older code. It's kind of interesting to go back and look at old code that you had written. You probably don't even remember writing it or what it does. But if your code is readable, you quickly get up to speed with what you had written.

I think we're fairly good with formatting since good style is taught as you learn how to code. But I don't think we're really taught how to write good comments. Instructors and professors only ask that you don't write something that is blatantly obvious, like "this sets x to 10" or "loop from 0 to 10". And despite having taken 413 a few years ago, I admit that the formatting and comments in my Java files aren't really up to snuff (the style and comments in my C files aren't all that great either. Maybe I need this book as well). So when we were given the chance to go back and clean up our Robocode files, I spent the most time adding in Javadocs for my classes. I also did some refactoring by moving often used methods to a separate robot file ( and had the simple robots inherit from that robot. Finally, I formatted each of my source code files using an Eclipse formatting template.

What annoys me about coding style is that there tends to be no real standard across all programming languages. For example, in the Elements of Java Style, rule 13 states "Capitalize only the first letter in acronyms". If only Apple used that rule in their Objective C code, then I wouldn't consider using the caps lock key to type NSHTTPURLResponse every time I want to process a request from a web server. Then again, I understand why C programming style generally is the way it is with terse variable names (because of memory constraints). And some languages lend themselves to different styles and conventions. When in doubt, rule #1 in EJS should stand across all languages: "Adhere to the style of the original".

Click here to download my new and more readable Robocode code.

No comments:

Post a Comment