Java Coding Conventions

During the OOP lab, you will also get points for the way the source code is paged, tabbed, the naming of the classes, methods and variables, and the general structure of the program. The conventions that need to be followed are:

• avoid using innner-classes, so in a Java file only define one class;
• the segments of the file should appear in the following order:
  • header comment, describing the role of the class, author and the project it is part of;
  • package definition, if it exists;
  • import directives;
  • the class or interface declaration;
  • field declarations, all indented with one tab, in the following order:
    • class constants;
    • static fields;
    • dynamic fields;
  • static methods (un-indented);
  • constructors, starting from the least complex to the most complex (un-indented);
  • methods (un-indented);
  • footer comment, describing the changes in the file;
• all segments of the file are split by a comment-line which appears also between methods;
• the main method, if it exists, is placed immediately before the first constructor;
• for the block of statements attached to an if / else / do-while / for / case and for the body of a class / method, the open curly bracket is placed on the same line with the if / else / do / for / case keyword, respectively the class / method declaration, and the closed curly bracket is placed on a separate line, on the same column with the first letter of the keyword / declaration;
• an instruction block is indented by one extra tab in respect to the previous level;
• class names and constructor names implicitly, start with an uppercase letter;
• method names start with a lowercase letter;
• field names start with a lowercase letter;
• constant names are written in caps, words separated by the "_" character;
• method arguments and local variables start with the underscore character ("_") with the second character being a lowercase letter. There are exceptions in the form of cycle counters: i, j, k, etc.
• the naming must be as explicit as possible regarding their purpose, in order to avoid excessive comments;
• it is allowed to insert a blank line, if a natural segregation of elements is obtained through it.

These coding conventions are a necessary minimum for the OOP lab. For those who wish to study the coding conventions recommended by Oracle, they can find it online.

Example (attention, this program will not function on its own since it is part of a project:

//------------------------------------------------------------------------------
//
//		This is the title of the Project
//			- Assembler -
//
//------------------------------------------------------------------------------
//
//  The role of this class is to provide an example as to how a Java
// class is structured and how the code is written. It provides examples
// for naming conventions and code alignment.
//
//------------------------------------------------------------------------------
package ro.pub.arh.beam.assembler;

//------------------------------------------------------------------------------
import ro.pub.arh.beam.assembler.structs.*;
import java.io.*;
import java.util.Vector;
import ro.pub.arh.beam.structs.*;
import ubiCORE.jroot.common.utils.ErrorCode;
import ro.pub.arh.beam.common.HexConverter;
//------------------------------------------------------------------------------
public class Assembler{

    public static final int REGISTER_COUNT = 32;
    public static final String INSTRUCTION_SEPARATOR = "\\|";
    public static final String OPERAND_SEPARATOR = "\\s+|\\s*\\,\\s*";
    
    private static PrintStream dumpStream = System.out;

    private String fileName;

    private int currentAddress;
    private int currentLine;

    private Program program;
    private Function function;
    private int entityIndex;

//------------------------------------------------------------------------------
public static void main(String[] _args){
    try{
        new Assembler(_args[0]).run();
    }catch(ArrayIndexOutOfBoundsException _aiobe){
        out("File is empty or no file specified.");
    }catch(Exception _e){
        _e.printStackTrace();
        out("Assembly error: " + _e.getMessage());
    }
}

//------------------------------------------------------------------------------
public Assembler(String _fileName){
    fileName = _fileName;
    currentAddress = 0;
    currentLine = 1;
}

//------------------------------------------------------------------------------
public void run() throws IOException, ErrorCode{

    BufferedReader _reader = new BufferedReader(new FileReader(fileName));
    String _line;
    Vector<Instruction> _instructions = null;
    boolean _atLeastOneError = false;

    entityIndex = 0;
    program = new Program(fileName);
    do{
        _line = _reader.readLine();
        if(_line == null){
            program.add(function);
            break;
        }
        _line = trimWhiteSpaces(_line);
        try{
            _instructions = null;
            _instructions = processLine(_line);

            if(_instructions != null){
                function.addAll(_instructions);
                currentAddress += Instruction.INSTRUCTION_LOCATION_COUNT;
            }
        }catch(RuntimeException _re){
            out("Line " + currentLine + ": " + _re.getMessage());
            //_re.printStackTrace();
            _atLeastOneError = true;
        }
        
        currentLine++;
    }while(true);

    if(_atLeastOneError){
        out("Finished with errors.");
        throw new RuntimeException("Assembly failed.");
    }
    
    out("No syntax errors.");
    //placeIRQHandler("irq_handler", MachineConstants.IRQ_HANDLER_ADDR);
    replaceJumpLabels();
    buildLineSeeker();

    out("Assembly succesfull!");

    program.sort();

}

//------------------------------------------------------------------------------
private Vector<Instruction> processLine(String _line){
//...
}

//------------------------------------------------------------------------------
private String trimWhiteSpaces(String _line){
    _line = _line.substring(0, _line.indexOf("//") == -1 ? _line.length() : _line.indexOf("//"));
    _line = _line.substring(0, _line.indexOf(";") == -1 ? _line.length() : _line.indexOf(";"));
    _line = _line.trim();
    _line = _line.replaceAll("\\s+", " ");
    return _line;
}

//------------------------------------------------------------------------------
private int getValueOfString(String _number){
    int _value;

    try{
        if(_number.startsWith("0x")){
            _value = Integer.parseInt(_number.substring(2), 16);
        }else{
            _value = Integer.parseInt(_number);
        }
    }catch(NumberFormatException _nfe){
        throw new RuntimeException("Invalid new code address");
    }

    if(_value % 4 != 0){
        throw new RuntimeException("Invalid new code address " + currentLine + ". Address must divide by 4.");
    }
    return _value;
}

//------------------------------------------------------------------------------
private void replaceJumpLabels(){
    int _address = 0;
    Instruction _instruction = null;

    for(int i=0; i<program.size(); i++){
        Function _function = program.elementAt(i);
        for(int j=0; j<program.elementAt(i).size(); j++){
            _instruction = _function.elementAt(j);
            if(_instruction.getLabel() != null){
                String _label = extractLabel(_instruction.getLabel());
                if(_instruction.isCall()){
                    _address = program.findAddressOfFunction(_label);
                }else if(_instruction.isAbsoluteJump()){
                    _address = program.findAddressOfLabel(_label);
                }else{
                    _address = program.findAddressOfLabel(_label) - _instruction.getAddress();
                }

                _instruction.setLabelAddress(offsetAddress(_address, _instruction.getLabel()));
            }
        }
    }
}

//------------------------------------------------------------------------------
}
//------------------------------------------------------------------------------
//      Change History:
//      $Log: Assembler.java,java First file revision.$