Time

The first key is to make time to write. Ideally this should be a decent period of time each day during which you are undisturbed and at peak mental capacity.

The minimum period of time that I find effective is usually around 15 - 30 minutes. This is because it sometimes takes time to get into a good flow of writing. The maximum period of time that I find effective ranged from 45 minutes to 1.5 hours. This maximum is based on how well I can maintain my flow of writing and my motivation / discipline. If I get stuck, especially on a new section for which I do not have a clear outline, I tend to stop and let it percolate in the back of my mind. The longer the writing session goes, the more likely I am to run out of steam (motivation / discipline) - e.g. by getting distracted by email or my RSS reader. I find that practically this means that I am generally unable to continue writing for more than 1.5 hours.

So how do I find the time to write? I get up early each morning, before the rest of my family, and use the time to write. I sometimes write in the evening, but I find I often do not have the mental energy for this after a long day at work. So I tend to save the evenings for other activities, such as exercising, and dedicate the mornings to writing. Successfully doing this day after day takes motivation and discipline.

Motivation

The second aspect of my system is maintaining a high level of motivation. I have found that if I am not motivated to write regarding a particular topic or section then my progress is usually quite slow and I am easily distracted.

One way I keep my motivation high is extremely simple: I primarily choose topics that I am motivated to write about. When a new idea comes along, motivation to write about it is usually quite high initially and decays over time. So the ideal is to start writing about such ideas immediately. Other times I am wrestling with a topic at work or researching it on my own and gain some insights that I feel like sharing.

My motivation in these cases is linked to the goal of helping others learn and grow, which is part of my professional vision. In some cases, as I have started writing about an idea, I realized that I only had a sentence or two of meaningful content, which by my standards is not enough to share via an article. This typically rapidly deflates my motivation, and I move on to a different idea.

This concept of linking the act of writing to the achievement of a larger, more personally-meaningful goal is another valuable technique for boosting motivation. In the last year I have started to tackle some larger projects (which is one reason for the decrease in my posting frequency), and I find that having this linkage is extremely powerful in maintaining motivation over the long term. Having this motivation helps in dedicating the time to write.

Motivation is powerful, but it tends to fluctuate. When motivation fades, discipline is needed to maintain consistency of purpose.

Discipline

The final key to my system of writing is discipline - consistently applying deliberately-designed techniques and practices that help me write. Discipline has also helped me discover these methods through ongoing reflection and improvement on what is working versus what is not

A large part of discipline is consistency, which helps build up productive practices into positive habits. One example is my practice of getting up early each morning to write - I do this every morning, weekends as well as workdays.

I have found that there is an initial hurdle to overcome when sitting down to write, especially if I am struggling with a section. This difficulty often caused me to switch to email or the web as a distraction from which I tended not to emerge, resulting in me making no progress for that block of time. One practice I have developed to overcome this is to have a firm plan in mind the night before of what specifically I am going to write the next morning. As I get up in the morning, I immediately begin recalling my plan as a way to help prime my mind for action. Not only does this help me stay focused, but I also find it reduces the start-up time necessary to get into the flow, thus allowing me to be productive with even a short block of time.

Outlines are another practice I regularly use, even for short pieces of writing such as this article. These outlines are often quite informal, focusing on the main points I plan to write about. The purpose is not to identify all the content, or how it is organized - I often add more points that come to mind as I write, or restructure as the material comes together. Instead, I use outlines to help eliminate one of the causes of getting stuck - not knowing what content to write about. (It is still possible, unfortunately, to get stuck regarding how to write the content.) Outlines are also helpful in dividing the writing into sections: each section acts as a mini-milestone that I can aim to complete during a writing session, thus helping me remain motivated to write.

I have a technique for maintaining the flow while writing and minimizing distractions that involves the use of 'todo' labels. The general idea is that when I identify something to do or consider that falls outside my current focus, I document it with a 'todo' prefix. This keeps it preserved for later action, which helps to get it out of my mind now. Here are some common examples of how I employ this technique:

