File APIs for Java Developers
Manipulate DOC, XLS, PPT, PDF and many others from your application.
http://aspose.com/file-tools
The moose likes Cattle Drive and the fly likes Question on good code Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login
JavaRanch » Java Forums » This Site » Cattle Drive
Bookmark "Question on good code" Watch "Question on good code" New topic
Author

Question on good code

Jack Moore Iii
Ranch Hand

Joined: Jun 07, 2012
Posts: 76
When people say good code, in relation to assignments like this, are they talking about turning a hello world program into 50-100 lines of JavaDocs and comments? A huge /* */ for every method, a big long comment for every variable, loop, switch, cast, declaration, etc? I'm a big fan of understanding how to program and getting things to work, but I've never been that anal about commenting...
Paul Clapham
Bartender

Joined: Oct 14, 2005
Posts: 18716
    
    8

I don't know what the Cattle Drive wants from you, and in general the rule is, if somebody in charge of you says you have to write comments in such-and-such a way, then write comments in that way.

However my opinion is, don't write comments blindly. If you have a getter method named "getFlavour" then saying that the method "gets the flavour" from the object just looks silly. And if you wrote your code in a self-documenting way -- e.g. you called the variable containing the customer's name "customerName" -- then it isn't necessary to put in comments which state the obvious.

Likewise it isn't necessary to put in code comments which state the obvious. If you have code which divides a number by two and assigns the result to a variable, there's no need to say so. On the other hand if you have code which calculates the monthly payment on a loan, you should say so. In other words explaining WHY or WHAT FOR is preferable to explaining HOW. And if you wrote some code which does things in a strange or non-standard way, explain that you did that and say why you did it.

The other reason why you SHOULDN'T write comments is this: later you're going to come back and change the code, and it's possible that you will not get around to changing the comments to match the change. At this point you have a comment which is a lie, and that's no better than no comment at all. Perhaps it's worse, since an incorrect comment could mislead the poor schmuck who is trying to find the bug.

And speaking of that poor schmuck: the purpose of comments is to help somebody to understand your code. That somebody most likely doesn't understand your code nearly as well as you did when you wrote it, and the somebody might even be you six months later. So that's why you SHOULD write comments. Just don't waste the poor schmuck's time with pointless commentary.
Katrina Owen
Sheriff

Joined: Nov 03, 2006
Posts: 1364
    
  17
We optimize for short, simple, and readable, where readable wins over short.

With respect to comments, we will very, very rarely expect a comment. For the most part if you have a comment, we will ask you to choose more appropriate variable names.
The only time a comment is expected is if the code contains some context that cannot be encoded into the code itself.

We work a lot on choosing good variable names, as naming things is considered one of the hard problems in computer science.

This is one of those "it depends" things, but examples of typical names that will get nitpicked are a name that tells us where the variable comes from or how it is derived, but not what role it plays in the program, or a name that contains a suffix or prefix that does not provide a meaningful distinction. There are many others.
Katrina Owen
Sheriff

Joined: Nov 03, 2006
Posts: 1364
    
  17
We've discussed naming things a couple times:

Intention Revealing Names
Variable Naming
 
I agree. Here's the link: http://aspose.com/file-tools
 
subject: Question on good code