A software development guideline is a document that determines important rules for the processes, tools, design and architecture used by a team of software developers (programmers, QA folks, product managers…). It is my firm belief that every team of software developers should have such a guideline for the reasons that will be laid out in this article.
Compatible Code
When all developers follow a common guideline they are less likely to write incompatible code. For example in C++ one developer might want to use char pointers, while another might want to use std::string objects to represent strings. This would lead to both types having to be converted between each other at many places throughout the code (by using std::string’s constructor and c_str method).
This situation can be avoided if the developers of the team agree in advance about which string data type they want to use. This decision should be written down in a development guideline (document) so developers can come back to this agreement later. In my experience a simple wiki page is often a good choice, because it can be revised if developers make new agreements or ditch old ones.
These agreements can stretch beyond the code itself. For example programmers and testers might agree on providing an interface for automated testing for their components. They might also involve documentation or resource tracking requirements of work done. It is vital though that these requirements are not found in a process of top-down prescription but by equals agreeing about what they believe would be best for the software at hand.
Commitment to Quality
A very important aspect of a development guideline is that it is a commitment to quality. When all developers articulate what they think is best for the software and their work, write it down and enforce it (together), individual developers have little excuse to write hackish code, skip important tests or “forget” documentation.
This makes it especially important that all developers voiced their opinions and have been part of the final agreement. Otherwise, they could disregard the guideline as something imposed on them, which is not in their best interest or the best interest of the software and project. The creation of the development guideline is just as important as the guideline itself.
Code Reviews
Most of us got (at some point) a code review that is filled with personal preferences of the reviewer, speculations about the future use of the code or remarks about abstract benefits of doing one thing over another. These kinds of reviews often take a long time to resolve and in the end one often feels like having wasted all that time on a very abstract kind of quality. The reviewer might even have good reasons for suggesting the changes, but without them explaining, why something is a good idea the “educational” effect of that review will be minimal.
But what if the development team already talked about what is and isn’t good for the software and their work? What if they wrote down, what they agreed on and why they agreed on it? Code reviews now become much less of a fight about who is right, but is much more of a trial where the submitter’s code is assessed on the basis of a common set of rules (and values). This reduces the amount of discussion taking place in review comments and shifts that work to proper face-to-face meetings, where these matters may be discussed adequately.
Testing
A software development guideline should have a section about testing. It should define what acceptable levels of test coverage are (if you ask me 100% for unit tests [article]), which test framework to use, what testing interfaces the software’s components must have and who is responsible for executing the tests.
The reason I am suggesting this is simple. Testing tends to be forgotten until late in a project if it is not required from the start. Especially more integrative tests are often not implemented early on. A development guideline may help to mitigate this problem by making the expectation about testing clear and encouraging developers to fulfill this expectation before they submit their code. It also helps QA folks to better understand what programmers assume the scope of tests is and the other way around.
Conclusion
As discussed, a software development guideline has many advantages. From code compatibility over individual commitment to quality to earlier testing. The effort for creating such a guideline is minimal, it only takes a couple of hours once and then some time every month to discuss if all decisions still hold or if any new agreements need to be made. Adopting a development guideline is one of the most effective steps in creating an environment in which reliable software is developed.
I hope I was able to convince you, why your software development team and you should agree on a development guideline. Set up a meeting now and discuss with your colleagues what your mode of working should be and expect to reach your goals together more effectively.