• When I want to link to an article on my website or elsewhere, I leave a 'todo'. Finding the link is often quite quick, but I do this to avoid distractions.
• When I have an idea for a piece of content for a future, unwritten section, I jot down a brief note with a 'todo' in that section, then return to what I was writing.
• When I get quite stuck on a particular paragraph or section, I leave a 'todo' comment and switch to another area. This is especially common when I have a long list of points outlined: I start writing the points for which I have the most motivation, leaving 'todo' flags on ones I skip. I then use the momentum I have built writing these more motivating points combined with the promise of almost being done them all to return to these few remaining points and grind them out.
• When I have an outline consisting of sections, like this article does, I start by writing down the section headings with 'todo' labels on each. This serves as a road-map for me to follow while writing. It also helps me see the overall structure of what I am writing.

This is my system for writing - it may not work for you. But I do suggest at least experimenting with some of these techniques and practices if you have not tried them before. I encourage you to leave a comment describing what practices or techniques you have found helpful.

While the term agile itself is indeed ten years old, the philosophy and approach of iterative and incremental development (IID) has a surprisingly rich and extensive history. The article Iterative and Incremental Development: A Brief History (PDF) by Craig Larman and Victor R. Basili published in IEEE Computer discusses how the ideas of IID actually predate the existence of software, and have been used and promoted in every decade since for over 50 years. This article also discusses a classic 1970 article by Winston Royce well-known for supposedly promoting the use of waterfall, but which actually recommended the development of an initial pilot or preliminary version prior to creating the final version intended for delivery to the client. Larman's and Basili's article also discusses the ongoing evolution of the standard used by the U.S. Department of Defense for software development. The initial standard was document-heavy, gated, single-pass waterfall, but the high rate of project failures led to first the allowance of and eventually the full adoption of IID approaches.

So a limited set of organizations (often governments due to their byzantine contracting restrictions) did experience an evolution from waterfall to agile over time, but notably they started with a misunderstood version of waterfall. The use of IID approaches has always been part of the I.T. industry.

What about the effectiveness of agile? The second article Quality metrics: Software quality attributes and their rankings is an interview with Capers Jones and Olivier Bonsignour regarding their new book The Economics of Software Quality. The authors in this book discuss the effectiveness of over 100 quality factors using research based on over 10,000 software projects. On a scale of -10 for extremely harmful to a scale of +10 for extremely valuable, Agile methods rated a 9 - highly valuable - while waterfall only rated a 1 - barely useful.

These two articles highlight the fact that agile-like methods have been in use since the start of the software field, and are on average far more effective than the waterfall approach. This leads me to conclude that there is really no defensible reason for organizations to mandate or promote the use of waterfall.

Too often I see projects and even entire organizations misaligned with one or more of these principles and in the worst cases taking actions in complete violation of these principles. The result is predictable: poor quality or significantly extra cost to achieve adequate quality, with the complete absence of high quality.

Achieving high quality is difficult. It suffers from what I call the weakest link problem: no matter how many things you do well, it is the area you are poorest at that generally dictates the overall quality. Another way of putting it is this: there are many ways to fail at developing high quality software and only a few ways to succeed.

So to help you achieve high quality here is my list of the top seven quality principles in software development. For each principle think about the implications - how might your organization be acting in ways that contradict it? How might you change to better align with the principle?

People as individuals and teams are the most significant factor affecting quality

Software engineering research has consistently found that variations between people are by a large margin the single largest contributing factor to quality and productivity. While good process is important, good people have a much greater impact.

Achieving high quality requires people capable of doing high quality work, both individually and as teams. While individual excellence is important, most software is produced by a team of people and it is the team's overall quality of workmanship that ultimately determines the quality of the software being produced.

Within organizations, throughout the blogosphere, and even in many software development books too much attention is placed on process and methodology and too little on the quality of the people doing the work.

All software has defects

Any significant piece of software has defects, no matter how carefully it has been produced. Zero defects is an Utopian ideal, but not a realistic goal. With extreme discipline and effort you can get very close to zero defects, as evidenced by the group working on the space shuttle control software, but under more normal conditions defects are unfortunately a fact of life.

It is impossible to fully test software

For even the most trivial of functionality like adding two numbers there are a nearly infinite set of tests that could be performed. So completely testing a significant piece of software is impossible. Testers therefore must appropriately choose and perform an extremely small subset of all possible tests.

Defects are more expensive to fix the later they are found

As time elapses from the point at which a defect is introduced, the effort required to fix the defect grows. There are several reasons for this. The most significant is that as the software moves through subsequent phases of the software development life-cycle - from development into test and then finally into production use - the effort involved to get to that phase increases. Work previously done, like testing and deployments, has to be repeated to some degree. Another reason is that over time, the developer's memory of the problematic functionality in question fades, thus requiring more effort to recover the context.

