PCSA Stylesheet

#PCSA Stylesheet

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

1. Naming
2. Formatting
3. Comments
4. Exception handling
5. Good practices

---

##1. Naming

1.1 Name of the File

All the project files should use UpperCamelCase on its name.

        //good example
	CustomAlertDialogFragment.java

        //bad example
	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 example
	private Vibrator vibrator;
	ImageView[] comradesViews;

        //bad example
	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 example
	private EditText findInput(View view) {

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

        //bad example
	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 example
	public class Confidentiality {
		// Class code.
	}

	public class CircleOfTrustFragment {
		// Class code.
	}

        //bad example
	public class Trustees {
		// Class code.
	}

	public class circleOfTrustFragment{
		// Class code.
	}

	public class CircleofTrustFragment {
		// Class code.
	}

1.5 Acronyms

Treat acronyms as a word.

    //good example
    private String urlQuery = "";

    //bad example
    private String URLQuery = "";

1.6 Constants

Constants must be written in SCREAMING_SNAKE_CASE

        //good example
	public static final int REQUEST_SELECT_CONTACT = 100;

        //bad example
	private static final boolean firstTime = false;

##2. Formatting

2.1 Tabs

Tabulation must be 4 spaces sized

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

        //bad example
	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 example
	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 example
	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 example
	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 example
	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 example
	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 example
	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 example
    String title = getArguments().getString(TITLE_KEY);

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

    //bad example
    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 should not be a space after a method name, if, else if, switch, for, while, try, catch.

    //good example
    public void onClick(View v) {
        // ...
    }

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

    //bad example
    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 comment

• 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

// 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 example
    @Override
    public void onCreate(Bundle savedInstanceState){
        super.onCreate(savedInstanceState);
    }

    //bad example
    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 example
    // This method invokes the onCreat parent class.
    @Override
    public void onCreate(Bundle savedInstanceState){
        super.onCreate(savedInstanceState);
    }

//bad example

// 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 example
    // This method invokes the onCreat parent class.
    @Override
    public void onCreate(Bundle savedInstanceState){
        super.onCreate(savedInstanceState);
    }

    //bad example

    // 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 example
    // This method invokes the onCreat parent class.
    @Override
    public void onCreate(Bundle savedInstanceState){
        super.onCreate(savedInstanceState);
    }

    //bad example

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

##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 example
	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 example
	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