en
de

Rules for Rules

17 September 2014
| |
Reading time: 4 minutes

The Use and the Limits of Process Rules

It is folklore wisdom, especially in software engineering, that repetitive manual tasks are error-prone and should be eliminated as far as possible. After all, this is why we have learned to generate boilerplate code from  domain-specific languages instead of writing it by hand, to employ automated testing, to use static code analysis to detect improper use of languages, to prefer tool-aided over purely manual refactoring, and so on.

Nevertheless, software projects tend to involve process rules that cannot be automated easily. In many cases, the motivation for these rules is easy to comprehend – most of these rules are not arbitrary or pointless at all. Let’s consider three examples:

  • Noone would claim that the idea of a style guide (namely this: ensuring a common style throughout the code base and avoiding well-known pitfalls) is harassment.
  • It is obviously desirable to have commit log rules that allow for features such as automatic extraction of important release notes, tracking of bug fixes with traces to the affected bug tickets, or identification of newly implemented requirements/features (e.g., via tags).
  • A common set of rules for inline documentation clearly helps to produce code that is easier to maintain (for example, a ubiquitous documentation of pre- and postconditions for all functions of a library designed for reuse across several programs).

But even in a situation where each individual rule is straightforward and acceptable, it is imperative to keep the effect of the sum of all process rules in mind.

A Digression to Probability

Let us consider a fictitious software project of moderate size. For the sake of a simple demonstration, we assume the following conditions:

  • There will be 10,000 commits to the code repository over the lifecycle of said project.
  • There are five sets of process rules (rule sets) in effect.
  • Adherence to the rules is not enforced, resulting in a certain chance of error – say, 3% per rule set per commit.
  • Errors are completely independent from each other in their occurrence.

Even though the above conditions include a lot of simplification, an error rate of 3% is still quite optimistic even for a team of skilled and highly disciplined developers. Either way, these conditions lead to the following outcome:

  • Each set of rules will be violated in 300 commits (expected value).
  • The chance of a perfect commit – no set of rules violated at all – is 0.97^5, roughly 86 percent, per commit.
  • The expected value for the amount of faulty commits is about 1413 (more precisely, it is (1-0.97^5) * 10,000 = 1412.659…).

What if there are 10 rule sets to adhere to? Here you go:

  • The chance of a perfect commit is 0.97^10, roughly 74 percent.
  • The expected value for the amount of faulty commits is about 2626 (more precisely, it is (1-0.97^10) * 10,000 = 2625.758…).

Interpretation

The above “number game” does not aim at being a precise prediction; it is merely useful to demonstrate a crucial fact: Having many process rules without tool support comes with a price, and the price is having violations as a common occurrence, not as an exception. You will have your rules violated on a daily basis, period.

There are two fundamental ways of coping with this fact. The first one is extremely simple, does not introduce any effort, and is also completely useless: Namely, blame it on the developers and retreat to your sulking corner. And since this is 1970ies style team management, also make sure to enjoy the brand-new second season of Columbo (out now!).

The other strategy is a bit more sophisticated, and it is slightly more difficult than pushing rules into the team in a fire-and-forget fashion. The idea is to provide useful rules, to include experts in the process, to understand the consequences, and to always consider the feasibility.

10 Rules of Thumb for Creating Process Rules

  1. When designing a set of rules for some activity, ensure that at least one person on the rule-creating committee will regularly have to perform that activity. In other words: Never create rules without involving somebody who will regularly work with those rules in the future. In many cases, it is even better to include the entire team.
  2. Do not only consider the use (or the perceived importance) of a rule. Always include the associated costs in your considerations – the effort of adhering to the rule as well as the likelihood of errors in its application.
  3. If the consequences of a suggested rule set are not clear, perform a time-boxed test run, possibly in a sandbox environment.
  4. Do not resort to black-and-white thinking when it comes to automation. Maybe a rule set cannot be enforced automatically in its entirety, but as an example perhaps 80% of them are easy to automate, 10% are hard, and 10% impossible. What stops you from going for the 80%?
  5. Reevaluate old process rules. Set aside time to re-run rule (2) every once in a while and eliminate the rules that have not proved their worth.
  6. Monitor violations. Do not do this to put blame on individual people, but rather to find out which rules are most error-prone and hence require further clarification or automation.
  7. Make sure to communicate process rules in a perfectly clear fashion. There should be exactly one central place for all process rules in a project, for example a Wiki page that provides links to all sets of rules that are currently in effect (in a tree-like manner).
  8. Absolutely never introduce new process rules by email or IM. Teach your team to ignore any such spam.
  9. Absolutely never ever change process rules without updating the corresponding official documentation.
  10. Document the rules for rules. This will have at least two positive effects: Firstly, it will force discipline on the rule writers, especially the people who suffer from regular visits by the “good idea fairy”. Secondly, it will greatly increase the acceptance of rules in the team. And that alone might reduce the chance of error significantly.

Comments (0)

×

Sign up for our Updates

Sign up now for our updates.

This field is required
This field is required
This field is required

I'm interested in:

Select at least one category
You were signed up successfully.

Receive regular updates from our blog

Subscribe

Or would you like to discuss a potential project with us? Contact us »