Build quality in

This principle comes from the lean thinking literature and addresses the issue highlighted by the prior principle. Finding and fixing defects is considered waste - non-value-add work - and thus according to lean should be minimized. This is accomplished in a twofold manner: first, use practices that help prevent the introduction of defects, such as specifications with examples, and second use practices such as test driven development and code reviews that find defects as quickly and cheaply as possible after they are added.

Adopt your approach to quality based on the level of criticality and complexity

Different contexts require different actions. Criticality and complexity are the two most significant factors to consider in order to determine the level of quality you require and the approach you will take to achieve it. Criticality is the measure of how important the application is to the business and/or the users and is generally assessed using categories such as life critical, mission critical, business important, and casual use. Complexity is the measure of how difficult it is to understand and work with the code. A number of factors increase complexity such as complicated algorithms, sheer volume of code, and poor architecture resulting in high coupling.

Higher quality requires more quality-focused activities and better execution

In order to achieve a higher level of quality corresponding to a lower volume of production defects requires that you introduce less defects and/or find and fix more defects throughout your software development process. This process can be modeled as a series of activities acting as feedback loops or filters that each prevent or remove some percentage of defects.

Using this model it becomes obvious that the only way to reduce the defects remaining at the end of the process is to either make existing activities more effective - what I call better execution - or add more activities to filter out additional defects. The choice of which quality-focused activities to use and the effort to put into each requires deliberate planning which I have written more about in my article titled Filter by Failure Mode Matrix: A Method for Planning Quality.

One approach for doing this selection is a method I call the Filter by Failure Mode Matrix. The basic idea behind the matrix is to identify the activities and practices that will act as filters to either prevent or mitigate quality-related failure modes in the software development process. This is inspired by failure mode and effects analysis except it is applied to the development process itself rather than a piece of software. The categorization of failure modes in the matrix should be as broad as possible to minimize the size of the matrix, while remaining specific enough to effectively identify specific activities and practices that will be effective at preventing or mitigating each failure mode. Many of the failure modes correspond to defect root cause categories.

The matrix defines two sets of filters for each failure mode: primary filters and secondary filters. Primary filters consist of those activities or practices that the team will rely on as their first line of defense in preventing or mitigating the corresponding failure mode. Secondary filters act as a second line of defense for those issues that make it through the primary activities. The activities and practices assigned as a secondary filter are either less effective in preventing or mitigating that particular failure mode, cost more to perform in terms of budget or schedule compared to the primary filters, or are performed later in the overall development process compared to the primary activities. When the primary filters consist solely of activities performed by developers, then the secondary filter should include activities performed by non-developers in order to serve as an independent assessment of quality with respect to that particular failure mode. This is especially important for mission-critical and life-critical systems.

Multiple activities can be listed as primary filters or as secondary filters. The intent is not to require only a single activity per filter category. In fact, to obtain higher quality research tells us that multiple quality-enhancing activities are a necessity.

While most failure modes have general applicability, some are more contextually-dependent so you should ensure that the list of failure modes you use is meaningful to the particular software development effort you are undertaking.

Both the relevant failure modes and the effectiveness or applicability of quality-enhancing activities and practices can vary significantly based on the nature of the application functionality. For example, web-based user interface screens will experience usability defects and automated functional testing is more difficult to apply. In contrast a scheduled batch process does not need to worry about usability defects and automated functional testing is usually much easier to apply. So when a system combines multiple components that differ like this, this can be handled in one of two ways. First, a single matrix can be used with additional failure modes representing the two different components. Based on our above example, you could have a failure mode for web-based functionality defects and a second category for batch process-based functionality defects. This allows the latter category to specify automated functional tests as a primary filter. The second approach is to define separate matrices. This should only be done when there are significant differences between the matrices.

While a filter by failure mode matrix can be defined up front, you should expect to evolve it over time. Examples of how a matrix can evolve are:

• A particular activity is found to be ineffective and is replaced with another activity in the matrix.
• A new failure mode is identified based on defects that occur in user acceptance test or production. A new row is added for this failure mode with corresponding filters identified.
• The overall quality level is discovered to be too low, so additional activities and practices are added throughout the matrix.

The following table provides a sample filter by failure mode matrix.

One solution to this problem that I have worked with and now recommend is to use a feature done checklist to track the completion of the definition of done for a specific feature. At its essence the checklist consists of the major elements of the definition of done listed as rows in a table with additional columns for the person verifying the completion of the item to enter their name and date. Here is a simple example:

You need to decide whether to use digital or printed checklists. I prefer using paper-based checklists for several reasons:

• I find it more meaningful to sign a piece of paper than to add my name electronically, so I tend to treat the completion of the checklist more seriously than I would an electronic form. This attitude may be due to my engineering background.
• A paper copy is more tangible and real. It can be waved around at a team meeting to celebrate the completion of a feature or posted on a team wall. It can be placed on a coworker’s keyboard in order to focus their attention on an outstanding item.

Evolving the Checklist

I have found it useful on occasion to evolve the basic feature done checklist beyond the team’s definition of done to provide support for the team’s development process. This is usually done as part of continuous improvement to resolve issues identified during retrospectives. Here are some examples:

• On one project we had issues with developers rushing into coding new features without fully understanding the requirements, so we added an initial checklist item for feature clarification to focus attention on the activity.
• For each item you can specify the role (e.g. developer, tester, architect) responsible for signing that it is done. I strongly recommend doing this for two reasons: it minimizes confusion over who signs off each item, and it minimizes the problem of having the developer of the feature quickly sign off all the checklist items without doing the necessary checking so they can say the feature is done.
• You can specify dependencies between the items. On one project we had a problem with people treating the items as a linear sequence of activities, so we defined dependencies to explicitly show that some activities could be done in parallel.
• You can add a feature start date to indicate when work began on the feature. This in combination with the feature done date allows you to calculate the duration of time spent on the feature. In lean terminology, this gives you the cycle time for the feature, which you want to minimize. When aggregated across the team, this defines the team’s overall throughput in completing features.

Checklist Challenges

I have encountered a number of challenges when using feature done checklists. Some of these issues are due to the actual checklists, but many are actually due to using a strict definition of done – the checklists just make the issue visible.

1. The checklist needs to be meaningful to the team - you must avoid the risk of it just becoming a form that people sign without doing the necessary work / checking that the item entails. (This is sometimes called rubber-stamping or pencil-whipping.) I have used many strategies to mitigate this risk:
   • Use a paper-based checklist rather than electronic.
   • Keep the checklist to a single page with as few items as possible for each role to complete.
   • For items involving ‘checking’ activities, assign these to roles / people whose primary responsibility is checking, separate from the developers doing the coding.
2. Extra effort is involved in getting a feature fully complete. This is often not accounted for in estimates, particularly if the estimate is provided by the developer. The time required for checking by other roles can be accommodated by having separate estimated tasks for these activities. What I find particularly challenging is accounting for extra time needed by the developer to resolve issues found in reviews or testing.
3. Having a through definition of done with multiple hand-offs of the feature to various roles will typically extend the duration of time required to complete the feature. The mitigation is to allow as many items as possible to be done concurrently. The best example is using pair programming as the means for doing the peer code review.
4. A single role / person with multiple review items per feature can end up becoming a bottleneck that ends up delaying feature completion. This is especially problematic if you are using a methodology like Scrum which focuses on getting features (user stories) done within the iteration – you tend to get a backlog of checklist items forming at the bottleneck near the end of the iteration which jeopardizes their completion.
5. One problem with using paper-based checklists is that they can get misplaced, or you end up looking for who has a form. This can be addressed by defining a location for checklists to be returned to. One option I like is to post them on a team wall, which provides the additional benefit of visibility.

The idea of to do comments really only makes sense with the proper tooling. The Eclipse integrated development environment calls them task tags, and supports providing any number of custom identifiers that when found in a comment will cause Eclipse to add that comment into its Task view. The default identifiers that Eclipse ships with include "FIXME" and "TODO". You can then browse the task view, sorting or filtering the tasks by various criteria, to see the outstanding work. Continuous integration servers such as Hudson running the Task Scanner plugin can produce statistics, reports, and graphs of the outstanding tasks in a code base.

Why use to do comments?

When doing my own coding, I use to do comments when ideas come to me regarding code I need to write or special cases I need to handle that are separate from what I am coding right now (usually in order to get the current test to pass, via test-driven development). Writing the idea down gets it out of my mind and out of my way. Using a to do tag reassures me that it will not be forgotten: part of my definition of done is to ensure that there are no to do comments remaining in the code.

