Software coding standards template

The software tests and system tests are reduced in one phase The Software Tests Plan is the central document of this phase and verifies the content of the software requirements specifications. The tests results are gathered in the Software Tests Report. If your software is very small and has a very low level of risk then, I suggest you to document it in a single document.

Some reviewers may not appreciate it. So use it if you know what you are doing and if:. Translations: Thanks to the contribution of Valentin Valchev, we have now the All-in-one template translated to Bulgarian:. Thanks to the contribution of Pablo Ojeda, we have now the All-in-one template translated to Spanish:. I invite you to translate the all-in-one template to your mother tongue it's the most downloaded template , I'll add your contribution here.

What I mean by standard development process is the one you find the most in the all the literature about software in medical devices. It is also named waterfall process. The templates below fit best this process. But they may be used for more recent or sexy processes like agile methods. The main principle in all these templates is the traceability of data between each document. From the topmost level data: user requirements to the bottom data: conception units and tests.

Most of documents have at the end a traceability table. These tables are mandatory and you shall fill them to build the tracebility tree of your software. Here is an example of traceability tree. The software development is driven in parallel with the risk analysis and, if necessary, the human factors engineering. Risk and humans factors analysis give mitigations actions, which are inputs to software development. These inputs are traced during all the software development up to the software tests, which are at the end of the traceability tree.

Having all tests passed allow to assert that every input, from user requirements, risk analysis and humans factory engineering, are verified. Software tests and system tests allow to verify the requirements and, by transitivity, the whole system, as shown in the figure below.

You make the validation easier if you defined well the traceability of every input and if you wrote all the documentation during the software development proccess.

Hence, you will have all the proofs to show that user requirements, risks and human factors where well implemented in your software.

There are several benefits in doing it rather then creating your own standards. Taking the four previous points:. You don't need to rewrite StyleCop rules to fit your own standards. I don't say it's hard to write your own rules, but if you can avoid doing it, it means you have more time doing something useful instead. Microsoft's guidelines are very well thought.

There are chances that if you disagree with some of them, it might be because you don't understand them. This was exactly my case; when I started C development, I found a few rules totally dumb. Now, I completely agree with them, because I finally understood why they was written this way. New developers who will be hired in your company later may already be familiar with Microsof's coding standards.

There are some chances that no one will be familiar with your internal coding style. The first important thing to note is that a coding standards document is not about right and wrong. It's not about good and bad or which method is better. A coding standards document's purpose is to make sure that all code is designed, written and laid out the same to make it easier for a developer to switch from one persons work to another without the needed change of mentality to read someone else's style.

How will you name your methods, variables, classes and interfaces? Which notation will you be using? Also something else included in our standards was a split off standards for SQL, so we had similar names for tables, procedures, columns, id fields, triggers, etc.

Will braces be kept on the same line as the opening method line? How should it be used? We have standards to dictate grammatical correctness, and that comments begin on the line before, or after, not on the same line, this increases readability. Will comments have to be indented to the same depth as the code? Will you accept those comment borders used around larger texts?

Also an important thing to note. A good standards document can go a long way in helping review code, does it meet these minimum standards? Don't make it long, and boring, and impossible to get through, or those standards just wont be followed, keep it simple.

I was going through this process multiple times. And the most successful although bumpy anyway was approach was to take "Coding Standards" document from well known company and modify it to fit your needs. I hate most standards documents as they usually try to sweat the small stuff and ignore the bigger picture.

For example, nearly all of them will say how to name variables or place brackets. This is pure style and does little to really help a group of devs code correctly. They ignore stuff like directory structure and code layout. I've seen standards documents that told you exactly how many spaces to put between operators and how many blank lines to put between methods. All of these usually end up with a ton of exceptions to the rule which just shows how pointless they really are, and then they are so big no-one can follow them, which again, makes a mockery of the point they are trying to make.

Now for me, I use many different bits of software from lots of different people and they all have different styles. I simply get used to this, I don't complain that there isn't a common style across all development groups. As long as the code is a common style throughout a project, I really don't care what that style is. So my first rule for all standards documents is: Keep a consistent coding style within the project. Take the religious wars and shove them :.

The second is code layout. When I pick up a piece of code, I want to see that its laid out along similar lines as other, similar pieces of work. If I have a web service I want the name of the wsdl contract to be clear, I want the name of the implementation to be clear.

I do not want someone to come up with a brand new and different layout for files and classes. That means I have to play "hunt the code" which is a nuisance.

If it looks the same as the last project I worked on, I can immediately know where to find what I'm looking for and it is probably the biggest help to working with other people's code that I know. So, keep a structure of how the code is laid out eg Documentation folder for docs, interfaces for interfaces etc - whatever it is that works for you, but stick to it.

Code artifacts should be present too, so you need to say whether the expected error handling is exceptions or error codes - ie. I worked in a place where every project did logging differently - it was pathetic how each code release had to have its own, different, operations document telling the ops guys how to tell if it had gone wrong. Event log, log file in which case where , etc are all valid here. The same applies to other common aspects to code - how to configure it no point using a.

In short, the only thing that matters is Consistency. And as huge standards documents are too much to read and memorise, I prefer to just inform people of the stuff they cannot see eg architectural standards like logging and tell them to keep the code they write consistent with what is currently there.

And if you don't have code already then you don't need a standards document! So take from that the main points: don't try to make a legal document , think of things that aren't just coding but also how the code works and how the code fits with other people's expectations. Then trust people to do good code and you'll see that they do.

Don't, it's an utter waste of time and energy. StyleCop is great and was established over years by people far more experienced and way smarter than you or anyone on your team. Embrace and love it! It guides you continuously, which is better than any document waiting for someone who can be bothered to read it.

Here's an example. I started with a template someone else wrote, but I can't find it, so here it is as I've edited:. These are not to be blindly followed; strive to understand these and ask when in doubt. Sometimes standards are a bad idea. Really try hard not to duplicate the functionality of an existing maintained library or function. If this means making a new repo to share across projects Don't write code that guesses at future functionality. Related Articles. Table of Contents.

Improve Article. Save Article. Like Article. Next Software Engineering Testing Guidelines. Recommended Articles. Article Contributed By :. Easy Normal Medium Hard Expert. Writing code in comment?