FrontPage/Axis2/CodeQuality

Code Quality Principles

• No spelling mistakes
  • - Use correct (US) English spelling
• Comment code
  • - use block comments at the start of the class and before each method - try to think about what's obvious and what isn't obvious e.g.

    •        /*
             ** Gets the Foo property
             ** [This comment is completely useless unless I've never read ANY Java before]
             */
             public Foo getFoo();
      
             /* 
             ** The Foo property is used to decide which foobar to use
             ** [This comment is trying to say something more than obvious]
             */
             public void setFoo(Foo foo);

    - Leave a blank line before the block comment - Don't put author information in code.

    - If you think people will need to contact you about the code it means you haven't put in enough doc

    - Clear JavaDoc comments for each method and class - Interfaces in particular should have clear comments for each method - If you can't explain the class or method, maybe you need to refactor - Use @value tags above comments, to Javadocs (and IDE javadoc popups) show the

    • value of constants

    •        /* 
              * Namespace of SOAP1.2.
              * {@value}
              */
             public static String SOAP12="http://www.w3.org/2003/05/soap-envelope";

• No warnings or errors in Eclipse/IDEA
  • - There should be no import package.* - There should be no imports that aren't used - There should be no unused local variables - Serializable classes need serialVersionUIDs and an implicit guarantee of stability - Or better still remove java.io.Serializable unless we are actually using it - Don't use static methods on instances (use the class not the object)
• Don't use long lines (e.g. greater than 100 characters)
• Aim to initialize variables where they are defined
• Use curly braces on if, while statements
  • - dont use the shortcut if (something) a; else b;
• If the name of an class or method isn't clear rename it
  • - if in doubt ask one or two other people
• Always comment decisions you made or didn't make
  • - If you chose one of two options explain why

    - If you failed to do something add a comment // TODO to let other committers know

• Order of content in a class
  • - Apache license at the absolute top of the file - Package definition followed by any import statements - Class comments followed by the class definition
    • - All field definitions must be at the top of the class - Immediately after that should be the constructors, ordered from most specific (in terms of the number of args) to the least specific (being a no-args constructor, where appropriate) - Immediately after that should be private methods that are used by constructors - Immediately after that should be getter/setter methods for properties - Immediately after that are all public methods - Finally the private methods used by the class
• Internationalization of messages
  • - Ensure all error and other messages are fully internationalized