Coding Standards are Part of Continuous Improvement
Coding standards extend to something beyond just code formatters. Coding Standards give team members the same understanding of what's expected of them. Developers spend less time trying to understand code when it's style and operating model look similar across modules and applications. Standards must take into account the range of developer skill set allowing for ongoing improvement from training. It may be that you allow or disallow some feature/approach to reduce the number of defects even if some developers are capable of doing "more". Developers like to be free to develop "in their own fashion" but management wants code to have the same shape and look from developer to developer because they care about developer portability across development efforts. Standards can be created that still let developers be creative on the interesting problems.
Automated Standards Support
Tooling can help enforce coding standards by providing constant reminders that there are minimum standards. Teams may wish to have coding standards that are not supported by automated tools but the core standard should be audited on a regular basis. Be sure the standards are adhered to before the code is checked in because you aren't going to have time to fix it later. Java developers have the advantage that their IDEs provide good automated analysis and review. These automated tools find more than just formatting issues.
They find formatting issues that lead to defects down the road and they find actual defects. Tooling should be included in the standard if you can get away with it. Most of my projects have a standard IDE configuration that everyone loads for their Java code. The checks are automatically turned on. You may only use some of the tools on a continuous basis while other tools may be run "on demand". The Eclipse formatter/clean-up module is a good continuous tool. The Checkstyle plugin can be configured to only run on save so it does not impact your build times.
Code Format
This is the simplest one but causes a surprising amount of conflict on a team. (See "artist" comment above. Code formatters help you with this. We basically use the Eclipse style with some changes. The great thing about the Eclipse formatter is that it can also do some code clean up in addition to managing indentation and line wraps. Conditional blocks without curly braces ({}) are defects waiting to happen. You can set up Eclipse so that it automatically adds the curly braces. We force all the developers to use Eclipse and we provide a standard set of preferences that we make everyone load. Eclipse has a setting that will reformat the source on every save so folks can just stream their code into the IDE and hit Save.
Code Constructs
Internally developed coding standards should focus on avoiding defects. It is best if you pick standards that can be flagged by our automated tools, IDE and plugins. As a first step, go down the list of style warnings flagged by Eclipse and figure out which ones you want to turn on. There may be some conflict here because teams include both experienced and inexperienced developers. Ex: We don't allow ternary operators because of legibility and the way folks overuse
them. Include the documentation settings in this review because you are delivering code for future generations. Some folks claim unit test are documentation and then don't document their complicated unit tests. Set a minimum bar that makes sense. Then go through the better tools/plugins, Checkstyle, PMD and/or Findbugs and take thieir suggestions and add them to your coding conventions. Standards that are supported by tools are the easiest to enforce.
Application Specific Standards
Applications and architectures develop coding patterns over time. Those coding patterns should be added to the coding standards as they are developed and accepted. A project might use Spring only in a Singleton pattern so you might add that singleton pattern to the coding standard. It may be that an application caches results of some operation based on a hash key so every class that can be a result of that operation needs to implement a custom hashCode() method. This would be added to the coding standard. Basically every defect that shows up due to a coding error is a candidate to be added to the application specific coding standard. Every tier in the application has these conventions.
Coding for Testing
Coding Standards are about more than pretty code. They should drive developers to create software structured in a way that meets other requirements like testability. Code takes on a different shape when it is written in a unit testable fashion. Static classes tend to disappear or made pluggable. Methods tend to get smaller and accept more inputs as parameters instead of doing environmental rendezvous with their data. Void methods in controller classes tend to vanish to be replaced by methods that return values to be handled by the callers. Coding standards that include minimum unit testing requirements drive users to create more modular code.
Non-Java Languages in Java Projects
Coding standards should include non-Java languages including things like xhtml, xml, Javascript, etc. Some of these standards may be supported by automated tools but that is often limited to source formatters. Application specific coding conventions should be included here as well. Example non-format non-Java related standards might be to limit types functions or data in Javascript code or in hidden fields in HTML. Many of the standards will have to be manually enforced, especially for the dynamically typed languages. The lack of good tooling support is one of the biggest reasons that teams often keep scripting or dynamic language usage to a minimum in large projects. Small teams full of really smart people will tell you that they are more efficient with these languages but it is very hard to create standard, readable code that can be handed off from one generation to the next of developer on the project.
Standards Verification
The team motto should be "Trust but Verify". Run tools in the IDE. Cover coding standards in code reviews and training. Then measure your progress with a tool like Sonar. It will run all of the automated tools described elsewhere in this document and track the progress over time. It has a web interface that lets you drill down by package and class and see where you are having compliance issues, coding problems or poor unit test coverage. Metrics can help a team
improve their game without a lot of manual intervention.
Training
Training is required whenever a team changes a policy or method of operation. Coding standards will result in changes for many users so training will be mandatory. Some teams send out the coding standards and then assume everyone is OK with them when no one complains. Zero complaints means they didn't read it or that they don't think the company is serious. Teams must do at least one
walk through of the different sections of any standards. Training should almost always result in standards updates, clarifications or additions.
Final
Coding standards can really help keep a code base together and set expectations for new and existing team members. Teams should expand the concept of a coding standard beyond naming and formatting and include all the standardized behavior and style that they want in their code base. Standards should be reevaluated whenever a new type of subsystem is written or a new 3rd party library included. Organization is the key to repeatable success and lower defect counts.
Originally Written 3/2010
Automated Standards Support
Tooling can help enforce coding standards by providing constant reminders that there are minimum standards. Teams may wish to have coding standards that are not supported by automated tools but the core standard should be audited on a regular basis. Be sure the standards are adhered to before the code is checked in because you aren't going to have time to fix it later. Java developers have the advantage that their IDEs provide good automated analysis and review. These automated tools find more than just formatting issues.
They find formatting issues that lead to defects down the road and they find actual defects. Tooling should be included in the standard if you can get away with it. Most of my projects have a standard IDE configuration that everyone loads for their Java code. The checks are automatically turned on. You may only use some of the tools on a continuous basis while other tools may be run "on demand". The Eclipse formatter/clean-up module is a good continuous tool. The Checkstyle plugin can be configured to only run on save so it does not impact your build times.
Code Format
This is the simplest one but causes a surprising amount of conflict on a team. (See "artist" comment above. Code formatters help you with this. We basically use the Eclipse style with some changes. The great thing about the Eclipse formatter is that it can also do some code clean up in addition to managing indentation and line wraps. Conditional blocks without curly braces ({}) are defects waiting to happen. You can set up Eclipse so that it automatically adds the curly braces. We force all the developers to use Eclipse and we provide a standard set of preferences that we make everyone load. Eclipse has a setting that will reformat the source on every save so folks can just stream their code into the IDE and hit Save.
Code Constructs
Internally developed coding standards should focus on avoiding defects. It is best if you pick standards that can be flagged by our automated tools, IDE and plugins. As a first step, go down the list of style warnings flagged by Eclipse and figure out which ones you want to turn on. There may be some conflict here because teams include both experienced and inexperienced developers. Ex: We don't allow ternary operators because of legibility and the way folks overuse
them. Include the documentation settings in this review because you are delivering code for future generations. Some folks claim unit test are documentation and then don't document their complicated unit tests. Set a minimum bar that makes sense. Then go through the better tools/plugins, Checkstyle, PMD and/or Findbugs and take thieir suggestions and add them to your coding conventions. Standards that are supported by tools are the easiest to enforce.
Application Specific Standards
Applications and architectures develop coding patterns over time. Those coding patterns should be added to the coding standards as they are developed and accepted. A project might use Spring only in a Singleton pattern so you might add that singleton pattern to the coding standard. It may be that an application caches results of some operation based on a hash key so every class that can be a result of that operation needs to implement a custom hashCode() method. This would be added to the coding standard. Basically every defect that shows up due to a coding error is a candidate to be added to the application specific coding standard. Every tier in the application has these conventions.
Coding for Testing
Coding Standards are about more than pretty code. They should drive developers to create software structured in a way that meets other requirements like testability. Code takes on a different shape when it is written in a unit testable fashion. Static classes tend to disappear or made pluggable. Methods tend to get smaller and accept more inputs as parameters instead of doing environmental rendezvous with their data. Void methods in controller classes tend to vanish to be replaced by methods that return values to be handled by the callers. Coding standards that include minimum unit testing requirements drive users to create more modular code.
Non-Java Languages in Java Projects
Coding standards should include non-Java languages including things like xhtml, xml, Javascript, etc. Some of these standards may be supported by automated tools but that is often limited to source formatters. Application specific coding conventions should be included here as well. Example non-format non-Java related standards might be to limit types functions or data in Javascript code or in hidden fields in HTML. Many of the standards will have to be manually enforced, especially for the dynamically typed languages. The lack of good tooling support is one of the biggest reasons that teams often keep scripting or dynamic language usage to a minimum in large projects. Small teams full of really smart people will tell you that they are more efficient with these languages but it is very hard to create standard, readable code that can be handed off from one generation to the next of developer on the project.
Standards Verification
The team motto should be "Trust but Verify". Run tools in the IDE. Cover coding standards in code reviews and training. Then measure your progress with a tool like Sonar. It will run all of the automated tools described elsewhere in this document and track the progress over time. It has a web interface that lets you drill down by package and class and see where you are having compliance issues, coding problems or poor unit test coverage. Metrics can help a team
improve their game without a lot of manual intervention.
Training
Training is required whenever a team changes a policy or method of operation. Coding standards will result in changes for many users so training will be mandatory. Some teams send out the coding standards and then assume everyone is OK with them when no one complains. Zero complaints means they didn't read it or that they don't think the company is serious. Teams must do at least one
walk through of the different sections of any standards. Training should almost always result in standards updates, clarifications or additions.
Final
Coding standards can really help keep a code base together and set expectations for new and existing team members. Teams should expand the concept of a coding standard beyond naming and formatting and include all the standardized behavior and style that they want in their code base. Standards should be reevaluated whenever a new type of subsystem is written or a new 3rd party library included. Organization is the key to repeatable success and lower defect counts.
Originally Written 3/2010
Comments
Post a Comment