Coding Standard 3 - shanjida-alam/Smart-Living-Community GitHub Wiki

Coding Standard 3

Author:

Md. Tanvir Hossain Saon

1. Naming Convention:

1.1 Classes and Interfaces:

Class names should be treated as nouns, capitalized first letters in all internal words, and written in mixed cases. Similar to class names, interface names must also be capitalized. Avoid using acronyms and abbreviations and instead use complete words.

Example:

  • Classes: class Student {}, class Integer {}, class Scanner {}
  • Interfaces: Runnable, Remote, Serializable

1.2 Methods:

Methods should be verbs, written in mixed case with each internal word's first letter uppercase and the first letter lowercase.

Example:

public static void main(String [] args)  {}
void calculateTax() {}
String getSurname() {}

1.3 Variables:

Short yet descriptive names are ideal for variables. They should be mnemonic, making their intended usage clear to the untrained eye. Avoid single-character variable names, except for temporary ones (e.g., i, j, k, c, d, e). Variable names should be in mixed case and should not begin with underscores (_) or dollar signs ($).

Example:

String firstName;
int orderNumber;
int[] marks;

1.4 Constants:

Use underscores (_) to separate words, and capitalize all letters.

Example:

static final int DEFAULT_WIDTH;
static final int MAX_HEIGHT;

1.5 Packages:

Package names should begin with one of the top-level domain names (e.g., com, edu, org) and be written in lowercase ASCII letters.

Example:

java.util.Scanner;
java.io.*;
package com.mycompany.utilities;

2. Comment and Documentation:

2.1 Block Comments:

Block comments should be used for describing files, procedures, data structures, and algorithms.

Example:

/*
 * Here is a block comment.
 */

2.2 Single Line Comments:

Single-line comments can be used for brief explanations of code.

Example:

if (condition) {
    // Handle the condition.
    ...
}

2.3 Trailing Comments:

Short comments can appear on the same line as the code they describe.

Example:

if (a == 2) {
    return TRUE;    /* special case */
} else {
    return isPrime(a);  /* works only for odd a */
}

2.4 Temporary Code Removal:

You can temporarily comment out code using //.

Example:

if (foo > 1) {
    // Do a double-flip.
    ...
}
// if (bar > 1) {
//     Do a triple-flip.
// }

3. Exception Handling:

Use exceptions for unexpected or exceptional conditions, not for flow control. Avoid using exceptions in place of logic checks.

Example:

public class SimpleTryCatch {
    public static void main(String[] args) {
        try {
            int result = 10 / 0;  // Throws ArithmeticException
            System.out.println("Result: " + result);
        } catch (ArithmeticException e) {
            System.out.println("Error: Division by zero is not allowed.");
        }
    }
}

4. Import Format:

Group imports logically. Static imports should follow regular imports.

Example:

import java.util.List;
import java.util.ArrayList;
import org.apache.commons.lang3.StringUtils;
import com.myproject.MyClass;

5. URL Format:

Use the java.net.URL class to represent a URL in Java.

Example:

URL url = new URL("https://www.example.com:8080/docs/resource.html?name=test#section1");

6. Whitespace and Indentation:

Use four spaces for indentation and add enough whitespace between code blocks.

Example:

if (x > y) {
    x = y;
} else {
    y = x;
}

7. Line Length:

Keep lines under 80 characters. Break long lines into multiple lines.

Example:

String longLine = "This is a very long line of code that should be broken " + 
                  "up into multiple lines for better readability.";

8. Braces Usage:

Always use braces, even for single-line control structures.

Example:

if (x > y) {
    x = y;
}

9. File Organization:

Each source file should contain only one top-level class or interface. The class name and file name should match.

Example:

Student.java should only contain the Student class.

10. Favor Composition Over Inheritance:

Prefer composition over inheritance for flexibility.

Example:

  • Inheritance (Less flexible):
class Engine {
    public void start() {
        System.out.println("Engine started");
    }
}

class Car extends Engine {
    // Car inherits Engine functionality
}
  • Composition (More flexible):
class Engine {
    public void start() {
        System.out.println("Engine started");
    }
}

class Car {
    private Engine engine;

    public Car() {
        this.engine = new Engine();
    }

    public void startCar() {
        engine.start();
    }
}

11. Proper Use of Access Modifiers:

Use appropriate access modifiers to ensure encapsulation.

Example:

// Bad Practice:
public int age;

// Good Practice:
private int age;

public int getAge() {
    return age;
}

public void setAge(int age) {
    this.age = age;
}

12. Code Modularity:

Break code into smaller, reusable modules. Each method should have a single responsibility.

Example:

// Instead of doing everything in one method:
public void processOrder() {
    checkInventory();
    calculateTotal();
    applyDiscount();
    generateInvoice();
}

// Break down into separate methods:
private void checkInventory() { ... }
private void calculateTotal() { ... }
private void applyDiscount() { ... }
private void generateInvoice() { ... }

References: