Blog

Time to pass along another gem from our friends out at DZone. Alberto Gutierrez brings us the 10 commandments for creating good code. While I encourage you to follow the link to read all of the commandments, there are a couple that I feel deserve special mention.

3.- Use good names for your classes, methods and variables.
There is nothing nicer than using some other developer code and not having to read its documentation because the names of the classes and the methods are telling us everything, so, make everyone’s life easier and take this approach, expend always a few seconds before naming any element in your code.

I couldn’t agree more. Well written code should be able to be read like a book. The names of the classes, methods, and variables themselves should tell me pretty much what they do without having to refer to the documentation. If I see an isAdmin() method on a User object, that is a good method name and pretty self explanatory. But what does this method do?
public String admin (int i) {...}
Yup, that is an actual method I have run across in a fairly popular library. And to be honest, I still don’t know exactly what it does…

8.- Comments are evil.
This particular one is a bit controversial, most of us were taught that comments are good, and actually it’s better to have a comment in an obscure piece of code than just having the code by itself, what this point means is that: even better than having a comment for an obscure piece of code is not to have that code at all, just refactor it until is a nice and readable piece of code. [EDIT] Please read this other post for a better explanation of what “comments are evil” means.

Here I have to respectfully disagree… kind of. I understand the gist of what he is saying - poorly written code is not made better by adding comments. It is better to refactor the code so that it doesn’t need comments. For instance, let’s assume we have a method that processes a collection of items, and that processing has several steps. Instead of commenting where each step begins and ends, refactor each step into its own, well named method, and call the secondary methods from the processing method. But it isn’t the comments that are evil, it is the misuse of comments that are evil. Comments themselves can still serve a very good purpose. Clarifying initialization parameters, adding context to test methods, identifying why something was deprecated, javadocs, etc. As engineers, we tend to be a reactionary group. We have all seen developers use comments as a crutch to support poorly written code. So the (over)reaction seems to be the admonishment of all comments. While we can certainly scale back the amount of comments that are used, and educate our peers on when they SHOULDN’T be used, to claim that all comments are evil is way too absolute for me.

Those were the two I wanted to touch base on. Feel free to add comments, and again, please check out Alberto’s blog for the other eight.