Engineering Full Stack Apps with Java and JavaScript
Is formatting your code important? Formatting your code properly is as important as working code. Proper formatting increases readability and hence maintainability, and also give readers the impression that the code was written by professionals. Let us quickly see some of the formatting issues from vertical as well as horizontal perspectives.
Vertical formatting deals with the vertical size and vertical distance between elements. Some of the tips for vertical formatting are worth to note.
Small files are easier to understand than larger files.
Topmost parts of the source file should provide the high level concepts or abstractions and details should increase as we move downward.
There should be vertical openness between concepts. Separate concepts can be separated by a blank line.
Lines of code that are tightly related should appear together with high vertical density. Sometimes useless comments come in between these lines and break this principle. Closely related concepts (variables or functions) should not be separated into different files unless it is really needed. Protected variables act against this principle as they are inherited by subclasses even outside the package. If one function calls other, they should be vertically close. Also the caller should be above callee whenever possible, as it will give better top-to-bottom readability. Related functions should also come closer with high vertical density.
Variables, especially local variables should be declared closer to their usage; however for smaller methods, they may be declared on top of the method. A loop variable may be declared within the loop statement if possible. Instance variables may be declared at the top of a class as it may be used by any method within the class.
Horizontal formatting deals with the horizontal width and horizontal distance between elements.
If you use shorter lines, readers would not have to use horizontal scroll. Width should be around 80 bits or max 120 bits, but not beyond that, according to the book Clean Code.
We can use horizontal whitespace to associate things that are closely related and disassociate things that are weakly related.
int a = b;
mymethod(arg1, arg2);
Though the book Clean Code also suggest special space handling to denote precedence, many IDEs don’t support it.
Indentation is also part of horizontal formatting. A source file contains a hierarchy of scopes like class, method, block etc. Variables declared inside a level of scope hierarchy will be available to its inner scope hierarchy, but not to its outer scope hierarchy. It is a good practice to indent the lines of source code according to their hierarchy levels so that it would be easy to visualize the scopes.
In Java, a block can be considered as a group of zero or more statements between balanced braces {}. A method can also be considered as a block with a name. Variables declared inside any block has a scope and lifetime limited to that block. A variable declared in one block will be available to its inner blocks, but not to its outer blocks.
Class MyClass{
instanceVar;
public static void myMethod()
{
int var1 = 1;
{
int var2 = 2;
}
}
}
Here, indentation clearly gives an idea about the scope of each variable and this can be really helpful when the program becomes bigger and complex. When I first started with C programming in TurboC, my instructor’s first advice was to use proper indentation and I have followed it from then. I too tell my students to properly indent the code from the early stages of programming so that it will become a habit.
There may be situation where the programming language gives you flexibility to not use braces for an “if” or “while” clause, like when there are no more than one line. In this case, it may be tempting to not indent. But for better readability and clarity it is always preferred to do indentation and you may also provide the braces even though it is optional.
You can format your code in eclipse as follows: select the lines of code you need to format, go to Source > Format Element. This will format the code according to the default format settings. You can change the default settings for formatting by going to Window > Preferences > Java > Code Style > Formatter.
You can decide upon a common set of formatting options for your team or project, and get help from IDEs and other tools to enforce it across the project. When using an IDE like eclipse, we can specify the formatting rules, including if we need spaces or tabs for intendation, and also how many space gap we need for each indent.
This note is primarily based on the book “Clean Code” by “Robert C. Martin”.