Generally speaking, programming style guide is a written document, containing a set of rules or guidelines used when writing source code for a computer program (it might be an Android app, desktop software or even a video game).
A particular programming style may be different from coding conventions, or even designed around a specific language or even program. For example, what is considered a good practice in C, may not be really appropriate for BASIC.
Why the style guide?
In an ideal world, a product code (or code of different programs created by a particular company) should look like it was written by a single person, even if it was written by hundreds. Conforming to a style guide removes unneeded guesswork and ambiguities.
It also allows for a more streamlined creation of code and its maintenance, because you won’t have to think about the style or how you should name a variable — you simply follow instructions.
Should I create my own style guide?
If you’re working alone, then, most likely, yes. Just write down all of the things, down to the smallest detail, structure it in a logical manner and follow it. Style guides, though, are not set in stone and are rather living documents. If you feel that what you’ve written 5 years ago don’t really work — change it.
But it’s a whole ‘nother story if you’re working with a team. If you come to a new team, you should follow their style guide — no questions asked. You can suggest changes, of course, if you really feel it will be for the better, but otherwise — just work with their style guide.
What should be in the style guide?
Because we’re talking about programing style guide, most of the things should do with the code. Style guide should talk about indentation, variable naming, vertical alignment, even comments!
I won’t dive into details here, because if I were to, it will take pages and pages worth of content. If you want to look at some programming style guides examples, you can check Google’s C++ Style Guide or Epic Games Coding Standard.
But the actual code may not be the only thing in there. Folder naming, their hierarchy, asset naming (images, sounds, etc.) should also be included to eliminate the possibility of any mix-ups or inconsistency.
’Tis a short, but a very important article that, hopefully, will help anyone looking for a simple explanation of what programming style guide is and why every team needs it. If you have any questions — feel free to ask, I’ll be glad to answer!
Have a nice day!
Bradley Nice, Content Manager at ClickHelp.com — best online documentation tool for SaaS vendors