A few days ago, I talked about reading other people’s code can sometimes feel like a game of Where’s Waldo.  One huge limiter to my ability to decipher the hieroglyphics of a code snippet is how easily I can find the comments or patterns in the nesting of steps. When I was a young whippersnapper of a developer, I would hastily bang out code with a ‘devil-may-care’ attitude towards how I formatted the code or heck my variable naming. Ugh! Now looking back on this, I find that I didn’t really improve my speed but simply artificially slowed myself down when it came time to add new features.  A hard lesson that I had to learn was that comments and consistent styling makes all the difference.

A while ago, I had to check about 20 Chef cookbooks created by some staffers at a client. I went into the exercise hoping and planning that we could simply reuse what they had built for this new internal cloud project.  The client told me that half of the cookbooks didn’t seem to work and wanted me to give them a viability check. Ok, so I dove in heads first to check and verify what was there.  It was pure carnage and took me way longer than it should to check. There were no comments anywhere.  No unit tests. The hardest part was that there was very little consistency in the code. Eventually, we determined that very little could be re-used though the framework was there and could be used as a guideline.  This gave me a great opportunity to help them set up standards on how to write their code. How better to do it then by example?

Before I list my thoughts on standardizing code style, I want to suggest that you also look into any tools that might help enforce those standards in an automated way.  For example, I use Rubocop for any Chef or Ruby work while PsScriptAnalyzer works well for Powershell.  Extremely helpful tool can do the style and lint automatically. Lint is one of the first utilities that did syntax checking and is now synonymous with this type of action. Before you start your next project check to see if there are any tools that can help you automate that verification.

So here are some of my personal guidance:

Tabs vs Spaces: On an episode of the comedy Silicon Valley the main character went on a rant about how tabs take up less ‘space’ in the code because it is on char instead of four and it was a great dialogue.  Here is the thing, it doesn’t matter as long as you are consistent.  Flattening against the left margin of your IDE is also not a good idea but neither is trying to keep track of a 20 tab deep code hierarchy.  So what are my person rules on Tabs vs Spacing.

1. I am a two-space guy and configure my IDE to support it as such.  Just easier and on a small laptop screen I don’t end up with weird wrappings
2. If the hierarchy of my code requires more than 4 indents, then I have gone too far. I should really think about refactoring my code into functions.  More importantly, there is likely a lot of duplication that a simple refactor can DRY up. (DRY stands for Don’t Repeat Yourself).

Variable Naming: This is a very subjective topic and one that can spur many a bar room brawl.  There are many thoughts to how to define variables but I typically style three categories – Function-defined, Global-defined, Global-constant.  Here are my person rules:

1. Function-defined variables should leverage CamelCase.  It is cleaner and easier to see but make sure that you are consistent in the first letter.  You can use UPPERCASE or LOWERCASE but don’t mix the style.
2. Global-defined variables should always start with two underscores e.g __CurrentVar.  This gives me a very quick view to know that it is where I defined the variable but also always me to reuse the declared name as a Function-defined without accidentally ‘overwriting’ a previous declaration.  Some languages like Ruby need to add a special character when declared it as global.  In this case you could forego the underscores but why muddy the waters?
3. Global-Constant variables are tricky but my rule is ALLCAPS. I had an engineer ask me what these ALLCAPS variables were in some of my code and I explained it this way.  When I see a variable in ALLCAPS, I know exactly where how I declared it and that it is a variable that should never be recast. It is part of the base elements of my code and reserved for components that would never be subjective to environmental changes… or it could be an ENV.  Either way, these are typically variable cast from a configuration file or some other external declaration.

Single vs Double Quotes: It doesn’t matter but some of the style tools will enforce this one.  My personal habit is a single quote for simple text while using a double quote for interpolated strings with variables.  Simple and effective and just keeps things nice and pretty.

Method and Function names: Depending on your language of choice, this could mean different things.  Ruby and PowerShell have very different naming requirements.  For Ruby, I tend to go with all lowercase and leverage underscores between the words.  In PowerShell, I follow the cmdlet formatting option (PSVerb-FunctionName in CamelCase).  I typically start the function name with the verb that the function will execute e.g. create, get, set, destroy, mock. This makes reviewing the code and the later call to the function easier to understand later.

My goal is to help you later review and change your code.  A consistent coding habit makes life so much easier six months from now when you need to go fix a bug or make a change.  It starts small but when you make it a habit then it won’t matter if you are writing a small 20 line script or a 10k line program.  Tomorrow, we are going to talk about source code control and good habits in your commits and messages.  I hope that this was helpful and see you tomorrow.