Convenții de programare

De la WikiLabs

La laboratorul de POO se va puncta și modul în care un program este paginat, tabulat, modul în care sunt denumite clasele, metodele și variabilele, și, în general, modul în care codul este structurat. Regulile care trebuie respectate sunt:

  • se evită utilizarea de inner-class, deci într-un fişier Java se definește o singura clasă;
  • segmentele fişierului apar în următoarea ordine:
    • comentariul de introducere (header) care descrie pe scurt rolul clasei;
    • declaraţia de pachet (dacă există);
    • directivele de import;
    • declaraţia de clasă / interfaţă;
    • declaraţiile de câmpuri, toate identate cu un tab, în următoarea ordine:
      • constante de clasă;
      • câmpuri statice;
      • câmpuri dinamice;
    • constructori, de la cel mai puţin complex la cel mai complex (neidentate);
    • metode (neidentate);
    • comentariul de final (footer);
  • toate segmentele fişierului sunt despărţite printr-o linie-comentariu ce apare inclusiv între constructori şi între metode;
  • metoda main, dacă există, este plasată între constructori şi metode;
  • pentru instrucţiuni if / do-while / for / case, şi pentru blocul metodelor, acolada care deschide blocul de instrucţiuni se află pe aceeaşi linie cu instrucţiunea / declaraţia iniţială iar acolada de final se află pe o linie separată, pe aceeaşi coloana cu prima literă din instrucţiune / declaraţie;
  • un bloc de instrucţiuni este identat cu un tab faţă de nivelul imediat superior;
  • numele de clase, implicit constructori, încep cu majusculă.
  • numele de metode încep cu litera mică;
  • numele de câmpuri încep cu litera mică;
  • numele de constante sunt scrise numai cu majuscule, cuvintele fiind desparţite prin "_";
  • argumentele și variabilele locale ale metodelor sunt declarate imediat sub declaraţia metodei, neidentate, şi încep cu caracterul “_”, având a doua literă mică. Excepţie fac contorii de cicli: i, j, k;
  • numele trebuie să fie cât mai sugestive în ceea ce priveşte scopul, pentru a evita comentariile excesive;
  • este permisă introducerea unei linii goale, dacă prin acest lucru se realizează o segregare naturală a elementelor.

Aceste convenții de scriere a codului sunt doar un minim necesar(și obligatoriu) pentru laboratorul de POO. Pentru cei ce vor să cunoască tot setul de convenții recomandat de Oracle, îl pot găsi online.

Exemplu (atenție, acest program nu va funcționa de sine stătător deoarece este parte a unui proiect):

//------------------------------------------------------------------------------
//
//		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 Assembler(String _fileName){
    fileName = _fileName;
    currentAddress = 0;
    currentLine = 1;
}

//------------------------------------------------------------------------------
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 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 $