based on the inchecklist created by Erwin Moetwil
review 2008-04-02 by Rutger Kramer (QM)
About this document
As a developer, you are responsible for the quality of the code you write. Although it is not the sexiest part of the development cycle, it is absolutely paramount that the code you write is reliable, legible, bug-free, and that it scales well. In order to ensure that the code can withstand one of the greatest challenges of all, i.e. users, you need to regularly check the quality of your code and follow the guidelines of your project.
Unfortunately, writing code is not just an engineering skill. It takes a lot of inspiration and creativity to come up with algorithms and implementations, and you need room to experiment to be able to come up with the best solution. Imposing rigid guidelines on how to write your code will not help much when you’re trying to be creative.
This checklist will help you determine whether or not the user-story you have been working on is really ready to be released into the system. After you’ve done your creative thing, and the functionality seems to be ready, you should do the following things:
- take a moment to reflect on what you have created,
- take out this list
o check every bullet on the list against your code
o wherever your code does not adhere to the checklist, fix the discrepancy,
o if you’re not able to fix it, discuss it with a fellow developer. See if he or she knows a solution to the problem,
o if you’re still not able to fix it, add a commentblock explaining why so that other developers won’t have to re-evaluate the code.
- commit the code, and celebrate the birth of new functionality
Numerous tools and applications have been written to help you analyze source code and identify possible weaknesses. These tools can give you a good idea of the quality of the code, but it still takes a human like you to actually fix the problems. Moreover, these tools are not able to recognize complex problems such as memory management issues or performance hogs. You need to be able to judge your own code, and determine its quality, without relying solely on tools like CheckStyle and FindBugs.
It is important to realize that taking care of the issues that arise from this checklist takes time. Do not underestimate the amount of effort it takes to get your code up to par. For small stories, such as adding a button to a GUI, the quality issues can easily take more time than the functionality itself.
With practise and experience, you’ll be able to estimate how much extra time is going into the quality of the code.
And one more thing: whenever a project manager or developer tells you to skip the quality checklist, laugh hysterically and refer them to your appointed quality manager.
Agreements on this checklist can be found on:
Things you need to do before the celebration:
- Determine which classes are affected by the story
o Which classes have been altered/created?
o Which resourcefiles (configs, propertyfiles, etc.) have been created?
o Which classes are dependent on these classes?
- For each class affected by the story:
• Are there passages in you code that can be refactored to something more elegant, e.g.:
• Loops instead of repeating code,
• private functions instead of inline processing,
o JUnit testing:
• Check JUnit Test Coverage against project coverage aim (minimum is 60%),
• Actually run the tests and fix any resulting problems,
o Check if your code adheres to the code formatting conventions of your project:
• Use Checkstyle to identify formatting violations,
• Either fix the issues, or add a comment block on why you cannot fix the issue after deliberation with a fellow developer,
o Check against Taglist
• Check all the tags found in the taglist
• Either fix the issues (e.g. TODO items), or add a comment block on why you cannot fix the issue after deliberation with a fellow developer.
• For now, ANTLR code will only be tested on input/output bases.
Submitted by dirk on Tue, 2008-07-15 09:11.