• Post Reply Bookmark Topic Watch Topic
programming forums Java Mobile Certification Databases Caching Books Engineering Micro Controllers OS Languages Paradigms IDEs Build Tools Frameworks Application Servers Open Source This Site Careers Other Pie Elite all forums
this forum made possible by our volunteer staff, including ...
Marshals:
  • Campbell Ritchie
  • Jeanne Boyarsky
  • Ron McLeod
  • Paul Clapham
  • Liutauras Vilda
Sheriffs:
  • paul wheaton
  • Rob Spoor
  • Devaka Cooray
Saloon Keepers:
  • Stephan van Hulst
  • Tim Holloway
  • Carey Brown
  • Frits Walraven
  • Tim Moores
Bartenders:
  • Mikalai Zaikin
  • Likes 1
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
This page was migrated from a javaranch.com.jsp

   
     
   

   
   
     
     Java Programming Style Guide
   
 




   Introduction


   1 Formatting
   
   2 Identifiers
   
   3 Coding
   
   4 Self-Documenting Code
   
 





Introduction

The Java language gives you all the room you need to write code that would be very
difficult for others to understand. Java also permits you to write code that is very easy
to understand. Most development teams would prefer the latter.



A style guide provides provides a map so that the code generated by a group of programmers
will be consistent and, therefore, easier to read and maintain. Many people do not care for the
style guide offered by Sun.
This document is one alternative.



This document covers most areas where there could be confusion or difference of opinion.
Areas that have never been a problem in our experience are undocumented, but we try to provide
at least one example to demonstrate proper use somewhere in the document.



1 - Formatting


    1.1 - Indentation

    <strong>All indenting is done with spaces, not tabs. All indents are four spaces.</strong>

    <em>Reasoning: All programs work well with spaces. Most programs will mix tabs
    and spaces so that some lines are indented with spaces and some with tabs. If your
    tabbing is set to 4 and you share a file with someone that has tabbing set to 8,
    everything comes out goofy.</em>




    <strong>Matching braces always line up vertically in the same column as their construct.</strong>


    example:



    <strong>All if, while and for statements must use braces even if they control
    just one statement.</strong>

    <em>Reasoning: Consistency is easier to read. Plus, less editing is involved
    if lines of code are added or removed.</em>






    1.2 - Spacing

    <strong>All method names should be immediately followed by a left parenthesis.
    </strong>



    <strong>All array dereferences should be immediately followed by a left square bracket.</strong>


    <strong>Binary operators should have a space on either side.</strong>


    <strong>Unary operators should be immediately preceded or followed by their operand.</strong>


    <strong>Commas and semicolons are always followed by whitespace.</strong>


    <strong>All casts should be written with no spaces. </strong>


    <strong>The keywords <code>if</code>, <code>while</code>, <code>for</code>, <code>switch</code>, and <code>catch</code> must be followed by a space.</strong>


    1.3 - Class Member Ordering



    1.4 - Maximum Line Length

    <strong>Avoid making lines longer than 120 characters. If your code starts to get indented way to
    the right, consider breaking your code into more methods.</strong>

    <em>Reasoning: Editors and printing facilities used by most programmers can easily
    handle 120 characters. Longer lines can be frustrating to work with.</em>



    1.5 - Parentheses

    <strong>Parentheses should be used in expressions not only to specify order of precedence, but
    also to help simplify the expression. When in doubt, parenthesize.</strong>


