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

Naming Conventions
1.1. Variables
1.2. Constants
1.3. Functions/Methods
1.4. Classes
1.5. XML Elements
1.6. Packages
Layout Conventions
2.1. Indentation
2.2. Empty Lines
2.3. Braces
Member Order
Code Comments
4.1. Inline Comments
4.2. Method and Class Comments
4.3. XML Layout Comments
Error Handling

Chapter 1

Naming Conventions

1.1 Variables

Use camelCase for variable names.
Example:

int userAge;

Reason: The use of capitalization in the middle of the variable helps distinguish individual words. This makes variable names easy to read and consistent with Java’s common practices.

1.2 Constants

Constants should be written in UPPERCASE_SNAKE_CASE.
Example:

final int MAX_SPEED = 120;

Reason: UPPERCASE_SNAKE_CASE makes constants stand out from other elements in the code. Since constants are meant to represent values that don't change, making them easily identifiable helps programmers quickly recognize them.

1.3 Functions/Methods

Use camelCase for method names.
Example:

public void calculateTotal() { ... }

Reason: This helps in naming methods in a way that reflects their actions, keeping your code clean and understandable.

1.4 Classes

Class names should be written in PascalCase.
Example:

public class UserProfile { ... }

Reason: PascalCase improves readability by capitalizing the first letter of each word in the class name. This convention is also a standard practice in Java.

1.5 XML Elements

Use lowercase and separate words with underscores.
Example:

<user_profile> ... </user_profile>

Reason: Using lowercase with underscores ensures that XML names remain consistent and compatible, avoiding case-sensitivity issues that might arise in different programming languages or systems, like Java. Separating words with underscores makes multi-word names more readable.

1.6 Packages

Use lowercase names, with no underscores, following the hierarchical naming structure.
Example:

package com.example.app;

Reason: This is the standard practice for package names in Java and Android to ensure compatibility across different platforms.

Chapter 2

Layout Conventions

2.1 Indentation

Use 4 spaces per indentation level. Do not use tabs.
Example:

if (condition) {
    executeTask();
}

Reason: This creates a clear visual hierarchy in code structure, making it easier to follow.

2.2 Empty Lines

Add an empty line between:

Methods
Blocks of unrelated code.
Example:

public void method1() { ... }  
 
public void method2() { ... }

Reason: Using empty lines to separate different sections of code improves readability. This also helps to separate different sections of your code.

2.3 Braces

Always put the opening brace { on the same line as the statement.
Example:

public class Sample {
    public void method() {
    }
}

Reason: Placing the opening brace on the same line as the statement makes the code more compact and readable, reducing unnecessary vertical space.

Chapter 3

Member Order

The member order defines the structure inside a class, ensuring consistency across the codebase.
Recommended Order Inside a Class:

Constants
Variables
Constructors
Methods: Public methods followed by private methods

Example:

public class Vehicle {
    // Constant
    private static final int MAX_SPEED = 180;

    // Variable
    private int speed;

    // Constructor
    public Vehicle(int speed) {
        this.speed = speed;
    }

    // Public Method
    public int getSpeed() {
        return speed;
    }

    // Private Method
    private void checkSpeed() {
        if (speed > MAX_SPEED) {
            speed = MAX_SPEED;
        }
    }
}

Reason: This logical order helps in understanding and maintaining the code structure.

Chapter 4

Code Comments

4.1 Inline Comments

Use inline comments to clarify complex logic.
Example:

int total = calculateTotal(); // Total amount calculated based on user input

Reason: Using inline comments highlights why certain decisions were made.

4.2 Method and Class Comments

Each method/class should have a Javadoc comment to describe its purpose, parameters, and return value (for methods). These comments help developers understand the purpose and behavior of a method or class without needing to read through the entire code. This is especially useful when working on large projects or when multiple developers are involved.

Example:

In this example, we have a class Order with a method calculateTotal. The method calculates the total price of an order based on the quantity of an item and the price per item.

/**
 * Represents an order in an e-commerce system.
 * The Order class holds details about the quantity of items and price per item,
 * and it includes a method to calculate the total price.
 */
public class Order {

    // Fields to store quantity and price per item
    private int quantity;
    private double price;

    /**
     * Constructor for the Order class.
     * Initializes an order with the specified quantity and price per item.
     *
     * @param quantity The number of items in the order.
     * @param price The price of a single item.
     */
    public Order(int quantity, double price) {
        this.quantity = quantity;
        this.price = price;
    }

    /**
     * This method calculates the total price for the order.
     * It multiplies the quantity of items by the price of each item.
     *
     * @return The total price for the order.
     */
    public double calculateTotal() {
        return quantity * price;
    }

    /**
     * Gets the quantity of items in the order.
     *
     * @return The quantity of items.
     */
    public int getQuantity() {
        return quantity;
    }

    /**
     * Sets the quantity of items in the order.
     *
     * @param quantity The new quantity of items.
     */
    public void setQuantity(int quantity) {
        this.quantity = quantity;
    }

    /**
     * Gets the price per item.
     *
     * @return The price of a single item.
     */
    public double getPrice() {
        return price;
    }

    /**
     * Sets the price per item.
     *
     * @param price The new price of a single item.
     */
    public void setPrice(double price) {
        this.price = price;
    }
}

Reason: Providing a high-level overview of what the method/class does makes it much easier for others to understand its functionality without needing to examine the implementation details line by line.

4.3 XML Layout Comments

Add comments in XML files to explain the section.
Example:

<!-- Layout for the user profile screen -->
<LinearLayout
    android:orientation="vertical"
    android:layout_width="match_parent"
    android:layout_height="match_parent">
</LinearLayout>

Reason: This helps in understanding the structure and purpose of different parts of your XML configuration.

Chapter 5

Error Handling

Specific Exceptions

Use specific exceptions rather than catching or throwing generic exceptions.
Example:

try {
    FileReader file = new FileReader("data.txt");
} catch (FileNotFoundException e) {
    e.printStackTrace();
}

Reason: Using specific exceptions like IOException, SQLException, or NullPointerException provides clear information about what went wrong, making error handling more precise and informative.

Avoid Empty Catch Blocks

Avoid empty catch blocks.
Example:

try {
    // code that might throw an exception
} catch (IOException e) {
    e.printStackTrace(); // Handle the exception
}

Reason: Avoiding empty catch blocks ensures that errors are either properly handled or logged, preventing silent failures.

References

Why Some Conventions Were Not Chosen

For more information on why some conventions were not chosen, please refer to the Why Not Us? We Are Not Standard Enough?.