PCSA Stylesheet

#PCSA Stylesheet

This document brings a series of coding conventions to be used in the PCSA-Android project.

Naming
Formatting
Comments
Exception handling
Good practices

##1. Naming

1.1 Name of the File

All the project files should use UpperCamelCase on its name.

    
// Good Code
	CustomAlertDialogFragment.java

// Bad Code
	Customalertdialogfragment.java
	Custom_Alert_Dialog_Fragment.java
	customAlertDialogFragment.java

1.2 Atributes

The atributes must be written in lowerCamelCase and there should be only one per line. Furthermore, the atributes should not be abbreviated must not have special characters.

// Good Code
	private Vibrator vibrator;
	ImageView[] comradesViews;

// Bad Code
	ImageView[] comrades_views;
	ImageView[] comradesviews;
	ImageView[] ComradesViews;

1.3 Methods & Parameters

All methods and parameters should use lowerCamelCase.
All methods will have their initial and final parameters without a blank space between them and the parenthesis.
Any additional parameter will have a blank space after the comma that separate them with the beginning of the following parameter.
The methods names should have a name representing what it means, using a action verb.
After the closing parenthesis there should be a blank space before the opening bracket

// Good Code
	private EditText findInput(View view) {

	}
	
	protected void onActivityResult(int requestCode, int resultCode, Intent data) {
	
	}

// Bad Code
	protected void onActivityResult(int requestCode,int resultCode,Intent data) {
	
	}

	protected void onActivityResult(int requestCode, int resultCode, Intent data){
	
	}

1.4 Classes & Interfaces

For classes and interfaces their name should begin with a capital letter, be in the singular form, and must not be abbreviated. Names composed by multiple words should use the UpperCamelCase and there should not be any other character that is not present in the alphabet.

// Good Code
	public class Confidentiality {
		// Class code.
	}

	public class CircleOfTrustFragment {
		// Class code.
	}

// Bad Code
	public class Trustees {
		// Class code.
	}

	public class circleOfTrustFragment{
		// Class code.
	}

	public class CircleofTrustFragment {
		// Class code.
	}

1.5 Acronyms

Treat acronyms as a word.

// Good Code
    private String urlQuery = "";

// Bad Code
    private String URLQuery = "";

1.6 Constants

Constants must be written in SCREAMING_SNAKE_CASE

// Good Code
	public static final int REQUEST_SELECT_CONTACT = 100;

// Bad Code
	private static final boolean firstTime = false;

##2. Formatting

2.1 Tabs

Tabulation must be 4 spaces sized

// Good Code
	if(comradesViews.length > i) {
		button = comradesViews[i];
	}

// Bad Code
	if (comradesViews.length > i) {
	  button = comradesViews[i];
	}

2.2 Line Lenght

The maximum size for a single line is 110 characters. The command should br divided in many lines as necessary to increase the visibility of the code. Instructions that have muktiple lines should be aligned with the '+' operator of the following line and the ones that does not have a '+' operator should follow the tabs rule, using a 4 space size identation to show that the instruction belongs to the line above.

// Good Code
	contentToPost = getString(R.string.confirmation_message1) + " " 
		+ counter + " " + getString(R.string.confirmation_message3) + " " 
		+ getString(R.string.receive_log);
	CustomAlertDialogFragment customAlertDialogFragment = 
		CustomAlertDialogFragment.newInstance(getString(R.string.no_comrade_title),getString(R.string.no_comrade_msg));

// Bad Code
	contentToPost = getString(R.string.confirmation_message1)+ " " + counter + " "+ getString(R.string.confirmation_message3) +" " + getString(R.string.receive_log);
	CustomAlertDialogFragment customAlertDialogFragment = CustomAlertDialogFragment.newInstance(getString(R.string.no_comrade_title),getString(R.string.no_comrade_msg));

2.3 Logic Groups

The logic groups should be separated by a single blank new line.

// Good Code
	TextView reporting_step1 = (TextView) rootView.findViewById(R.id.reporting_step1);
	TextView reporting_step2 = (TextView) rootView.findViewById(R.id.reporting_step2);
	
	reporting_step1.setText(Html.fromHtml(getResources().getString(R.string.helping1)));
	reporting_step2.setText(Html.fromHtml(getResources().getString(R.string.helping2)));
	
