Should a Statement of Work (SOW) include "coding style" under the Client Obligations section?

Question

I am hiring a contracting firm to rewrite a small application for my group. The dev team is going to be a single person. Based on past experiences with other developers, I'm concerned that the code produced is going to be functional, but inconsistently styled. I'm negotiating the Statement of Work now.

Should I add something to "Client Obligations" about code style? What about requiring use of ReSharper or something similar? Is there sample boilerplate I can use?

I read the related question about a PM enforcing code style on devs; this question is different, in that I'm asking about adding specific language to the SoW.

Answer 1

TL;DR

Should I add something to "Client Obligations" about code style?

You can do this, but you may be measuring the wrong thing. This smells like an X/Y problem: you have a problem to solve with the deliverables hand-off, have decided that coding style is the thing that will fix the problem, and are now trying to solve for "coding style" rather than the underlying process issue.

While agreeing that a consistent coding style is important, define the risks you're trying to mitigate. Then consider focusing your attention on measurable quality metrics and acceptance testing as project controls, rather than style issues as a proxy for your actual risk model.

Think "Quality" and "Definition of Done"

You can put anything you like into a statement of work, but this is not the path to actually getting what you want. I interpret your real motivation as:

1. You want the deliverables to be readable as an aid to maintainability.
2. You consider consistent coding style to be an important element of readability and maintainability.

What you really want to do here is to ensure that the deliverables meet some defined criteria (e.g. PEP-8 or the Ruby Style Guide) as part of the "Definition of Done." The title of the contract section is unimportant; what matters is that you ensure the contract states what is (and is not) an acceptable level of quality for your deliverables.

This is no different than a factory specifying machining tolerances for a widget. However, you need to ensure that your quality criteria are reasonable, concrete, and measurable, rather than simply subjective. This is why the use of a documented style guide is essential; you should not move the developers' cheese after the fact because of undocumented specifications.

Acceptance Testing as an Alternative

A less stringent, but possibly equally useful alternative, is acceptance testing. People often think of acceptance testing as something that end users do to test a user interface or application functionality, but it can also be applied to code readings or rebuilds performed by a development team.

Your style requirements are really just a means to an end: can my internal team, or someone other than the original developer, make sense of the code? The only way to be sure of that is to have another person or team look it over, run the unit tests, compile the code, or try to make some changes. I hereby dub this Development Team Acceptance Testing.

It doesn't matter how pretty the code is. Code can follow style guides all day long and still be poorly documented, needlessly complex, or improperly designed. For example, imagine you want to convert some financial application from dollars to euros; if the exquisitely beautiful code you receive as a deliverable makes it impossible to figure out how to make a basic change like that, then the code is spaghetti code even if it's indented properly.

Of course, these sorts of acceptance tests ought to be part of your documented acceptance testing criteria, and clearly communicated as part of the work to be done. You can't guarantee 100% coverage of every eventuality, but a specification that says:

All magic numbers will be stored as module constants at the top of the module file.

is a whole lot better for everyone involved in the project than:

Make sure your code looks pretty so it doesn't make my eyes bleed.

Be as specific as you need to be, but leave enough wiggle room to ensure that the guidelines don't become a straitjacket. Remember, you get what you measure, and if you measure the wrong things, you'll have some great Gantt or pie charts and a thoroughly useless set of deliverables.

Answer 2

A Statement of Work should specify anything that matters to you. If programming style is on that list, there is nothing theoretically wrong with specifying it, although it opens up the risk of unintended consequences. Other responses have gone into that in more detail.

In a company where I worked until recently, we got tired of web subsites being handed off to us without documentation, dependencies sporadically noted, and the whole not readily integratable into our extent CMS. We decided to provide developers with a clone (via Adobe AMI at the time; now I think the org. uses Puppet) of our system in all of its extant messiness. One condition of acceptance written into the SOW was that the code be checked into a VCS such that we could follow documentation and check it out into another clone of our deployment for testing, then production.

It did add considerable sanity to the end of the process and the "definition of done." It removed many vendors from our list, but also told those who did work with us how to best present their work in a usable fashion.

Answer 3

You can add whatever you want to the SOW that you are trying to control or wanting to require. Whether you should depends on what you will get because of the language versus what it will cost you, the risks you incur because of it, and any other penalty. For example, "client obligations" is a bit ambiguous. How would a developer control for that in terms of his risk, i.e., changing obligations, rock not shiny enough, etc. The developer, because of this language, would build risk into his price. If firm fixed, the price will climb. If too risky for a firm price, then you will need to manage T&M, which is costly and risky, too.

Another example might be a penalty like what might have the developer offered that would prove to be better than your intended obligations. Too much control on how to do it stifles innovation or other interesting ideas.

So you have some analysis of alternatives to do and some really good risk management. If you do the analysis right, score it right, your answer should materialize.