10 Rules for Formatting Your Code
The functionality that you create today has a good chance of changing in the next release, but the readability of your code will have a profound effect on all the changes that will ever be made. The coding style and readability set precedents that continue to affect maintainability and extensibility long after the original code has been changed beyond recognition. Your style and discipline survives, even though your code does not.
- Uncle Bob, Clean Code
When I first started learning to code, my first-ever hacker mentor encouraged me to pay attention to formatting. It was not an insignificant lesson in software craftsmanship. Today, much of formatting-related tasks are outsourced to my favorite Vim command: `gg=G` which indents an entire file. (Note: this command has messed up the formatting of my Speclj file, so it’s not always 💯). Nonetheless, formatting is always a consideration for me.
Here are Uncle Bob’s formatting rules, supplemented with my experience with Clojure:
- Keep files small, which translates to about 200 lines per file (and no more than 500).
- Keep each line to less than 120 characters, preferably less than 100.
- Set blank lines to separate package declaration, the import(s), and each of the functions.
- Variables should generally be placed as close to their usage as possible.
- Instance variables should be grouped into an easy-to-find, well-known place. In Java, variables are found at the top of the page and in C++, at the bottom. In Clojure, I store values at the top, as well (I do this to avoid magic numbers since it provides context).
- If one function calls another, they should be vertically close, and the caller should be above the callee. This isn’t possible with Clojure; you have to define the function before calling it, unless you use a `declare` statement. I try to not use `declare` unless it is inevitable (see here and here). Nevertheless, I keep these functions sequentially adjacent.
- Keep functions close if they are related. For instance, in my `Game Setup` file, I have two methods that essentially do the same thing (they prompt the user, validate the input, and either returns the value of the input or calls a method). They are even affiliated by similarity in function names (e.g. `get-valid-move` and `get-valid-input`).
- You’ll want to have whitespace between operators for readability. Otherwise, eliminate that whitespace, especially at the end of a line.
- Indentation indicate hierarchy and each level (e.g. method names, blocks) should be one indented to the right within a file.
- Eliminate unnecessary, unhelpful alignment that draw your attention to the wrong thing (in this case, variable names rather than type):
Formatting is absolutely important in ensuring that a software’s source code is consistent. There is enough complexity in code; let’s make it easier for ourselves and future developers by maintaining a consistent style. Uncle Bob recommends getting together with your team to decide the basics (location of braces, indent size, how to name classes, variables, and methods, etc). Splendid, Uncle Bob!