// Bad Code
	TextView reporting_step1 = (TextView) rootView.findViewById(R.id.reporting_step1);
	TextView reporting_step2 = (TextView) rootView.findViewById(R.id.reporting_step2);
	reporting_step1.setText(Html.fromHtml(getResources().getString(R.string.helping1)));
	reporting_step2.setText(Html.fromHtml(getResources().getString(R.string.helping2)));

2.4 Brackets

Brackets must be open at the same line
There should be a blank space preceding it, between it and the last caracter of the line
They must be closed at the sabe position horizontaly where it was opened
There should always be a opening and closing brackets in every logic group

// Good Code
	for(String number : numbers) {
            if (!number.isEmpty()) {
                try {
                    sms.sendMultipartTextMessage(number, null, parts, sentIntents, null);
                }
                catch(Exception e) {
                    Toast.makeText(getActivity(), R.string.message_failed + (counter + 1), Toast.LENGTH_LONG).show();
                }
                counter++;
            }
        }

// Bad Code
	if(counter!=0)
    {
    	// If Code
	}
	else
	{
		// Else Code
	}

	if(counter == 1)
		// If Code

2.6 Operators

Operators must be preceded and followed by a blank space.

All logic, math and boolean operators should be treated this way, regarding just the ! operator, when its meaning is the logic NOT. The increment operators should also not be included in this practice, as is not necessary to be in between spaces.

Operators :, ?, =, <, >, <=, >=, ==, +=, -=, +, -, *, \

// Good Code
    String title = getArguments().getString(TITLE_KEY);

    if(title != null) {
        // ...
    }

// Bad Code
    String title=getArguments().getString(TITLE_KEY);

    if(title!= null) {
        // ...
    }

2.7 Spaces

