Skip to content

Project Code Convention

Jump to bottom
Pedro Ivo de Andrade edited this page Apr 5, 2016 · 76 revisions

Table of Contents

  1. Naming Files
  2. Classes
  3. Methods
  4. Attributes/Variables
  5. Line Length
  6. Comments
  7. Keys & Indent
  8. Test
  9. Exceptions

1. Naming Files

All the project file's content must be named in English. The name of the files in Java must have the same name of the Class. Java establishes an order that must be used in the file:

Example:

/*
 * Class name: HospitalAdapter.java
 * Date: April 4, 2016.
 * Programmers: Iolane Andrade, Lucas Brilhante, Pedro Ivo de Andrade, 
                Vinícius Carvalho.
 * Purpose: Class that create an item list for the user by inflating the items and putting them on the
 *          screen.
 */

package mds.gpp.saudeemcasa.adapter;

import android.content.Context;
import android.view.LayoutInflater;
import android.view.View;
import android.view.ViewGroup;
import android.widget.ArrayAdapter;
import android.widget.ImageView;
import android.widget.TextView;

import java.util.ArrayList;

import mds.gpp.saudeemcasa.R;
import mds.gpp.saudeemcasa.model.Hospital;

public class HospitalAdapter extends ArrayAdapter<Hospital>   {

    private Context context = null;
    private ArrayList<Hospital> list = null;
    public static final int COUNT = 15;

    public HospitalAdapter(Context context, ArrayList<Hospital> list){
        super(context, 0, list);
        this.context = context;
        this.list = list;
    }

...

}

2. Classes

The name of the classes must begin with capital letter in the singular, and must not be abbreviated. The following rules must be followed:

  • Names made by multiple letters must follow the standard UpperCamelCase, where each word will begin with a capital letter.
  • The name must not have any characters other than the letter of the alphabet.

The functional order of the components of the class are:

  • Constants
  • Attributes of the class
  • Attributes of the instance
  • Constructors
  • Main methods
  • Helper methods

Example:

public class Stablishment {
    private String latitude = "";
    private String longitude = "";
    private String type = "";
    private String telephone = "";
    private String name = "";
    private String city = "";
    private String address = "";
    private String state = "";
    private float rate = 0;
    private String id;
    private float distance = 0;

    public Stablishment(String name, String telephone) {
        this.name = name;
        this.telephone = telephone;
    }

    public String getId() {
        return id;
    }
    public void setId(String id) {
        this.id = id;
    }

...

}

3. Methods

All methods will have their initial & final parameters without a space between the opening and closing of their parenthesis. Each aditional parameter will have a comma at the end of the following and a ' '(space) for the beginning of the new parameter.

  • Methods must be named in lowerCammelCase.
  • Methods needs a verb to describe the action he execute.

Example:

public void onStatusChanged(String provider, int status, Bundle extras) {
    ...
}

4. Attributes/Variables

The attributes must follow this formatting standard:

  • Only one declaration in each line.
  • The names must follow the standard lowerCamelCase.
  • They can't be abbreviated.
  • They can't have special characters.
  • For constant names with two names, they need to be separated with the underscore and be written all with capital letters.
  • Global variables should not be used, but if it must then it shall follow the java pattern: NAME_NAME

Example of variables:

public class Stablishment {
    
    // Correct way.
    private String postalCode = "";

    // Wrong Way
    private String postalcode = "";
    // Wrong Way
    private String PostalCode = "";
    // Wrong Way
    private String POSTALcode = "";
}

Global variables examples:

public class HospitalAdapter extends ArrayAdapter<Hospital> {
    ...
    // Correct way.
    public static final int HOSPITAL_QUANTITY = 15;
    // Wrong way
    public static final int hospital_Quantity = 15;
    // Wrong way
    public static final int hOsPiTal_QuAnTiTy = 15;
    ...
}

5. Line length

Avoid lines longer than 80 characters. When a statement won't fill in a single line, it may be necessary to break it.

6. Comments

Comments must be the second type of information that is being declared.

The comments must be initialized first with capital letter. At their end, it must be add a '.' (dot) to indicate it's end.

6.1 Class Comments

To document a method or a class, you must use the type '/** & */, and to start typing there must be a space.

Example of Class comment:

/**
 * Hospital class inherits Stablisment. Hospital has two attributes more
 * than stablishment. Are they, number and district. Both used to add more
 * information on hospital address.
 */
public class Hospital extends Stablishment {
    ...
}

