I decided to write a short series of “Effective Programming” tips and for the first article I choose to talk about style guides.
What is a style guide?
A Style Guide is a set of standards for writing and designing code.
How do we format our code?
When talking about style guides, the first question that pops in any programmers mind is “How do we format our code?”. As far as I am concerned this is a boring and stupid question. Go use some formatter that follows a decent set of rules that has be proven to be good enough for large teams. For example Eclipse has a wonderful formatter. If you are not using any formatter, I think you are just sadly in the dark ages. Manually formatting code is painful. The machine is better at formatting code, on average, than humans by a significant amount. I have looked at millions of lines of codes formatted by humans and by robots, robots win. Yes there are some exception to this rule, but on average robots beats developers, so LET IT GO.
What is the Purpose of a Style Guide?
If we won’t talk about formatting, than what are style guides about? As I said a style guide is a set of rules your organization puts out. You should not set rules in your organization without a good reason. Rules have costs. The purpose of a good style guide is to:
- Make it harder for people to do “bad” things, encourage “good” thinks. What good and bad means clearly depends on your organization’s goals.
A good style guide should not list every thing that you shouldn’t do, and should not be perfect. No two developers can agree on a style guide. A style guide should be good enough for all team members. Remember, a good style guide will never fully satisfy all team members but will make sure that everybody is on the same page, it has the minimal set of rules needed to make the code maintainable and to optimize communication between team members (optimize code for reading). Also a good style guide should not ignore the rules that have been proven to work such as SOLID design principles.