Coding conventions are rooted in the definition of done.
Having a definition of done helps to form a common understanding of desirable qualities of a product created by a team.
This definition is not underestimated, as the following quotes account for.
Ten years ago no one had that notion [refers to the "definition of done"]. But I think that through the years the idea that if you just keep putting out feature after feature without considering the quality of it, you could be in trouble.
Laurie Williams, Getting to Comparative Agility
Scrum teams that are unable to master the concept and use of "done" will not succeed.
Ken Schwaber, Done and Undone on Control Chaos
There are definitions of done for tasks, sprints, or releases, but let's stick to user stories. The answer to the question
is answered by this definition and the items on this list makes the work required visible to all stakeholders. This list may have numerous items like the following example:
[dropshadowbox align="center" effect="lifted-both" width="350px" height="" background_color="#ffffff" border_width="1" border_color="#dddddd" ]
The definition of done is defined by the team to meet requirements that are non-functional, also know as a quality attributes: software maintenance for instance.
One item one can often find on the 'done list' is that the code must conform to the coding standards defined by the team. Conforming code improves the readability for all team members. This advances the software maintenance quality. It supports the notion that the team owns the whole code base.
[perfect_quotes id="87"]
Having tools like Checkstyle, PMD or Findbugs checking the code is not only about automation, but the executable rules also form an instance of a living documentation.
The definition of done is not static and an agile team works on it to improve the collaborative work and to communicate about it with other stakeholders of the project. The requirements stated in the list are a moving target.
From the point of view of a delivery pipeline the delivery process starts with a commit that may automatically be promoted into production. This requires that all the requirements formulated in the definition of done must also be automatically testable. This automatic tests also help team members to be write code that is conform with the coding standards while working with the editor. They will also be informed about not meeting the requirements by their build server, triggered automatically by the check-in - up to the stage where the manual user acceptance testing tasks can be executed. After the OK by the team the rest of the steps may be taken automatically again.
[perfect_quotes id="69"]
And there is a third point - and for me an equally important one: The team should document why a special coding convention is important. This is not only useful for the team to get a common understanding for a given rule, but it also helps new team members to adhere to it. Having a reason makes a rule challengeable. Reasoning is always a good thing.
So the path to my conclusion is this:
And the message is
At smartics the configuration for static code analysis is documented by three projects:
We add the justification for our Checkstyle and PMD rules as part of their configuration. To be pragmatic, only controversial rules should be commented. The configurations with their justifications are displayed on the project's website. There may be a better way to format this report than displaying the XML file, but it is enough for a start.
Definition of Done
Having a definition of done helps to form a common understanding of desirable qualities of a product created by a team.
This definition is not underestimated, as the following quotes account for.
Ten years ago no one had that notion [refers to the "definition of done"]. But I think that through the years the idea that if you just keep putting out feature after feature without considering the quality of it, you could be in trouble.
Laurie Williams, Getting to Comparative Agility
Scrum teams that are unable to master the concept and use of "done" will not succeed.
Ken Schwaber, Done and Undone on Control Chaos
There are definitions of done for tasks, sprints, or releases, but let's stick to user stories. The answer to the question
"What makes a story be considered as done?"
is answered by this definition and the items on this list makes the work required visible to all stakeholders. This list may have numerous items like the following example:
[dropshadowbox align="center" effect="lifted-both" width="350px" height="" background_color="#ffffff" border_width="1" border_color="#dddddd" ]
- All story tasks are done
- All unit tests pass
- Coding standards followed
- Code is peer reviewed
- Code merged in mainline
- Acceptance tests passed
- Capacity tests passed
- Successfully deployt to UAT environment and tests passed
- Successfully delivered to customer, passing smoke tests.
The definition of done is defined by the team to meet requirements that are non-functional, also know as a quality attributes: software maintenance for instance.
Coding Conventions
One item one can often find on the 'done list' is that the code must conform to the coding standards defined by the team. Conforming code improves the readability for all team members. This advances the software maintenance quality. It supports the notion that the team owns the whole code base.
[perfect_quotes id="87"]
Having tools like Checkstyle, PMD or Findbugs checking the code is not only about automation, but the executable rules also form an instance of a living documentation.
Automation
The definition of done is not static and an agile team works on it to improve the collaborative work and to communicate about it with other stakeholders of the project. The requirements stated in the list are a moving target.
From the point of view of a delivery pipeline the delivery process starts with a commit that may automatically be promoted into production. This requires that all the requirements formulated in the definition of done must also be automatically testable. This automatic tests also help team members to be write code that is conform with the coding standards while working with the editor. They will also be informed about not meeting the requirements by their build server, triggered automatically by the check-in - up to the stage where the manual user acceptance testing tasks can be executed. After the OK by the team the rest of the steps may be taken automatically again.
[perfect_quotes id="69"]
Justify Guidelines
And there is a third point - and for me an equally important one: The team should document why a special coding convention is important. This is not only useful for the team to get a common understanding for a given rule, but it also helps new team members to adhere to it. Having a reason makes a rule challengeable. Reasoning is always a good thing.
Conclusion
So the path to my conclusion is this:
- Communication is an important part of software development
- The definition of done does promote communication
- The definition of done also promotes qualities
- One such quality is software maintenance that is supported by coding conventions
And the message is
- Coding conventions are an executable specification for software maintenance requirements
- All rules of your coding conventions should be checked automatically
- A justification for the rules should be provided so that the members of the team can understand the reason for enforcing it
Example Configurations
At smartics the configuration for static code analysis is documented by three projects:
We add the justification for our Checkstyle and PMD rules as part of their configuration. To be pragmatic, only controversial rules should be commented. The configurations with their justifications are displayed on the project's website. There may be a better way to format this report than displaying the XML file, but it is enough for a start.
