September 20, 2014
Hot Topics:
RSS RSS feed Download our iPhone app

Good Java Style, Revisited

  • April 16, 2008
  • By Rob Lybarger
  • Send Email »
  • More Articles »

Other Considerations

A good code editor tool will visually hint to the matching parenthesis or brace when the cursor is to one side of it. Also, you may be able to double-click on (or to one side of) a brace to have the entire inner contents selected or highlighted in some way. This does a lot to help keep track of which braces match in long, highly-nested methods (although good code style says methods shouldn't get that hairy in the first place). However, you may see code that adopts the style of commenting the closing brace to inform you of its matching condition type. (When a condition block is so long that the opening and closing brace are no longer on the same screen, this isn't an entirely bad idea... although a block of that length is.)

for (condition)
{
   ... statements
   ... lots of statements
   ... pages worth of statements
} // end for

Comments

Comments in Java come in the inline style and the block style. (And when you're writing javadoc material, you have to use a slight variant of the block style.) Although I am personally as apt to use an inline comment, notably to describe a variable's purpose in life, there is one minor drawback to them that is worth mentioning: forum posts. A lot of forums allow someone to post in source code with the understanding the petitioner will attempt some level of diligence to make sure things are legible. Invariably, new people get it wrong, or the site behaves differently than they expect. Suddenly the line breaks disappear, and all those inline comments turn the post into a useless mess because there is no way left to know where they end. So the lesson here is that, if you post a question to a forum, be careful about inline comment markers, and double-check (preview and re-edit) before committing the question to the forum.

As to comment style in general, applying a javadoc comment to the class and to all publicly visible methods (if not all methods all the time) is preferred. You will usually be forgiven if your description has some misspellings in it. You might even be forgiven if the javadoc is a little bit out of date. But you will be cursed to your death to omit a javadoc entirely, when someone else has to follow along and maintain some non-obvious method or class. (Remember: No two people have the exact same definitions for "obvious.") On the other hand, be brief with what you do provide in the comments. Reiterating the name of the method just to use regular English words and capitalization is pointless, so try to add a sentence or two beyond what you think the method or class name implies.

Also, note that Sun has a complete writeup on their recommendations for what you put into a Javadoc comment and how it should be verbally formatted.

Declaration Mechanics

Variable Declaration Locations

Class-level variables, be they static or instance, should be placed toward the top of the source code file. This is largely a matter of convention for Java, and it inherits from its roots in C-style languages that effectively require variables to be declared in this fashion. Although Java is happy to allow you to intersperse your getters, setters, and instance variables throughout the class code, other experienced developers will have a natural (and in honesty, an unconscious) expectation that all such variables are declared at the top of the file.

On the other hand, the convention for method-level variables is that they are declared and initialized as they are needed. (This is a stronger break from early C-style languages that required all function-level variables to be declared at the beginning of the function before any actual statements were present.) The justification for this difference between class-level and method-level variables is that you really should not have that many class-level variables in the first place, and that they tend to be used throughout many methods in the class; however, the method-level variables tend to have more direct and limited roles, making on-the-fly declarations less taxing to a fellow code-reader.

Naming and Capitalization

The exact appearance of a class and variable names is again a matter that largely follows an established convention. Types (classes, interfaces, and so forth) should be in lowercase letters, with no spaces between words, but with the first letter of each word (including the first word) using an uppercase letter: SomethingLikeThis. (This form is often referred to as "camel case" for, perhaps, obvious reasons.)

Non-constant variables should likewise be in lowercase letters, with no spaces between words, but with words after the first word starting with an uppercase letter: somethingLikeThis. (The key difference is that classes start with a capital letter; variables do not. Otherwise, the appearance is very similar.)

A "constant" (which in Java is a variable with the 'final' keyword, and which is usually also 'static') is named in fully uppercase letters, with word separated by underscore characters: SOMETHING_LIKE_THIS. Experienced fellow coders will again have a natural and unconscious assumption that a token which looks like that in source code represents a final variable.

class MyNeatClass
{
   private int currentValue;
   public static final String SOME_STRING_CONSTANT = "Blah blah";
   ...
   public void doSomething()
   {
      ...other statements...
      ...
      int count=0;
      for (loop condition)
      {
         if (branch condition)
         {
            count++;
         }
      }
      ...
   }
}




Page 3 of 4



Comment and Contribute

 


(Maximum characters: 1200). You have characters left.

 

 


Sitemap | Contact Us

Rocket Fuel