When looking at code written by other team members, I want to be able to quickly tell what state the code is in – is it completely finished, or is it a work-in-progress, with scenarios or requirements left to be handled? The reason I care is that if I think the code is supposed to be finished, and see issues or outstanding work, then I will raise the issue(s) with the developer. Fairly often when I have done this in the past, the developer reassures me that they were already aware of the issue and would resolve it. That is usually when I recommend the use of to do tags as a communications mechanism to the rest of the team as to the status of the code, especially if someone else had to take over working on that code. And as often as not, unrecorded issues that developers say they are aware of and will resolve later end up being forgotten and left unresolved.

I hope I have convinced you of the value of using to do comments. Please leave a comment and let me know what you think about the practice.

This rule is based on a bottom-up engineering philosophy: if you completely understand the methods you are invoking, then you should understand the behavior of the method you are coding and know that it will work. This applies recursively up the call stack to the top-level entry point of your application.

Key Requirements

My formulation of the rule above specifies two key requirements for using another method:

1. Behavior Understood: The behavior of a method can be defined in terms of its pre-conditions and post-conditions. Knowing the pre-conditions allows you to ensure you are correctly invoking the method, while knowing the post-conditions ensures that you will get the results you want.
2. Confident Will Work: This is arguably part of the prior requirement - understanding a method’s actual (rather than stated or expected) post-conditions - but it is so important I felt it should be explicitly stated. You need to verify that the method you are using will actually function correctly and not fail due to a defect. This verification is best done via automated tests, but there are scenarios I discuss below when another approach is needed.

Applying the Rule

Applying the Use Understood Methods Rule involves, therefore, satisfying these two requirements. Exactly how I do this varies based on the context – specifically the nature of the method I intend to use. Below I describe the common scenarios I encounter and the approach I use to apply the rule to each.

• Method with implementation in code base: Calling a method that has an existing implementation within the code base you are working on is the most common scenario. This can be a method on the same class, on a super class, on a collaborating class, or a static method. This also can be an abstract method defined on an interface or abstract base class for which the implementing class exists and is known. To understand the method’s behavior I refer to the documented pre- and post- conditions if available, otherwise I look at the source code for the method. The correctness of the method should already be verified through automated tests. If necessary I can use code coverage analysis results to confirm that this method has sufficient test coverage.

• Method to be written concurrently in code base: Often when coding a method, I find I have to create a new method, either on the same class or on a separate class. This might be a simple extract-method refactoring of logic to simplify the existing method, or it might be new functionality required on another class. In this scenario I have no issues understanding the behavior of the new method as I am writing it at the same time. If the new method is non-trivial then I ensure it works by creating unit tests for it separate from my tests for the original method I am working on.

• Method with unknown implementation in code base: This applies to abstract methods in interfaces and abstract base classes for which no implementation yet exists or for which the implementation cannot be known in the context of the method being written. This latter scenario is typical when there are multiple implementations being processed in a common fashion. In this case I insist on having documented pre- and post- conditions for the method being invoked.

  If the method implementation does not yet exist then it is obviously not possible to verify now that it is correct, but it is possible to take steps to gain confidence that the implementation will work once it is written. One option is to ensure that the automated tests for the method you are writing that invokes this not-yet-implemented method sufficiently exercises the functionality of this not-yet-implemented method to ensure it will meet your needs. Another more general option is to ensure that the team has processes in place such as test driven development and code reviews to ensure that code written in the future will indeed work.

• Method in third-party code: When using third-party methods I usually rely on the documented API. When this is inadequate I look at the source code if it is available (this is a key benefit of open source libraries – the code is always available). In some cases the third-party software implements a specification (such as the various Java EE specs) and the specification can be used to understand what the third-party code is supposed to do.

  Once third-party software has been selected for use within a project I generally assume it works. The verification of the quality of such software happens previously, in the selection process, when I do my due diligence to evaluate the quality of the software under consideration.

  On rare occasions I write a unit test to understand and/or verify how some third-party functionality works. This is something I would probably benefit from doing more often.

