You just need to have a look at any minified JS file to realize how important proper formatting is.I don’t think any one would be able to program a whole system constantly minified, but most don’t give a concerned effort in improving the formatting of their code base, not even using the autoformatting features of the IDEs.
So in order of effort:
- If you are using Visual Studio type periodically Ctrl+K, Ctrl+D. This will auto format the current file giving you a nice starting point
- Install Code Maid. It’s a nice Visual Studio extension that helps formatting your code, you can configure it to do many little things, like grouping methods by its visibility (public, protected, private), removing unused using statements. It’s more powerful than the standard reformatting, and can also be configured to clean up at every save.
Code Maid goes a long way in improving your formatting, but when working on a team, it’s important that most of the team members use it, if not on auto mode, at least before any check-in. Otherwise, the commits done by the team members that use it risk being dirty with a lot of reformatting.
One thing I wasn’t able to do with code maid was enforce the news paper order to my methods. What’s that? Well, you see, a news paper article is organized in a way that first it gives you broad idea, then it goes a little bit in detail, then a little more, and then you get to the full picture.
In code you have high level functions calling low-level functions. So the same principle should apply. At the top of the file you should find the high level methods, then you should go down a level, and keep going till it the end.
Code maid isn’t smart enough to look at who calls who and order the methods with that in mind, but you have a brain and should use it 🙂
Other rules you should keep in mind are:
- Add vertical spacing between concepts
- Group vertically related concepts
- Declare local variables close to their use
- Declare instance variable at the top
- Caller function should be close to callee and should come first
As always dealing with smaller files is easier to apply this rule. As a general guideline, Uncle Bob suggest keeping them at about 200 lines, with a maximum of 500 LoC.
In the same vein he suggest to set a maximum of 100-120 characters for a line of code, while having most of it being less than 60.
indentation is really important to help legibility, so don’t collapse a scope even if it is possible.
|if(value == null) return;|
While it is a valid statement the collapsed block might be overlooked by a reader wasting his time.
|if(value == null)|
|return; //This is more readable|
Remember, trying to trick the 5 lines maximum rule for a function by collapsing statements only hinders the readability of your source file.
One last note, a project should look like it was written by a single individual, it should look consistent. Is not acceptable to have different parts of it have different coding styles. The team rules, so at the start gather your group and decided on which rules to follow, than follow them.
Author: Maurizio Pozzobon
Maurizio has 5+ years developing solutions in the insurance industry. He is passionate about doing the right thing right, so he works in a tight loop with his clients to deliver the best solution possible.