There must not be spaces after or before [, ] and (. Excluding just the ) as there must be a space after it when it is written in blocks and is followed by a {.

There will be a space after a method name, if, else if, switch, for, while, try, catch.

// Good Code
    public void onClick(View v) {
        // ...
    }

    if (faqDesc.getVisibility() == View.INVISIBLE) {
        // ...
    }
    else {
        // ...
    }

// Bad Code
    public void onClick (View v){
        // ...
    }

    if (faqDesc.getVisibility() == View.INVISIBLE) {
        // ...
    }
    else{
        // ...
    }

##3. Comments

The comments must be first initialized with a capital letter and ended with a final dot '.' to indicate it's end.

3.1 Class header

To document a class the /* */ block comment should be used, with every new comment line precedded with a *.
The first line should be only composed by the opening comment block /*
Every new comment line should have a space after the *
The first comment should be a proper comment indicate what the class does and what it is like.
In the final lines should be a @author and a @since tags, describing who designed the class and since when it is a contributor.

// Example

 /*
  * Proper comment on the class like what it does and 
  * if there are design level description
  * 
  * @author <Authorname>
  * @since 2016-03-29 
  */

3.2 Methods Comments

To document a method the /** */ block comment should be used, with every new line precedded with a *.
The first line should only be the /** and every new line should have a space between the * and the first character
The method comment must have a paragraph stating what is the purpouse of the method and it's proper behaviour
There must be the tag @param, if there are any parameters, explaining the meaning of it
There must be the tag @return, if the method is not a void method, explaining what is the returned result
Use tags according to the javadoc documentation

// Example
/**
 * Returns an Image object that can then be painted on the screen. 
 * The url argument must specify an absolute {@link URL}. The name
 * argument is a specifier that is relative to the url argument. 
 * <p>
 * This method always returns immediately, whether or not the 
 * image exists. When this applet attempts to draw the image on
 * the screen, the data will be loaded. The graphics primitives 
 * that draw the image will incrementally paint on the screen. 
 *
 * @param  url  an absolute URL giving the base location of the image
 * @param  name the location of the image, relative to the url argument
 * @return      the image at the specified URL
 * @see         Image
 */
 public Image getImage(URL url, String name) {
        try {
            return getImage(new URL(url, name));
        } catch (MalformedURLException e) {
            return null;
        }
 }

3.3 Language of Comments

The comments should be written in the language used in the code.

3.4 Overridden methods

Must be placed @Override before all the methods overridden.

// Good Code
    @Override
    public void onCreate(Bundle savedInstanceState){
        super.onCreate(savedInstanceState);
    }

// Bad Code
    public void onCreate(Bundle savedInstanceState){
        super.onCreate(savedInstanceState);
    }

3.5 indentation as the comment

The comments should have the same indentation as the code.

// Good Code
    // This method invokes the onCreat parent class.
    @Override
    public void onCreate(Bundle savedInstanceState){
        super.onCreate(savedInstanceState);
    }
// Bad Code

// This method invokes the onCreat parent class.
    public void onCreate(Bundle savedInstanceState){
        super.onCreate(savedInstanceState);
    }

3.6 Start of comment

The comments should start with uppercase.

// Good Code
    // This method invokes the onCreat parent class.
    @Override
    public void onCreate(Bundle savedInstanceState){
        super.onCreate(savedInstanceState);
    }

// Bad Code

    // this method invokes the onCreat parent class.
    public void onCreate(Bundle savedInstanceState){
        super.onCreate(savedInstanceState);
    }

3.6 Type of comment

It has to be used // to comments with just one line and /* ... */ to comments with more than one line.

// Good Code
    // This method invokes the onCreat parent class.
    @Override
    public void onCreate(Bundle savedInstanceState){
        super.onCreate(savedInstanceState);
    }

// Bad Code

    /* 
    * This method invokes the onCreat parent class.
    */
    public void onCreate(Bundle savedInstanceState){
        super.onCreate(savedInstanceState);
    }

3.7 Markers

*To do markers should start with /* TO DO:, followed by the to do message, end end with .*/. Markers comments should use 2 lines of code at most.

//good example

/* TO DO: change dates to positive numbers. */
if(date == -1) {
    date = 11;
    myear = Calendar.getInstance().get(Calendar.YEAR) - 1;
}

//bad example

/* To do: change dates to positive numbers.
 * Change all these dates to positive numbers.
 * Be careful ... */
if(date == -1) {
    date = 11;
    myear = Calendar.getInstance().get(Calendar.YEAR) - 1;
}

Do nothing: every structural condition should have a default behavior, i.e: every if/else if must be ended by else, and switch cases must be ended by default:. In case there's nothing to do in the default behavior, it should be explicit that there is nothing to do by placing a marker: // Do nothing..

//good example

switch (status) {
    case 0:
        dr = getResources().getDrawable(R.drawable.accept_medi_checked_tiny);
        gridcell.setCompoundDrawablesWithIntrinsicBounds(null, dr, null, null);
        gridcell.setTextColor(getResources().getColor(R.color.green));
        break;
    case 1:
        // ...
        break;
    case 2:
        // ...
        break;
    default:
        // Do nothing.
}

//bad example

switch (status) {
    case 0:
        // ...
        break;
    case 1:
        // ...
        break;
    case 2:
        // ...
        break;
}

##4. Exception handling When you finish the try block, the catch must start in the same line with a space of the end of one and the beginning of the other.

// Good Code
	try {
	    selectedButton = v;
	    Intent intent = new Intent(Intent.ACTION_PICK, ContactsContract.Contacts.CONTENT_URI);
	    startActivityForResult(intent, REQUEST_SELECT_CONTACT);
	} catch (Exception e) {
	    e.printStackTrace();
	}

	try {
		// code
	} catch (NullPointerException nullPointerException) {
		// Throw exception
	} catch(RuntimeException runtimeException) {
		// Throw exception
	}

// Bad Code
	try{
	    index = Integer.parseInt( tag ) - 1 ;
	}
	catch ( ClassCastException | NumberFormatException e ){
	    e.printStackTrace();
	}

##5. Good practices

5.1 Commits

Use meaningful commits mensages
Do not commit small fragments of change (Over commit)
Do not add a merge commit

5.2 Fixed numbers

Use constants instead of fixed numbers and strings in the code.

// Good Code
    private final Double INVALID_VALUE = Double.valueOf(91);
    private Double value = INVALID_VALUE;

// Bad Code
    private Double latitude = Double.valueOf(91);

5.2 Methods

A method must do only one task.
Parameters that are not changed within the framework of a function must be passed as a constant

// Good Code
    public View onCreateView(final LayoutInflater inflater, final ViewGroup container, final Bundle savedInstanceState) {
        View v = inflater.inflate(R.layout.intro, container, false);
        return v;
    }

// Bad Code
    public View onCreateView(LayoutInflater inflater, ViewGroup container, Bundle savedInstanceState) {
        View v = inflater.inflate(R.layout.intro, container, false);
        return v;
    }

5.3 Variables

A variable must be declared in the more closed possible scope

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

PCSA Stylesheet

Uh oh!

Uh oh!

Clone this wiki locally