Given the prevalent use of automated tests to verify correct behavior, you might be wondering how the application of this rule is impacted by the use of test driven development (TDD). The short answer is there is no impact: this rule applies the same whether or not TDD is being used. I do, however, slightly revise how I do TDD in order to apply this rule for the scenario Method to be written concurrently in code base - I create a second failing test before creating the new method. For further details see my article describing this refinement to TDD.

The Broader Context

Following the Use Understood Methods Rule is necessary for creating high quality code that you would trust your life to, but is not sufficient. Correctness also depends on satisfying class and application-wide invariants (such as properly closing database connections or limiting the number of file handles consumed concurrently), understanding the behavior of containers and frameworks (such as the Spring application context or Java EE container), and considering other quality attributes (such as security and scalability) which are and emergent in nature and not easily analyzed by looking at methods independently. I consider my rule to be the foundation on which the code is written, which these more global concepts rest on top of.

I use two guiding principles as the basis for constructing my definition.

1. Potentially releasable: Ideally the software can be released (or shipped) once it is done. I've seen many people, particularly in the context of Scrum, use the similar term "potentially shippable".
2. I would trust my life to my code: I just wrote an entire article on this titled Would You Trust Your Life To Your Code?

These principles are deliberately idealistic in order to set high expectations and motivate continuous improvement when I fall short of reaching them.

Different definitions of done can be created based on different levels or scopes. The two primary scopes are:

1. Done for a feature / user story.
2. Done for a release.

For this article I am using my definition of done for developing a feature (user story).

My definition of done is essentially a checklist with items grouped into categories. The lists of items and categories are not meant to dictate the process by which these items are done or the chronological order. For example, automated unit testing is listed in a separate category from coding but it is typically done at the same time or before-hand, if doing test-driven development.

Without further ado, here is my definition of done.

Coding

1. Code meets functional requirements.
2. Code meets non-functional requirements. Typical ones include:
   • Performance (capacity, scalability)
   • Usability
   • Security
   • Maintainability
3. Code is deployment-ready. This means environment-specific settings are extracted from the code base. A past article I wrote on designing for deployability provides more context on this.
4. Code is checked into version control.
5. Code complies with coding & architectural standards.
6. Code has been cleaned up. The goal is to ensure the code is easily readable and has a good design. In the past I have used the terms polishing code and refactoring to describe this. Robert C. Martin's book Clean Code: A Handbook of Agile Software Craftsmanship provides the best explanation of this that I have seen. Achieving this goes a long way towards meeting the maintainability requirement.
7. All TODO-style comments in the code have been addressed and removed.

Static Code Analysis

1. Code has been analyzed by static code analysis tools. The two primary tools I use for Java development are the Eclipse compiler and FindBugs. Other Java tools include PMD, Checkstyle, and Architecture Rules.
2. All errors and warnings found by the tools have either been corrected or have been suppressed with a comment indicating the reason for suppression.

Testing

1. Automated unit tests are written. The tests should be high quality (e.g. not brittle).
2. Automated integration tests are written that verify interactions with external systems such as the application database or third-party application / web services.
3. Code coverage achieved by the automated tests is measured and sufficient coverage is achieved. I use Cobertura for measuring code coverage. I do not like using only a numeric percentage coverage target as the sole definition of sufficient coverage, because this can encourage people to write poor-quality tests that merely execute the code rather than verify its correct behavior in order to meet the target. My true definition of sufficient coverage is that the tests execute and verify all code that could reasonably be incorrect. Having said this, I generally aim for at least 80% line (statement) coverage overall, and often achieve 90%+ coverage for individual classes. I am still debating what a reasonable target is for branch (conditional) coverage . I currently aim for at least 50% overall, but I have the feeling that a target of 75% would be better.
4. Functional testing by someone other than the developer has been done. Ideally this testing will be done by the customer, involve exercising the complete feature being coded in the way that users would use it, and be fully automated. More frequently I have seen this testing done manually (especially for user interfaces) by business analysts or testers who act as proxies for the customer. The key idea is to have someone other than the developer do testing to validate the assumptions and interpretations made (often implicitly) by the developer.

   I use the vague term "functional testing" rather than the more common terms "system testing" or "user acceptance testing" because projects can differ dramatically in what is done for system or user acceptance testing. If acceptance testing is done in a waterfall fashion as a separate phase near the end of the project then it cannot be part of the definition of done for a feature (but it is still part of the definition of done for the release). So I use the term "functional testing" to indicate this potential differentiation. Ideally, based on lean principles, all testing including system and user acceptance testing should be done as part of the work on a feature and not artificially delayed till later.

