A Manifesto of Done

Posted by Shane Hastie on Mar 19, 2010

Sections

Process & Practices,

Architecture & Design,

Development

Topics

Programming ,

Agile ,

Software Craftsmanship

Alixx Skevington posted a Manifesto of Done as the beginning of a discussion thread, talking about the commitments team members make to each other about the quality of their work and clearly expressing their commitment to delivering business value through the code.

• I will make sure that my code is usable. My code is for use and interaction with other people, and everything I write must make this a pleasurable experience, and reduce workload not increase it.
• I will make the code I write confirm to the style agreed by the team. People other than myself, will be maintaining and amending my code. So while I have flexibility to design and utilise any technology to build my solution. Abiding by the standard while I write this code will allow others to maintain my code.
• I agree to keep my methods to a reasonable size. Large methods are difficult to navigate, and make difficult to debug. As far as possible I will keep my methods to a reasonable size to alleviate this complexity.
• I will comment all code. Whether I am creating new code or altering existing code; I will make short but succinct comments to explain what I have done. So that others reading the code after me understand what I have done and what the code is trying to achieve.
• I agree to unit test my code. I agree to make these tests re-usable and not brittle. I will make the test explain what it is testing and why. So not only will others be able to run my tests when they refactor or fix bugs; they will also be able to see what my code was trying to achieve.
• I agree to maintain the unit tests for existing code. When I alter or add new features to existing code, I will make sure that all the tests pass and that there are new ones for any new feature.
• I agree to try to get my code coverage to at least 80%. By checking my code coverage I will make sure that everything I write has value. That there are no surprises’ in my code that could cause problems later. I will endeavour to get this figure higher.
• I agree to check my code integrates correctly. When I have finished writing my code I will work with the other developers working on my feature to make sure that my code works well with all the other code and that it delivers the requested functionality.

The post generated a number of comments on LinkedIn with suggestions for additional items to be added to the list, such as: 

 

I would add "I will re-run unit tests before check-in". The reason I suggest this is seemingly unrelated code in one place can break tests and/or code in another place. This happened several times at my last job.   (David Kramer)

Re: the bits about unit tests: in fact I would change that to "I will write the unit tests before I write the code", because I'm a big believer in TDD. Another thing to say about tests: they are production code, treat them like it. (Scott Ames)

as for the line about commenting code, I can't say that I disagree more. Comments frequently lie, or just captain obvious stuff (eg. /* set x to y */ x=y;), and always just add extra baggage that has to be maintained in line with the actual code. Good clearly written, clearly designed code doesn't need "succinct comments to explain what I have done" - it's obvious from the code what it does, and the SCM commit comment and version diffs should illuminate *why* it was done. And if it doesn't refactor until it does.  API documentation is a different beast, but this is usually aimed at users of the public methods, not readers of the code files, and it forms part of the released artifacts.

The most important definition of done is implied but merits explicit attention and I'd put it at the top of the list:  * "All Acceptance Criteria defining 'done' for a feature are expressed as tests and pass."   

---

Shane Hastie is an agile coach, trainer and consultant working for Software Education in Australia & New Zealand

1. Back to top

   Too specific

   by Machiel Groeneveld

   If it's a manifesto, it should be general enough to apply to many situations. I really like the "the use of my code a pleasurable experience" because from that many good things will follow.
   
   I would not be so strict on a few other things. Commenting every method and every change? That's sure to make your code unreadable. The code should represent the current state clearly, not convey its history. Furthermore, code should itself be readable, good naming and good practices (such as not returning null) diminish the need for comments.
   
   The code coverage of 80% is arbitrary and should only be attained in situations where it adds value. I'd rather have 60% coverage with good unit tests for the tricky parts than 80% coverage with unit tests of the smoke-test kind.

   Reply

2. Back to top

   Re: Too specific

   by Assaf Stone

   How about, instead of "I will comment every change of my code", say "my code will read as if it were documentation, and everything it does will be self evident?

   Reply

3. Back to top

   Insufficient

   by Charlie Hammell

   If this defines done, then we still only have checked-in, auto-tested code. It has not been auto-deployed to QA, it has not been approved by QA, it has not been approved by the Product Owner, and it certainly has not been staged for production. All of these steps are expensive and expose a multitude of problems that leave developers blissfully ignorant of how un-ready their solutions are for business users. Definition of done: staged for production.

   Reply

• Older >