Coding Guidelines

When I get a new client, I ask for a copy of their driver coding guidelines.   Typically I get one of several responses.


·         We trust our developers to do the right thing.


·         The last time we brought this up there was almost open revolt.


·         They hand me a corporate standard for coding applications, most of which is worthless for drivers.


Whether companies recognize it or not, they need a set of coding guidelines for drivers.  There are a lot of ways of doing things in drivers that can cause problems, and a good set of guidelines can help.  Consider some of the following areas:


·         C++ – There can be an argument for this in many cases, but if C++ is used for drivers, there needs to be limits placed upon the language for it to work in the kernel.


·         Undocumented or unusual routines – What is your company’s policy on the use of undocumented kernel interfaces?  What about routines not normally used in the kernel, but documented for user space?  How about functions from the IFS kit for a regular driver?  There are a lot decisions to make here.


·         WDM, WDF or 3rd party toolkits – What is your policy on drivers:  should they be the traditional WDM model, the new WDF models or a 3rd party model? 


·         Development Environment – What do you require for a development environment?  This should be simple; namely a specific version of the DDK/WDK, but if you don’t spec it you can get anything.


·         Windows Logo – Do you want your drivers to have a Windows Logo?  This impacts the routines, models, and methodology for developing drivers.


·         Static Verification tools – What is your policy on code passing static and dynamic verification tools?  Do you require code to be PREfast clean?  Does your code need to run through Static Driver Verifier?  Do you require annotations to aid the above tools in finding bugs?  Do you use PC-Lint and do you have your own definitions file? 


·         Testing – Does the code need to pass Driver Verifier?  For Server 2003, does your code need to pass Call Usage Verifier? Is there a code coverage tool and standards to be met?  What other tests are required?


·         Diagnostics – What is your model for tracing and debug prints?  Do you require event logging?  Do you expect data to be presented to the performance monitor?  Is there information going to Windows Management Instrumentation?

·         Coding style – This is the one that causes the biggest fights.  You should probably not be dictating the location of braces or indentation, but there are things that make code easier to review or for the next person to work on it.

The above is not a complete list, but even more needs to be considered.  If you do not have the resources in-house, consider engaging a consultant to develop the guidelines based on your current practice. 


You do not want to end up like one firm I know that hired a contractor to develop a driver.  When the driver was delivered, the company discovered the contractor had used a toolkit the firm did not own and would cost over $100,000 to buy for the developers and train them on.  The choice between slipping the product schedule and buying the tool was not a pleasant one.  With some preparation up front in specifying coding guidelines, such scenarios can be prevented and time and money saved in the end.


 

3 thoughts on “Coding Guidelines”

  1. Coding style:
    It would be great if you could provide some pointers to it.
    Should we follow some standards specific to the driver code?
    Are there any “Best practices” for the same?
    you can contact me at:
    ayush.gupta@yahoo.com

  2. Thanks for the great article! It was a big help when developing the guide lines for our company.

    Some more points to consider:
    -Source files should not get too long
    -Functions should not get too long
    -YAGNI (You ain’t gonna need it)
    -API design, upwards compatibility
    -Locking strategy

Leave a Reply

Your email address will not be published. Required fields are marked *


*

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>