Reviewed

1. Design / approach has been reviewed by the technical lead / architect.
2. Detailed peer review / inspection has been done. If pair programming is being used then the peer review is automatically done at the same time as the coding. Otherwise, the reviewer should focus on issues that are less likely to be found by the static code analysis or automated testing. This can include items such as security holes, concurrency issues, and correctly meeting requirements.
3. Issues identified by reviewers have been resolved to the reviewer's satisfaction.

Other

1. Required documentation has been updated. This may include online help, user manual, or operations manual.
2. Build and deployment scripts and related configuration files have been updated.
3. No known defects are outstanding unless the customer has agreed to defer them, in which case they should be logged.
4. No known tasks related to the feature are outstanding.

That concludes my definition of done. I would appreciate hearing about what you use for a definition of done. In particular, if there is anything you think should be added or removed from my definition please let me know via a comment below.

Why is having a definition of done so valuable? I have grouped the benefits it provides into the following categories:

Higher Quality

Definitions of done should typically focus less on the activities people normally do and focus more on the activities that tend to be neglected or forgotten. In software development this means specifying activities that ensure the quality of the code being produced, rather than the actual act of coding. Quality often means much more than just few defects: it can also mean readable code, a clean design, or achieving any number of other non-functional requirements such as security, performance, and scalability. A definition of done that includes quality aspects serves, therefore, as both a reminder of the importance of quality in the day-to-day work and as a set of expectations regarding the level of quality to strive for.

Out of curiosity I decided to check out a number of publicly available definitions of done and count the percentage of items that clearly related to quality. Here are the results:

Standardization

A written, clearly-specified definition of done is essentially a standard. Standards provide many benefits when properly applied using a lean (pragmatic) mindset rather than a bureaucratic mindset. The proper mindset can be summarized using the following dichotomy: a standard represents the best way we know today of doing some activity within some context, yet each day we search for a better way so as to improve the standard. As implied by this summary, standards help form the foundation for future improvements. This is because following standards brings consistency which makes it easier to analyze the results of the work being done, determine the root cause of problems, and identify how to improve. For more on how standards help improvement efforts see my article on a framework for continuous improvement.

Standards have a number of other benefits. Checklists can be created from the standards for use by both the people doing the work (as a reminder of what to do), and by the people verifying the work (as a quality assurance check). Standards are helpful in training new team members. Having documented standards can also be helpful for achieving certain certifications like ISO or passing regulatory requirements such as Sarbanes-Oxley.

Most definitions of done do not mandate the specific step-by-step procedures to follow, but rather set expectations regarding the final product produced. To illustrate, a definition of done for coding features will likely mandate that certain kinds of testing be done (automated unit testing, functional testing, etc.), but will typically not mandate the sequence in which the testing and coding activities are done. (So unit tests could be written before the code as per test-driven development, or they could be written afterward - either approach will satisfy the definition of done.) Team may choose to standardize which procedures are used, but this is typically kept separate from a definition of done.

More Accurate Estimates

Having a definition of done helps estimation accuracy in two ways. First, it serves as a checklist of all the steps required to complete an activity that can likewise be used to estimate the effort remaining. When estimating the work left on a feature, for example, a definition of done can help ensure that time is estimated not just for the coding, but also for reviewing and testing.

Second, a definition of done makes it easier to track the actual progress, since activities reported as done are more likely (but not guaranteed, unfortunately) to actually be done. This means there will be less surprises in terms of additional work required for previously 'completed' assignments. These surprises, of course, significantly reduce estimation accuracy, so the more they can be eliminated the better the estimates.

Better Teamwork

The previous benefits apply when you are working on your own, but software development is more commonly a team activity. And in addition to these prior benefits, having a definition of done will make your team more effective. Many of the challenges of working in terms such as achieving unity of purpose, clear communication, and coordination of effort, benefit from having a definition of done. When team members are communicating about the work that has been and needs to be done, having a clear definition of done helps avoid misunderstandings. The definition functions, in essence, as a communications technique for ensuring that when team members use the word "done" they all mean the same thing.

For examples of what happens without a clear definition see this story of a team of five having three different viewpoints regarding done and this story of someone reporting a status of 'finished' that really wasn't.

Concluding Thoughts

