Although this is primarily a post centered around Programming but because I happen to be a student of Java, I shall be talking about code commenting in Java.
We started with Java posts last year with the post titled What is the difference between JDK and JRE? . As is clear from the title of the post, this particular blogpost described the difference between JDK and JRE and then in the series of posts like Write a Java Application without a main() method which explained the trick of writing a program without a main method ( though this certainly is not useful from a production perspective) and How do I declare a constant in Java which explained the process of declaring a constant in Java.
Later during the last year, we also learnt about the lifecycle of a Java program in the post Java: Lifecycle of a Java Program. What can a programming language be without support for Database operation and that is when we talked about JDBC Drivers in the post JDBC Drivers:What are they?.
Lastly, we even talked about Polymorphism in Java in the posts titled Polymorphism in Java : Part 1 and Polymorphism in Java : Part 2. And now, the time is ripe to talk about Comments in Java; The most important yet often ignored element of coding.
There are three types of comments in Java:
– single line comments start with //, and end when the line ends
– multi line comments start with /* and end with */
– JavaDoc comments start with /** and end with /*
Now this was about How to comment the code in Java. Lets now try shifting our focus a little towards the Why part of the topic… Why to comment your code?
Stan James, a Javaranch forum member has a view against commenting the code. He says
If you’re tempted to put a comment on a method or in the middle of a method to explain what the next few lines do, stop and make the code tell the story. Small methods with great names make all the difference.
Many of the developers and other coding engineers i know don’t agree with Stan. Their point against this argument, is, in Programming Comments are not only for explaining what the code is all about but also to make it more understandable, more approachable and make the reader of the code understand the reason for applying the particular logic in the code.
Kelvin, another JavaRanch forum member says
Comments aren’t just for explaining how code works, though. I use comments mainly to explain why I decided to implement a feature or algorithm a particular way. This is especially useful in situations where there’s an “obvious” way of doing things that actually turns out to have serious but subtle flaws. If I don’t put a comment next to the code in question, it’s quite possible that some future zealous but inexperienced programmer will attempt to “optimize” my code using the flawed implementation approach.
I particularly like this post from J.Timothy King’s blog where he talks about Bad Writing and Poor Programming skills. Timothy in his blog gives an example
Here’s a snippet of code from a well funded, closed-source system that has been deployed in production for years. I’ve tweaked it a little, but only to make it more readable. This codebase gave me a migrane and almost made me lose my temper. (Seriously, it did.) I also know who wrote this. He was a senior developer, who had been programming at least as long as I. But as it turns out, in conversation, I never knew what he was talking about without questioning him in detail. Do communication skills reflect programming skills?
float _x = abs(x – deviceInfo->position.x) / scale;
int directionCode;
if (0 < _x && x != deviceInfo->position.x) {
if (0 > x – deviceInfo->position.x) {
directionCode = 0×04 /*left*/;
} else if (0 < x – deviceInfo->position.x) {
directionCode = 0×02 /*right*/;
}
}
This is equivalent to the following, more readable code. Except the following actually initializes directionCode in all cases. (The above code has a bug, which the following code fixes.)
static const int DIRECTIONCODE_RIGHT = 0x02;
static const int DIRECTIONCODE_LEFT = 0x04;
static const int DIRECTIONCODE_NONE = 0x00;
int oldX = deviceInfo->position.x;
int directionCode
= (x > oldX)? DIRECTIONCODE_RIGHT
: (x < oldX)? DIRECTIONCODE_LEFT
: DIRECTIONCODE_NONE;
Note that more comments does not mean more readable code. It didn’t in this example. The comments in the snippet above (if you even noticed them) only clutter the code even more. Sometimes fewer comments makes for more readable code. Especially if it forces you to use meaningful symbol names instead.
Therefore we can conclude that Comments can certainly never be replaced by code alone, however, the best approach seems to be the one wherein we ( as programmers) go back and refactor our code and then again, if the need be, add comments.
Do share your opinion on this and also your style of commenting.
Do stay tuned to Technofriends for more, one of the best ways of doing so is by subscribing to our feeds. You can subscribe to Technofriends feed by clicking here.
Cheers
Vaibhav
Filed under: How-To, Java, Technology, Tips | Tagged: coding, geeks | Leave a comment »
Technofriends 