2 - Identifiers
<strong>All identifiers use letters ('A' through 'Z' and 'a' through 'z') and numbers ('0'
through '9') only. No underscores, dollar signs or non-ascii characters.</strong>



    2.1 - Classes and Interfaces

    <strong>All class and interface identifiers will use mixed case. The first letter
    of each word in the name will be uppercase, including the first letter of the name.
    All other letters will be in lowercase, except in the case of an acronym,
    which will be all upper case.</strong>



    Examples:

       

      Customer

       SalesOrder

       TargetURL

       URLTarget

       





    2.2 - Packages

    <strong>Package names will use lower case characters only. Try to keep the length under eight
    (8) characters. Multi-word package names should be avoided.</strong>



    Examples:

       

      common

       core

       lang

       





    2.3 - All Other Identifiers

    <strong>All other identifiers, including (but not limited to) fields, local variables,
    methods and parameters, will use the following naming convention.
    This includes identifiers for constants.</strong>



    <em>Reasoning: Using all upper case, as traditionally done in C, is a violation of OO abstraction.
    For example, a variable which starts out as a constant may be refactored later to not be a constant.</em>



    <strong>The first letter of each word in the name will be uppercase, except for the first letter of
    the name. All other letters will be in lowercase, except in the case of an embedded
    acronym, which will be all uppercase. Leading acronyms are all lower case.</strong>



    Examples:

       

      customer

       salesOrder

       addToTotal()

       targetURL

       urlTarget

       





      2.3.1 Hungarian Notation and Scope Identification
      <strong>Hungarian notation and scope identification are not allowed.</strong>

      <em>Reasoning: Hungarian Notation, which specifies type as part of the identifier, violates OO abstraction.  Scope identification specifies scope as part of the identifier, which also violates OO abstraction.</em>







      2.3.2 Test Code
      <strong>Test code is permitted to use underscores in identifiers for methods and fields.</strong>

      <em>Code for testing other code often needs to be able to refer to existing identifiers, but also be able to append other qualifiers to the name.  This is easier to read if an additional delimiter is allowed.</em>



      Example:


           Code to test a method <code>double eatSomePie(double amount)</code> may use variables such as:

           

           <code>eatSomePie_count</code>

           <code>eatSomePie_amount</code>

           <code>eatSomePie_return</code>

           <code>eatSomePie_exception</code>





    3 - Coding



      3.1 - Constructs to Avoid



        3.1.1 - Never use do..while

        <strong>Do not use <code>do..while</code> loops.</strong>

        <em>Reasoning: Consider that the programmer looking at your code is probably examining
        each method starting at the top and working down. When encountering a loop, the first
        thing the programmer wants to know is what terminates the loop. If you have that logic at
        the bottom, it is harder to read. Further, many less experienced programmers are not
        familiar with do..while, but may be required to modify your code.</em>



        So rather than:



        use:



        3.1.2 - Never use <code>return</code> in the middle of a method

        <strong><code>return</code> is to be used at the end of a method only.</strong>

        <em>Reasoning: Using <code>return</code> in the middle of a method makes it difficult to
        later break the method into smaller methods. It also forces the developer to consider more
        than one exit point to a method. </em>




        3.1.3 - Never use <code>continue</code>

        <strong>Never use <code>continue</code>.</strong>

        <em>Reasoning: Using <code>continue</code> makes it difficult to later break the
        construct into smaller constructs or methods. It also forces the developer to consider
        more than one end point for a construct. </em>




        3.1.4 - Never use <code>break</code> other than in a switch statement

        <strong><code>break</code> is used only for switch statement control.</strong>

        <em>Reasoning: Using <code>break</code>, other than for switch statement control, makes
        it difficult to later break a construct into smaller constructs or methods. It also forces
        the developer to consider more than one end point for a construct. </em>





      3.2 - Do Not Compound Increment or Decrement Operators

      <strong>Use a separate line for an increment or decrement.</strong>

      <em>Reasoning:  Compounding increment or decrement operators into
      method calls or math is not clear to less experienced programmers who
      may be required to modify your code.</em>



      Examples:


      Note: i++ and ++i are equally fast, and i++ seems more consistent with the
      rest of the language. Since the above prevents any use of a case where ++i
      could make a difference, never use pre- increment/decrement.


      3.3 - Initialization

      <strong>Declare variables as close as possible to where they are used.</strong>



      Examples:




      3.4 - Access

      <strong>All fields must be private, except for some constants.</strong>



    4 - Self-Documenting Code




       

           

               
             

         



    <strong>Rather than trying to document how you perform a complex algorithm, try to make the
    algorithm easier to read by introducing more identifiers. This helps in the future in case the
    algorithm changes but someone forgets to change the documentation.</strong>


    Example:

      Instead of:


      Use:




    Or:
      Instead of:




      Use:


 
    Bookmark Topic Watch Topic
  • New Topic