This article has mostly discussed definition of done in the context of software development and specifically coding, but the concept is much more broadly applicable both within I.T. and beyond. Staying within I.T. I can see the benefits of having definitions of done for activities such as incident resolution by support staff, product high-level requirements definition, and pursuing sales. So I challenge you to look for opportunities to use a definition of done to help achieve superior performance.

1. Thou shalt not break the build

This is the first commandment because breaking the build causes immediate problems for the rest of the team. Anyone updating from version control repository will have a non-functional local copy of the code and will be unable to continue with their work until the problem is fixed. A broken build also causes issues for others wanting to commit changes: they cannot verify that their changes do not break the code base. Doing an unrelated commit on top of a broken build risks introducing new breaks that compound the difficulty in getting the code base back to working order. (This exact problem happened quite recently on my project.)

The general principle is to not introduce problems in the code base that interfere with other development activities. Each team needs to have a specific, unambiguous definition. As a minimum standard I require code to always compile and pass 100% of the unit tests. While I prefer that automated integration and functional tests always pass, they are slower to run and depend on external systems, so pragmatically the occasional failure can happen.

An easy way to make your definition of a broken build explicit is to define an automated build process that performs this check. This build process can be executed by the developer prior to committing a change, and can also be configured to execute on a continuous integration server immediately after a change is committed to ensure the code base is not broken.

I like having a penalty in place for those that break the build. It can be a small monetary fine (that goes into the team pot for the next social event), receiving a mascot of shame, or being assigned an unpleasant task.

2. Thou shalt put everything in version control

All code and all related files must be in the version control repository. A new developer or a new instance of a continuous integration server should be able to check out a copy of the software and build a complete release from it.

Too often I have encountered code bases where some key files are not included. I have seen a number of projects not include third-party libraries in version control. This might be deemed acceptable if an enterprise library repository is used (using a tool such as Ivy), but in the cases I have seen the code base required a directory of library files to exist on each developer's local workstation without even a definition of the required versions of the libraries being used. Other common omissions include build scripts, configuration files, and documentation.

3. Thou shalt use the version control repository as the source of truth

The version control repository is the official source of truth for all versions of the software. Source code distributions may be created and distributed via shared network drives or via the web, but the source of truth remains the repository.

If multiple branches are being used within the repository then the purpose of each branch must be clearly defined. The typical approach is to use the trunk (mainline) for ongoing development work, and create branches for releases. So the trunk is the source of truth for the software overall, while each release branch is the source of truth for a particular release, and in particular the fixes and/or patches made for a release. Distributed version control systems such as Git, which in essence treat each local workspace as a separate branch, still need to follow these same rules to avoid complete chaos. (For example, running a continuous integration build requires at least one official branch to build from.)

The corollary to this commandment is that changes to source code not in the repository do not officially exist. Committing changes into the repository is therefore a critical part of doing development that is reflected in the next commandment.

4. Thou shalt commit thy changes daily

The principle behind this commandment is that the effort and difficulty involved in integrating separate changes increases non-linearly with the size of the changes, so it is best to integrate changes as often as possible. (This is an instance of the lean principle of flow which dictates minimizing large batch sizes and work-in-progress.) Requiring daily commits ensures that conflicts or duplication of effort are found quickly.

There are other benefits of daily commits. It forces developers to decompose their work into smaller, incremental pieces of work and ensure the quality of that work (since it cannot break the build as per commandment number one). Developers are more likely to use step-by-step refactoring rather than big-bang changes that are much riskier (and more likely to negatively impact the rest of the team). Daily commits provide a visible sign of progress per developer that can be used to assess when a developer is stuck or sidetracked (the commits tend to stop).

5. Thou shalt treat thy version control system as mission critical software

I have seen more than one company which did not treat their corporate version control system as mission-critical software. In one case the version control server was classified as a under-powered development server that could be bounced at any time or upgraded without prior testing. In another case the source code repository did not have robust backup and restore mechanisms in place.

If the version control server goes down it is safe to assume that regular development activities will start to grind to a halt within the day and any emergency fixes or scheduled releases will likely need to be delayed. It is a good idea to ensure that a version control server is available 24x7 with the ability to restore service within a half-day maximum. Why 24x7? Regular hours of development likely do not correspond to regular business hours (especially for emergency fixes), and scheduled builds typically run at night or the weekend.