Mysterious Trousers

Quality software and amazing support since 2010

We’re a small team dedicated to making you happy. We achieve this through synergizing analytics and best-of-breed social blah blah blah hard work and honest-to-goodness customer service.

Code Styling and Formatting

Opinion vs Fact

I’m going to share my opinions about some code styling rules and then back them up with facts about why they are more efficient to try and convince you to agree with me.

General

  1. Do not be agnostic about coding styles. Code styles help train your eyes to recognize and read code faster. Everyone should use the same styles per language.

  2. The creator, or the person/group that made a language popular gets to set the coding styles for the language. This includes casing, naming, spacing, etc.

  3. If #2 is impossible, you should do a search on github to find out the most popular styles for the language and use those.

  4. Don’t be an annoyingly stubborn renegade. How you style/format your code has no affect on your ability to write elegant, clean, correct code. (Notice I didn’t say creative code, no one appreciates a creative alternative to quicksort…unless it is actually faster, in which case you’d be famous).

  5. If you are unwilling to break old habits, please resign fom the coding game. Your brain will go stale, get rigid and you will become more and more resistant to things that will make you faster, better and more efficient. It will no longer be able to think out of the box enough to innovate. Change and break habits regularly…hopefully towards greater unity with all other coders. I have a dream where we all can read each others code and think we wrote it.

Specifics

  • Asterisk placement: the asterisk goes by the variable name, not the type. This is not logical, it’s practical. The asterisk is contributing to the type, indeed, good thinking, but because of how pointer languages are designed, a multiple declaration statement needs an asterisk by every variable. Fact: the majority of people put it by the variable, that is reason enough.

  • Alignment: If you have a series common statements, go to the extra effort to align them. Usually this is in the form of aligning equal signs on a series of variable assignments. Fact: if you would rather open a raw csv and scan the data instead of opening it in a spreadsheet application so that the columns are aligned, you are weird and cannot relate with normal people, but please align code anyway to help the rest of us.

  • Whitespace: Again, to help your eyes group things together logically. I saw objective-c code the other day without a single line between methods. It was very hard to scan with the eye. It is also good to add more spacing between supergroups (logical groups of goups. e.g. Classes separated by more space than methods within each class). It depends on the language but 1-2 spaces between methods of the same purpose, 4 between groups of methods, 8 between classes, etc. is very easy to distinguish.

  • Braces: this is the most heated debate, but I’m about to put it to rest forever: both. Assuming the language uses braces, put the brace on a new line if the signature of the block (usually a method or function) is abutted against the left side of the document. Then, braces belong on the same line for everything else, like control statements, blocks, lambdas, etc. A brace on a new line when scanning down a file helps the signature stand out against the code of its body and makes it more visible as you scan down quickly the left edge of the file. If you put braces on new lines for everything, your code starts to look like mostly braces and it becomes too vertically stretched to distinguish groupings by spaces. It also doesn’t look as weird if you omit the braces in the case of a single statement after the control flow statement. Your eyes can effortlessly tell the difference between functions/methods and if/else/for etc.

  • Wrapping: only wrap code if you can do it in a clean way AND only if it goes past ~100 columns. Code that you have to scroll for miles to read is inefficient and people with wrapping ticks keep their code to about 20 columns and it is very difficult to tell where one logical line statement ends and the next begins.

  • Horizontal spacing: always put space between operators and constants. for(int i=0;i<20;i++) is simply cryptic!! Why do we see this so much! I’m embarrassed for us that I have to mention this. Fact: for(int i = 0; i < 20; i++), enough said. Some people go overboard with this, be reasonable, do what’s popular. Lastly, if the parameter of a method is syntactically busy, pad it with a space before the braces so that your eyes can read it as its own statement. No need for simple sqrt(4); stuff.

  • Misc: give up any other weird crap you don’t see anyone else doing, like putting a space before every semi colon at the end of the line. Putting the dot at the end of each line instead of the beginning when method chaining, etc.

Conclusion

No man is an island. Increasingly, you have read others code and, more scary, other people have to read yours. Lets be considerate of one another and write code that we can scan, navigate, distinguish, recognize and read more efficiently because its all consistently styled, logically grouped, spaced and aligned.

© 2013 Mysterious Trousers, LLC. All Rights Reserved. Background photo by hsld