October 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 »

The recent appearance of the Java "enum" type adds a relatively new twist into the works. An enum behaves like both a class and a listing of named value constants. The capitalization of the enum itself follows that for classes and interfaces (they are, after all, "types"). The precise convention for the named value constants inside the enum is a little less clear. Even though the constant-variable appearance is natural on the one hand (and is the form used in the enums that are present in the Java API documentation) an alternate tends to use class-style capitalization instead. I believe the reason for this lies in the nature of their "toString" output: they display a String-type value that exactly matches their source-code representation, and the class-style capitalization is more user-friendly than the final-variable-style capitalization. Of course, the class-like nature of the enum means this default behavior can be overridden as needed, so the "constant variable" form should probably be used.

enum MyFirstEnum
{
   ALPHA,
   BETA,
   GAMMA,
   DELTA;
}

If the enum type is still new to you (it was introduced in 1.5) you should read this page that discusses why enums are useful and how to take advantage of their OO-like capabilities.

Source File Layout Mechanics

The exact ordering of the sections of material that compose a Java source code file follows a fairly standard convention. (The compiler also makes a couple of mandates of its own.) The accepted ordering of material is generally as follows:

  • Your team's or company's comment header, if any
  • The package declaration statement
  • Import statements
  • The declaration for the type, an "extends" clause (if any), and an "implements" clause (if any)
  • Class-level variables (as appropriate)
  • Class methods
  • Inner class declarations, if any, using this same pattern

The team or company comment header tends to be some standardized copyright statement. This is a standard comment and can of course be omitted. The package statement can be omitted, but doing so can cause unexpected headaches. (Certain frameworks and toolsets may in fact require that the code it interacts with is in a package, but such a requirement is not directly imposed by the Java compiler itself. Still, an explicit package is highly encouraged, even if it is something as simple as "dummy", "test", or just your initials.) If you do provide a package statement, it must occur as the first non-comment statement in the file, preceding any import statement.

Import statements should generally be grouped in some fashion, and the "*" import forms are discouraged for anything bigger than a quick prototype. (Using "*" import forms begs to introduce a namespace clash, or worse, to accidentally have the compiler resolve an unqualified class name against the wrong fully-resolved class.) Grouping might be that you list all the core Java API classes together (and if possible, in alphabetical order), other third-party classes together in another group, and your own application's classes together in yet another group. (Adding blank lines between these groups is also encouraged. IDEs tend to do this if you allow them to format your source code.)

Types (classes, interfaces, and so on) and methods should include a Javadoc-style comment wherever possible. (Note that the general behavior of the javadoc utility itself is that non-Javadoc'ed entities are still listed in the generated output with empty descriptions and explanations.) Public-facing types usually benefit from someone taking the effort to describe a few usage examples in the top-level Javadoc comment for the type itself; certain the listing of assumptions, corner cases, and the like should be captured in some form.

The antecedent of this document went so far as to recommend a strict ordering for each type of class-level variable. I have not personally seen this level of detail demonstrated or heard many arguments made to bolster the case, so I am personally of the opinion that related class-level variables should be basically grouped together (for example, all the private variables that back the public getter and setter methods in one group, constants in another group, and so forth) but that the overridding principle is that these variables are easy to find, clearly labelled, and commented as necessary.

The antecedent also expressed that the "main" method should be listed last, but gave no clear rationale for this. My personal opinion is that a main method is either short enough to include right off the top, or sufficiently long enough that it should exist almost entirely in a separate class in a separate file. (Historically, early C-style languages had requirements that effectively caused the implementation of the main method to be last in the file, but Java suffers no such effects.)

Conclusion

Knowing the various rules and conventions that compose a "good Java style" goes a long way to reducing the mental noise that you and your fellow team members need to battle through to get the job done. Paraphrasing a joke I once heard, one should code as though they know the person that will follow along behind them knows where they live and is also an axe-wielding maniac. (And based on people I have worked with, this sometimes seems closer to the truth than you might think.) Writing better code can start with writing code that is styled and presented better. This will in turn lead code that analyzed and debugged more easily, and this in turn will lead to code that runs better.

About the Author

Rob Lybarger is a software guy (and a degreed aerospace engineer) in the Houston, TX area who has been using Java for nearly ten years. He has used various versions of Windows, various distributions of Linux, but loves Mac OS X. He likes exploring new techniques and new approaches to organizing and wiring applications, and loves to let the computer do as much work for him as possible.





Page 4 of 4



Comment and Contribute

 


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

 

 


Sitemap | Contact Us

Rocket Fuel