The Importance Of Following Conventions

Consider the following Java code snippets. How are they similar? How are they different? Are either or both of them suitable for production?

/*
 * Program1.java
 */

public class Program1 {

    public static void main(String[] args) {
        System.out.println("Hello World!");
    }
}

// program_2.java
public class program_2
{
public static void main(String CmdLineArgs[]) {System.out.println("Hello World!");}
}

If you know any Java, it should be obvious that both code snippets do exactly the same thing - they both print the text Hello World! (followed by a newline) on the screen. However, only Program1.java is suitable for production - in fact, program_2.java should make your blood boil. So, what is wrong with program_2.java if it does the exact same thing as Program1.java? It does not follow established conventions - for example, the class/program name should be Program2 instead of program_2. So what are conventions and why are they important?

A general definition of "conventions" could be "an informal set of rules that a (programmer) community is encouraged to follow". For example, in Java, the following conventions exist:

• A class name should always have every word capitalized with no delimiters between words (this is known as PascalCase or StudlyCaps). For example, HelloWorld is a good class name while helloWorld and hello_world are not.
• A variable / method name should always have every word except the first word capitalized with no delimiters between words (known as camelCase). For example, main, saveProgress and fileHandle make good variable / method names while SayHello and/or nth_fibonacci do not.
• Constants (variables marked with the final modifier) should be in ALL CAPS with a single underscore as a delimiter between words, e.g. PI and MAX_VALUE are good constant names while Pi and minValue are not.

So, if these rules are merely informal and do not affect the functionality of a program then why should we follow them?

By following established conventions, it makes it easier for fellow programmers to understand your code thus increasing productivity. For example, if every Java programmer used PascalCase for all class names, camelCase for all variable/method names and SNAKE_CASE_WITH_ALL_CAPS for all constant names then when a fellow Java programmer reads the resulting code, he/she can scan through the code quickly by making the following simplifying assumptions:

• If an identifier in PascalCase is seen then that identifier is a class name
• If an identifier in camelCase is seen then that identifier is either a variable name or a method name
• If an identifier in SNAKE_CASE_WITH_ALL_CAPS is seen then that identifier is an immutable constant

In contrast, if some constants were in camelCase while some variables were in SNAKE_CASE_WITH_ALL_CAPS and/or PascalCase as well, then whenever the fellow Java programmer reading your program sees such an identifier, he/she may be required to scan through the entire program (or even an entire project if there are multiple files with imports in between them) in the worst case scenario just to figure out whether said identifier is referring to a class, variable/method or constant. This would greatly reduce the speed at which the fellow programmer can read and understand your code thus reducing productivity.

Of course, conventions aren't limited to naming identifiers or indentation - design patterns also serve as a form of convention. For example, in Java, object-oriented code involving classes upon classes is the norm but if you did the following just to print a Hello World! in JavaScript, you would probably be met with strange looks:

// How NOT to write JavaScript!
// Assuming a Nodejs environment with ES6 or later

class HelloWorld {
    static main(args) {
        console.log("Hello World!");
    }
}

HelloWorld.main(process.argv);

Finally, although it is usually best practice to follow established conventions in whatever language/field you are working on, it may not be applicable in some situations. Take code golfing, for example - when you're trying to minimize the number of bytes in your program to achieve a specific task, all forms of best practice such as descriptive variable names and indentation automatically go out of the window. And while conventions tend to be quite stable, they do sometimes change over time - for example, in PHP, snake_case was previously preferred for function/method names but there is a gradual shift towards using camelCase instead in recent years. The only thing about changing conventions is that if you intend to change a certain programming convention in your field/language, you should always provide a convincing rationale for doing so, e.g. we should use camelCase for function/method names in PHP instead of snake_case because they are shorter to type or we should use snake_case in our project instead of PascalCase because it is much easier to see the individual words immediately when there is an explicit delimiter.