The Navy Java Style Guide
is essentially intented for the students of the N.P.S. School (some recommandations are not exportable outside the school). It is available on our site as a revisited mirror (original author's agreement pending) of http://vislab-www.nps.navy.mil/~java/course/styleguide.html (Last Updated 8 JUL96) by the Naval Postgraduate School (java@nps.navy.mil(JAVAPage)). The Java style guide is mirrored from the NPS CS C++ style guide used and developed by John Falby.
Unfortunately, some features available only in C++ (enum, typedef, cout, etc) were NOT removed! So, handle this text with care!!!

  1. General - section of the Java Style Guide of the NPS

  2. Visual Layout - section of the Java Style Guide of the NPS

  3. You should format your program making use of page boundaries and blank lines to separate code groups, functions and groups of logically related blocks. As a general guideline, no method or sub-class should be longer than one page, and formatting should ensure that it prints out on one page. There are exceptions, such as breaking a method up to fit a page may be poor design and worse than writing one that is too long.
    (quoted from Visual Layout - section of the Java Style Guide of the NPS)

  4. Output from a program should be both informative and professionaly formatted. A person reading the output should be able to determine for himself whether he believes that the program works reasonably, without knowing the internal details of the program.
    (quoted from Visual Layout - section of the Java Style Guide of the NPS)

  5. A printed page should be no more than 72 columns and 60 lines (12 point font).
    (quoted from Visual Layout - section of the Java Style Guide of the NPS)

  6. Indentation and Whitespace - section of the Java Style Guide of the NPS

  7. Indentation is used to highlight the block structure of the code and must therefore be used consistently. The proper use of white space and indentation makes the structure of the program evident from the layout of the code. You must use proper indentation, which in this class is three spaces. We strongly recommend the use of spaces vice tabs. Printers and other users might have different tab spacing.
    (quoted from Indentation and Whitespace - section of the Java Style Guide of the NPS)

  8. Vertical whitespace (i.e. blank lines) helps set off blocks of code and can increase readability of the code. Code with no vertical whitespace becomes very busy and hard to follow.
    (quoted from Indentation and Whitespace - section of the Java Style Guide of the NPS)

  9. A method of class name and its associated braces are aligned in the left most column, and all other code is indented from there. The closing brace will always be on a line by itself and aligned with the beginning of the block opening brace. Braces used to block code will be indented consistently with the rest of the code.
    (quoted from Indentation and Whitespace - section of the Java Style Guide of the NPS)

  10. Comments will be indented consistently with the block of code they describe.
    (quoted from Indentation and Whitespace - section of the Java Style Guide of the NPS)

  11. One way to improve the readability of a method is to paragraph it, or in other words indent your code within the scope of a code block. Any code within braces, the { and } characters, forms a block. The basic idea is that the code of within a block should be uniformly indented one unit 1 . To ensure consistency, start your method and class declarations in column 1 (NPS , 1996).
    (see the NPS' Navy Java Style Guide)
    (quoted from 2.4 TECHNIQUES FOR WRITING CLEAN CODE 2.4.2 Paragraph Your Code in AmbySoft Inc. Java Coding Standards by Scott W. Ambler, v. July 10, 1997, p. 10 )


  12. Use Whitespace in Your Code
    A few blank lines, called whitespace, added to your Java code can help to make it much more readable by breaking it up into small, easy-to-digest sections (NPS , 1996; Ambler, 1997).
    (see the NPS' Navy Java Style Guide)
    The Vision 2000 team (1996) (see The NASA Coding Standards for C, C++, and Java, Vision 2000) suggests using a single blank line to separate logical groups of code, such as control structures, with two blank lines to separate method definitions. Without whitespace is very difficult to read and to understand.
    (quoted from 2.4 TECHNIQUES FOR WRITING CLEAN CODE 2.4.3 Use Whitespace in Your Code in AmbySoft Inc. Java Coding Standards by Scott W. Ambler, v. July 10, 1997, p. 11 )

  13. Control Structures - section of the Java Style Guide of the NPS

  14. The use of braces is required for all control structures.
    quoted from Control Structures - section of the Java Style Guide of the NPS)

  15. Avoid the use of continue and break in loops.
    quoted from Control Structures - section of the Java Style Guide of the NPS)

  16. Always use a default case in switch statements. Use a break to end all cases (including default) in a switch statement.
    quoted from Control Structures - section of the Java Style Guide of the NPS)

  17. The use of //end if, //end while, and //end switch comments after the corresponding ending right brace is optional but highly recommended.
    quoted from Control Structures - section of the Java Style Guide of the NPS)

  18. Naming - section of the Java Style Guide of the NPS

  19. Variables will have meaningful names/identifiers. This must be balanced against using names which are too long, which can obscure the code. (A variable name greater than around fifteen characters is approaching the "too long" limit.) The only exception to this is for loop iteration counters. These special case variables can have names like "ix", "jx", etc. Single letter variables or constants should not be used. The exception is when it is a common practice to identify something with a single letter. An example of this is the coordinate axis (X, Y, and Z).
    quoted from Naming - section of the Java Style Guide of the NPS)

  20. An identifier consisting of multiple names shall have each name set off. This is done by making the first letter of each name part capital (e.g. redCarColor), or by using underscores between parts (e.g. red_car_color), but not both (e.g. red_Car_Color).
    quoted from Naming - section of the Java Style Guide of the NPS)

  21. Do not use the letter `l' (lower case `L'), `o', or `O' in names unless they are part of normal words. This is to avoid confusion with the numbers 1 and 0.
    quoted from Naming - section of the Java Style Guide of the NPS)

  22. All normal identifier names must be in lower or mixed case. (method, typedef, variable names, class, struct, union, and enum tag names)
    quoted from Naming - section of the Java Style Guide of the NPS)

  23. Enum elements must be in all CAPS, but instantiations can be in lowercase.
    quoted from Naming - section of the Java Style Guide of the NPS)

  24. Names with a leading or trailing underscore are usually reserved for system purposes, and may not be used for any user-created names with the exception of preprocessor defines.
    quoted from Naming - section of the Java Style Guide of the NPS)

  25. Avoid names that differ only in case, look similar, or differ only slightly.
    quoted from Naming - section of the Java Style Guide of the NPS)

  26. Avoid redefining names of standard identifiers (e.g cout).
    quoted from Naming - section of the Java Style Guide of the NPS)

  27. Names of methods with return type of void should reflect what they do (printArray).
    quoted from Naming - section of the Java Style Guide of the NPS)

  28. Names of methods which return something should reflect what they return (initialize).
    quoted from Naming - section of the Java Style Guide of the NPS)

  29. All global variables will start with "G_". Globals used only in a single class will be defined in that class, be declared as static, and start with "L_". const names are not considered global variables.
    quoted from Naming - section of the Java Style Guide of the NPS)

  30. Define TRUE, FALSE and NULL, and use them by name as opposed to using 1 and 0 explicitly.
    quoted from Naming - section of the Java Style Guide of the NPS)

  31. Avoid using absolute path addressing when referring to files. Use relative addressing based upon the location of the executable.
    quoted from Naming - section of the Java Style Guide of the NPS)

  32. Specify only the file names (i.e. without paths) for includes and libraries.
    quoted from Naming - section of the Java Style Guide of the NPS)

  33. Avoid long names (< 15 characters is a good idea). Although the class name PhysicalOrVirtualProductOrService might seem to be a good class name at the time (OK, I'm stretching it on this example) this name is simply too long and you should consider renaming it to something shorter, perhaps something like Offering (NPS , 1996).
    (see the NPS' Navy Java Style Guide)
    (quoted from 1.3 WHAT MAKES UP A GOOD NAME in AmbySoft Inc. Java Coding Standards by Scott W. Ambler, v. July 10, 1997, p. 1)

  34. Avoid names that are similar or differ only in case. For example, the variable names persistentObject and persistentObjects should not be used together, nor should anSqlDatabase and anSQLDatabase (NPS , 1996).
    (see the NPS' Navy Java Style Guide)
    (quoted from 1.3 WHAT MAKES UP A GOOD NAME in AmbySoft Inc. Java Coding Standards by Scott W. Ambler, v. July 10, 1997, p. 1)

  35. Avoid leading or trailing underscores. Names with leading or trailing underscores are usually reserved for system purposes, and may not be used for any user-created names except for pre-processor defines (NPS , 1996).
    (see the NPS' Navy Java Style Guide) More importantly, underscores are annoying and difficult to type so I try to avoid their use whenever possible.
    (quoted from 1.3 WHAT MAKES UP A GOOD NAME in AmbySoft Inc. Java Coding Standards by Scott W. Ambler, v. July 10, 1997, p. 1)

  36. Naming Constants
    In Java, constants, values that do not change, at typically implemented as static final attributes of classes. The recognized convention is to use full English words, all in uppercase, with underscores between the words (Gosling, Joy, Steele, 1996; Sandvik, 1996; NPS , 1996).
    (see the Java Coding Style Guidelines by Kent Sandvik)
    (see the NPS' Navy Java Style Guide)
    Examples:
    MINIMUM_BALANCE
    MAX_VALUE
    DEFAULT_START_DATE
    The main advantage of this convention is that it helps to distinguish constants from variables. (quoted from 3.1 NAMING ATTRIBUTES 3.1.2 Naming Constants in AmbySoft Inc. Java Coding Standards by Scott W. Ambler, v. July 10, 1997, p. 13 )

  37. Classes - section of the Java Style Guide of the NPS

  38. One way to make your classes easier to understand is to declare them in a consistent manner. The common approach in Java is to declare a class in the following order: (NPS , 1996) (see the NPS' Navy Java Style Guide)
    • public methods
    • public attributes
    • protected methods
    • protected attributes
    • private methods
    • private attributes
    Laffra ( in Advanced Java: Idioms, Pitfalls, Styles, and Programming Tips by Chris Laffra - PART I, Idioms and Programming Tips) points out that constructors and finalize() should be listed first, presumably because these are the first methods that another developer will look at first to understand how to use the class.
    (quoted from 6.1 STANDARDS FOR CLASSES 6.1.3 Class Declarations in AmbySoft Inc. Java Coding Standards by Scott W. Ambler, v. July 10, 1997, p. 27 )

  39. Methods - section of the Java Style Guide of the NPS

  40. The main() method shall be declared as the last method in the class, ie:
    quoted from Methods - section of the Java Style Guide of the NPS)

  41. Avoid multiple return statements in the same method.
    quoted from Methods - section of the Java Style Guide of the NPS)

  42. Test the return values of methods. It is not uncommon for a method to fail and an error manifest itself much later in the code.
    quoted from Methods - section of the Java Style Guide of the NPS)

  43. Each method (starting with the method comment) must be separated from other text/code by at least two blank lines.
    quoted from Methods - section of the Java Style Guide of the NPS)

  44. Globals - section of the Java Style Guide of the NPS

  45. For the most part, globals are bad and do not use them. However, there are a certain cases when globals might be used. All use of globals must be completely documented and justified.
    quoted from Globals - section of the Java Style Guide of the NPS)

  46. Files - section of the Java Style Guide of the NPS

  47. All Java source files will have a "java" extension and the prefix before the extension will be the same name as the class with in the file.
    quoted from Files - section of the Java Style Guide of the NPS)

  48. Comments - section of the Java Style Guide of the NPS

  49. Comments can be divided into two general categories, strategic and tactical. Strategic comments are used to give the reader a general overview of what is going on. These comments appear at the top of the files and before the function code. Strategic comments tend to be written in a prose style. Tactical comments are designed to explain tricky areas of code, what parameters do, and hints about the control flow of the program. These comments are imbedded in the code and tend to be shorter and in bullet format. The javadoc will be used to develop documentation files.
    quoted from Comments - section of the Java Style Guide of the NPS)

  50. If you use proper naming, block structure, indentation, and straight forward programming, your code will be mostly self documenting. This is what you should strive for. Keep comments simple. Do not attempt to explain the obvious. Do not use banner-like comments. Avoid decoration.
    quoted from Comments - section of the Java Style Guide of the NPS)

  51. Use the Java (C++) "/*"......"*/"construct for all comments. This will allow you to block out sections of code with the old comments.
    quoted from Comments - section of the Java Style Guide of the NPS)

  52. Implementation comments should be intermixed within the code. Usage comments will precede the code, normally in the file or function comment.
    quoted from Comments - section of the Java Style Guide of the NPS)

  53. Each class and method declaration must have a description in comments preceding it. The declaration will contain a comment pertaining to usage, and the definition should contain comments relating to the implementation.
    quoted from Comments - section of the Java Style Guide of the NPS)

  54. Avoid decoration, i.e. don't use banner-like comments. In the 1960s and 1970s COBOL programmers got into the habit of drawing boxes, typically with asterisks, around their internal comments (NPS , 1996).
    (see the NPS' Navy Java Style Guide) Sure, it gave them an outlet for their artistic urges, but frankly it was a major waste of time that added little value to the end product. You want to write clean code, not pretty code. Furthermore, because many of the fonts used to display and print your code are proportional, and many aren't, you can't line up your boxes properly anyway. (quoted from AmbySoft Inc. Java Coding Standards by Scott W. Ambler, v. July 10, 1997, p. 3)

  55. Miscellaneous - section of the Java Style Guide of the NPS

  56. Always use the most appropriate operator or construct.
    quoted from Miscellaneous - section of the Java Style Guide of the NPS)

  57. Always use the principle of least privilege (grant only that access necessary to perform the task and no more).
    quoted from Miscellaneous - section of the Java Style Guide of the NPS)

  58. All long int literals must have the `L' suffix (e.g. 40000L). Numerical constants ("magic numbers") must not be coded directly. The only allowable exceptions are for 0, 1 or -1, and those which are not "likely" to change.
    quoted from Miscellaneous - section of the Java Style Guide of the NPS)

  59. Numerical constants must have a comment explaining the value if it is not evident by the name.
    quoted from Miscellaneous - section of the Java Style Guide of the NPS)

  60. Enumeration types must be used to declare constants that have a discrete set of values. A comment must be provided indicating what the start value is.
    quoted from Miscellaneous - section of the Java Style Guide of the NPS)

  61. You must test floating point numbers with <= or >=. Never use exact comparisons with floating point numbers, even when comparing to 0.0f. The appropriate means of comparison is to define a value that represents the maximum difference two values may differ by and be considered equal.
    quoted from Miscellaneous - section of the Java Style Guide of the NPS)

  62. You should test your code. It should produce the correct results for normal test conditions as well as boundary conditions.
    quoted from Miscellaneous - section of the Java Style Guide of the NPS)

  63. Good design and clarity take precedence over optimization. (To a point)
    quoted from Miscellaneous - section of the Java Style Guide of the NPS)

  64. Do not declare or use more variables than are necessary.
    quoted from Miscellaneous - section of the Java Style Guide of the NPS)

  65. No line of code should exceed 72 characters (including blanks).
    quoted from Miscellaneous - section of the Java Style Guide of the NPS)

  66. If you open a file for reading/writing, close the file as soon as you are finished reading from/writing to it.
    quoted from Miscellaneous - section of the Java Style Guide of the NPS)