6.2 Single Line/Multiple Lines Comments

For single line comments, we use //. The // can be used inside methods, inside classes, and for short declaration comment.

Example of single line comment:

    public void requestRating() throws ConnectionErrorException {
        // Correct way.
        HttpConnection httpConnection = new HttpConnection(); // New Connection.
    }
    public void requestRating() throws ConnectionErrorException {
        /* WRONG WAY TO COMMENT */ 
        HttpConnection httpConnection = new HttpConnection(); /* New Connection */.
    }

The /*...*/ single line comment is used only in if-else statements to show which one don't have an action.

If technical comments exceed one line they must be changed from '//' to /* & */, jumping a line to start and a line to finish.

Example of multiple lines comment:

        /* 
         * Return the unique instance of DrugstoreController active in the
         * project.
         */
        return instance;
    }

6.3 Statement Comments

When if / else statement have no action, leave a commentary like this.

Example 1:

if(DrugStoreDao.instance != null) {
    /* !Nothing To Do. */
} else {
    DrugStoreDao.instance = new DrugStoreDao( context );
}

Example 2:

if (drugstoreController.getAllDrugstores().size()>0 && 
                        hospitalController.getAllHospitals().size()>0) {
    toListScreen();
} else {
    /* ! Nothing To Do. */
}

6.4 File Initial Comment

All source files should begin with a c-style comment that lists the programmer(s), the date, the file name and your extension, and also a brief description of the purpose of the program.

Example:

/*
 * Class name: Hospital.java
 * Date: April 4, 2016.
 * Programmers: Iolane Andrade, Lucas Brilhante, Pedro Ivo de Andrade, 
                Vinícius Carvalho.
 * Purpose: Represents hospital entity.
 */

7. Keys & Indent:

7.1 General Rules

All keys must be in the same line of command. The value of a tab must be equivalent to 4 spaces. Every if statement shall have your else . If the latter does not take any action should be a comment, as specified in statement comments.

   // Correct way.
   for() {
       if() {
       } else if() {
       } else {
       }
   }
   // Wrong Way.
   for() {
       if() {
       } 
       else if() {
       } 
       else {
       }
   }

7.2 Blank Lines

The variable declarations and methods must be separated each by a blank line. Between the sentences package & import, must have a blank line. Between imports from different API's there must be a blank line.

package mds.gpp.saudeemcasa.view;

import android.os.Bundle;
import android.support.v4.app.FragmentActivity;

import com.google.android.gms.maps.CameraUpdateFactory;
import com.google.android.gms.maps.GoogleMap;
import com.google.android.gms.maps.SupportMapFragment;

import mds.gpp.saudeemcasa.R;
import mds.gpp.saudeemcasa.controller.DrugStoreController;

public class GoogleMapDrugStore extends FragmentActivity {

    private GoogleMap mMap;
    DrugStoreController controller = DrugStoreController.getInstance(this);

    @Override
    protected void onCreate(Bundle savedInstanceState)

7.3 Blank Spaces

Each attribution, with the operator '=' must be followed with an unitary space before & after. In the use of a comma, there must be an empty space after. There must be space between the closing of parenthesis and method keys. In logical & arithmetic operations, there must be a blank space between the operators and operands.

private static final long MIN_TIME_BW_UPDATES = 1000 * 60 * 1;

locationManager.requestLocationUpdates(LocationManager.NETWORK_PROVIDER,
                            MIN_TIME_BW_UPDATES, MIN_DISTANCE_CHANGE_FOR_UPDATES, this);

7.4 Line Breakers

Instructions that break the line must be aligned with the operator '+' in the next line. In parameters, the line breaker (if necessary) must be after a comma.

textViewDistance.setText(convertToKM(this.lista.get(position).getDistance()).toString() 
                                     + " Km");

7.5 Annotations

Annotations should be written in previous line, see samples:

    // Correct way.
    @Override
    public int getCount() {
        ...
    }

    // Wrong way.
    @Override public int getCount() {
        ...
    }

It should be used in any kind of annotation and any place.

8. Test

The name of the test classes must have "Test" followed by the name of the tested class.

   TestHospitalDao.java

The name of the methods must sugest the funcionality witch is being tested.

 @Test
    public void testGetPostalCode() {
        DrugStore drugStore = new DrugStore();
        drugStore.setPostalCode("2034");
        assertEquals("2034", drugStore.getPostalCode());
    }

9. Exceptions

Under Construction.

10. A Very Brief Example

Clone this wiki locally