Our team of 12 is currently considering implementing a style guide. The question came up if long term productivity benefits outweigh the short term productivity loss as everyone adapts.
What has been your experience with style guides?
I should also note our code base is rather large and we'll probably have to run our code through uncrustify or something similar to bring the entire code base into conformance with the guide.
My experience has been positive, if the style document is well designed.
I expect to NOT have to think about any white space or indentation rules when I write code, and be able to just use a standard autoformating template. I appreciate the consistency when I read code.
More important than the white space consistency are the usual patterns/designs/name spaces styles. Knowing where you can look for something, and have a good chance to find it - or be reasonably sure it doesn't exist if it's not where you expect it to be is a huge time saver when you're exploring a large code base.
Yes and no.. it depends on the standards. Note that I feel style guides are useless, who really gives a damn how many spaces you have to put between an operator and variable, or how to indent your members.
However, once you assume your coders know their stuff, are professional enough to maintain consistency within a code file (ie will not just reformat everything because of a personal preference) and that any guide you come up with will never be perfect, you can start to crate something genuinely useful.
Standards contribute most when they are about communication. They are at their worst when they are about restrictions.
So a guide that says how to lay your project out, where to find the main project file (.sln or makefile or whatnot), where the entry point is, and how to name the files so that someone coming along can pick up a never-before-seen project and know exactly where to look for the things they need to find... that is worth its weight in gold.
I used to have a standards doc that said you pretty much laid out a project in a certain way - the .sln was included in the directory (ie there was none of this project file and a subdirectory of code), that there was always a release directory containing everything you needed to deliver the component, that every release directory contained a readme.txt that contained a summary of the component, what special stuff you needed to do to build it, and what you needed to do to deploy it. When everyone knew this, you never needed to tell them - I could simply direct a systems engineer at the source repo and they'd be able to deploy it all themselves, no handholding required, and all because of the consistency withi each project. I could direct another dev at the project and they'd be up and running very quickly because they knew how to fit the component into the system and build it, and where the bits of code they needed to look at were (because of the reasonably generic naming convention)
I'm sure you've picked up an open source project and been unable to know where to start, with code files scattered all over the shop, a readme that tells you nothing useful, and no way to find where the output is built to, or how to use it once built.
But at no time did I talk down to my fellow devs and tell them how to write their code, or what their code should or should not look like. Productivity was high and we were all happy with the situation.
If you really want a style guide and you have to run your existing code through a beautifier anyway ... well, you might as well simply run the code through the beautifier before each checkin and let everyone code whatever style they like.
Independent of whether style guides are worth the pain you should consider how you're going to enforce the policy as this will be a larger drag on productivity than learning the guide.
As a C# developer, I'm a proponent of adopting StyleCop as both a compliance tool and using it's rules as a guide. It's a static analysis tool I can run from the IDE which will analyze the source code at a document / project level and list all the violations as warnings. This doesn't prevent me from building, and I don't have to learn the rules beforehand.
