QueWeb Coding Standards


Introduction
~~~~~~~~~~~~
This document specifies the coding rules and conventions all QueWeb 
developers should follow. It applies to qwcore and all custom qwapp projects.


Subversion Rules
~~~~~~~~~~~~~~~~

Commit Comments
---------------
Always specify short description of what you have changed when commiting to
the repository, do not commit without the description.
For example:
    # Wrong:
    svn ci -m ""

    # Right:
    svn ci -m "Cosmetic code reformating"


Coding Rules
~~~~~~~~~~~~

Java Files Structure
--------------------
All Java files should have the following structure:
=========================================
/*
 * Copyright 2006-2007 Queplix Corp.
 *
 * Licensed under the Queplix Public License, Version 1.1.1 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.queplix.com/solutions/commercial-open-source/queplix-public-license/
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 
 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the 
 * License for the specific language governing permissions and limitations under
 * the License.
 */
package ...;

import ...;

/**
 * Description.
 * @author Firstname LastName
 * @since 8 Dec 2006
 */
public ... {
    ...
}
=========================================

Import Statements
-----------------
All Java import statements should allways specify fully qualified class names
rather than wildcards. It improves understanding and compiler's performance, 
especially in case of GWT.
For example:
    import java.util.*; // Wrong
    import java.util.ArrayList; // Right

Repetitive Expressions
----------------------
There should be no repetitive parts of expressions. Declare a local variable,
initialize it with the repetitive part of expressions and use it in the 
expressions. It will help reading, understanding and slightly improve
perfomance.
For example:
    // Wrong:
    obj.methA().methB();
    obj.methA().methC();
    v1 = arr[index].methD();
    v2 = arr[index].methE();

    // Right:
    A a = obj.methA();
    a.methB();
    a.methC();
    B b = arr[index];
    v1 = b.methD();
    v2 = b.methE();
In most cases non-repetitive but long expressions (with more than 3-4 tokens) 
should also be split into multiple parts to help reading and understanding.
For example:
    // Wrong:
    obj.methA().methB().methC()[index].methD();

    // Right:
    C[] arr = obj.methA().methB().methC();
    arr[index].methD();

Garbage Code
------------
Never use commenting to collect garbage code. The code should be clean and not
contain commented out chunks of garbage code.
For example:
    // Wrong:
    a = someMeth() / 2;
    //b = (a + 5) * 3;
    //if (b == 48) {
    //    return;
    //}

    // Right:
    a = someMeth() / 2;
In other words comments should contain actual text intended for reading only.

Commenting
----------
All comments should be written in English and contain ASCII characters only.
If your OS locale is not English and your IDE generates comments with localised 
entries (like dates) all generated non-ASCII characters should be removed 
manually.

Whitespace
----------
Source code files should never contain TAB characters. If you use TABs, 
configure your IDE to replace them with spaces.

Indentation
-----------
One level of indent should be exactly 4 spaces.
For example:
    // Wrong:
    int meth(int[] a) {
      int res = 0;
      for (int i = 0; i < a.length; i++) {
        res += a[i];
      }
      return res;
    }

    // Right:
    int meth(int[] a) {
        int res = 0;
        for (int i = 0; i < a.length; i++) {
            res += a[i];
        }
        return res;
    }

Short Files
------------
Strive to avoid producing lots of very short files (with less than 10-20 lines
of actual code). Consider using static inner classes instead where appropriate.

Localized Messages
------------------
Never hard-code any messages displayed to users. Use localization mechanism in 
place. For example, in case of qwcore GWT code see the following drectory:
    qwcore/qwcore-gwt/src/com/queplix/core/client/app/i18n

Java Doc
--------
All non-trivial code should be documented with Java Doc comments. The purpose
and usage information should be clearly described.

