Good Practices in Java and Coding Standards

When it comes to developing software, especially in a language like Java, adopting good coding practices and standards is essential for creating clean, readable and maintainable code. One of the crucial aspects of these practices is the effective use of internal comments to explain complex blocks of code. In this article, we will discuss how internal comments can significantly improve code quality in Java.

Java Internal Comments

Comments are annotations in the source code that do not affect program execution but provide useful information to developers. In Java, there are three main types of comments:

• // Single line comment
• /* Multi-line comment */
• /** JavaDoc documentation comment */

Internal comments are used to explain the "why" behind a block of code, rather than the "what", which should be evident from the code itself. They are particularly useful in complex passages where the logic is not immediately obvious.

Good Practices When Commenting

When using internal comments, it is important to follow some guidelines to ensure that they are effective and do not pollute the code:

• Be Concise: Comments should be brief and to the point. Avoid redundancies or obvious information that can be easily inferred from the code.
• Avoid Unnecessary Comments: Don't comment on the obvious. Comments should be reserved for explanations of complex logic or non-trivial design decisions.
• Maintenance of Comments: Comments must be kept up to date. An outdated comment can be more harmful than no comment at all.
• Use Comments to Mark: Use comments to mark areas of code that need review or have known issues with a TODO or FIXME.

Example of Internal Comment

// Apply Dijkstra's algorithm to find the shortest path
public void dijkstra(int startVertex) {
    boolean[] visited = new boolean[numVertices];
    int[] distances = new int[numVertices];
    Arrays.fill(distances, Integer.MAX_VALUE);
    distances[startVertex] = 0;

    for (int i = 0; i < numVertices; i++) {
        // Find the vertex with the shortest distance that has not yet been visited
        int u = findMinDistance(distances, visited);

        // Mark the vertex as visited
        visited[u] = true;

        // Update the distance to adjacent vertices
        for (int v = 0; v < numVertices; v++) {
            if (!visited[v] && graph[u][v] != 0 &&
                distances[u] != Integer.MAX_VALUE &&
                distances[u] + graph[u][v] < distances[v]) {
                distances[v] = distances[u] + graph[u][v];
            }
        }
    }
    // The distances array now contains the shortest distances from the starting vertex
}

In this example, internal comments explain the purpose of the method and detail each step of Dijkstra's algorithm, making the code more accessible to anyone unfamiliar with the algorithm.

Java Coding Standards

In addition to comments, following consistent coding standards is crucial to code maintainability. Here are some best practices:

• Naming: Follow standard naming conventions, such as camelCase for variables and methods, and PascalCase for class names.
• Indentation: Consistently use spaces or tabs for indentation. The most common convention in Java is to use 4 spaces.
• Code Grouping: Group related code into blocks and use blank lines to separate blocks of code for better readability.
• Code Reuse: Avoid code duplication. Use methods and classes to encapsulate common behaviors.
• Refactoring: Refactor code regularly to improve its structure without changing its external behavior.

By following these best practices and coding standards, you'll be on your way to writing high-quality Java code that's easy to understand, maintain, and expand.