C++ Coding Standards: Some Useful Tips - Online Article

Create a Bug Tracking System Early and Not Often

The earlier people get used to using a bug tracking system the better. If you are 3/4 through a project and then install a bug tracking system it won't be used. You need to install a bug tracking system early so people will use it.

Programmers generally resist bug tracking, yet when used correctly it can really help a project:

     
  • Problems aren't dropped on the floor.
  •  
  • Problems are automatically routed to responsible individuals.
  •  
  • The lifecycle of a problem is tracked so people can argue back and forth with good information.
  •  
  • Managers can make the big schedule and staffing decisions based on the number of and types of bugs in the system.
  •  
  • Configuration management has a hope of matching patches back to the problems they fix.
  •  
  • QA and technical support have a communication medium with developers.

Not sexy things, just good solid project improvements.

FYI, it's not a good idea to reward people by the number of bugs they fix :-)

Source code control should be linked to the bug tracking system. During the part of a project where source is frozen before a release only checkins accompanied by a valid bug ID should be accepted. And when code is changed to fix a bug the bug ID should be included in the checkin comments.

Bug Tracking Systems

Some options for bug tracking systems are:

     
  1. Jira - a full featured and reliable bug tracking system. It works best when combined with Confluence, their wiki product.
  2.  
  3. Bugzilla - a free product that is functional and widely used.

As for source code control systems there are many available bug tracking systems. It's more important that you use one than which one you use.

RCS Keywords, Change Log, and History Policy

When using RCS directly this policy must change, but when using other source code control systems like CVS that support RCS style keywords:

     
  • Do not use RCS keywords within files.
  •  
  • Do not keep a change history in files.
  •  
  • Do not keep author information in files.

Justification

     
  • The reasoning is your source control system already keeps all this information. There is no reason to clutter up source files with duplicate information that:
  •  
       
    • makes the files larger
    •  
    • makes doing diffs difficult as non source code lines change
    •  
    • makes the entry into the file dozens of lines lower in the file which makes a search or jump necessary for each file
    •  
    • is easily available from the source code control system and does not need embedding in the file
    •  
       
  • When files must be sent to other organizations the comments may contain internal details that should not be exposed to  outsiders.

Create a Wiki System Early and Not Often

The heart of software development is information. Where do you put all your documentation? Where do we put your coding guidelines? Where you put all your process documents? Where do you put your design documents? Where do you put all the 1000s of bits of information that hold a project together?

With a strategy information is usually spread like seeds in the wind. Much is in people's heads, in email, in IM, in files on people's file systems, or files on different servers. Nobody can ever find anything they need.

A solution to this mess is to store all your information in a wiki. A Wiki is a web site written by many users. It's very easy for a community of people to create and edit content. The idea is that people can add a page for any topic they want and add to any existing page by simply editing it. Over time we can create a site addressing most of the issues people have about projects, products, development, process, and more.

A wiki is perfect support for software development.

I've written up my hard one advice for using wikis at Getting Your Wiki Adopted.

Honor Responsibilities

Responsibility for software modules is scoped. Modules are either the responsibility of a particular person or are common. Honor this division of responsibility. Don't go changing things that aren't your responsibility to change. Only mistakes and hard feelings will result.

Face it, if you don't own a piece of code you can't possibly be in a position to change it. There's too much context. Assumptions seemingly reasonable to you may be totally wrong. If you need a change simply ask the responsible person to change it. Or ask them if it is OK to make such-n-such a change. If they say OK then go ahead, otherwise holster your editor.

Every rule has exceptions. If it's 3 in the morning and you need to make a change to make a deliverable then you have to do it. If someone is on vacation and no one has been assigned their module then you have to do it. If you make changes in other people's code try and use the same style they have adopted.

Programmers need to mark with comments code that is particularly sensitive to change. If code in one area requires changes to code in an another area then say so. If changing data formats will cause conflicts with persistent stores or remote message sending then say so. If you are trying to minimize memory usage or achieve some other end then say so. Not everyone is as brilliant as you.

The worst sin is to flit through the system changing bits of code to match your coding style. If someone isn't coding to the standards then ask them or ask your manager to ask them to code to the standards. Use common courtesy.

Code with common responsibility should be treated with care. Resist making radical changes as the conflicts will be hard to resolve. Put comments in the file on how the file should be extended so everyone will follow the same rules. Try and use a common structure in all common files so people don't have to guess on where to find things and how to make changes. Checkin changes as soon as possible so conflicts don't build up.

As an aside, module responsibilities must also be assigned for bug tracking purposes.

Process Automation

It's a sad fact of human nature that if you don't measure it or check for it: it won't happen. The implication is you must automate as much of the development process as possible and provide direct feedback to developers on specific issues that they can fix.

Process automation also frees up developers to do real work because they don't have to babysit builds and other project time sinks.

Automated Builds and Error Assignment

Create an automated build system that can create nightly builds, parse the build errors, assign the errors to developers, and email developers their particular errors so they can fix them.

This is the best way to maintain a clean build. Make sure the list of all errors for a build is available for everyone to see soeveryone can see everyone elses errors. The goal is replace a blaim culture with a culture that tries to get things right and fixes them when they are wrong. Immediate feedback makes this possible.

Automated Code Checking

As part of the automated build process you can check for coding standard violations and for other problems. If you don't check for it people will naturally do their own thing. Code reviews aren't good enough to keep the code correct. With a tool like Abraxis Code Check you can check the code for a lot of potential problems.

This feature like the automated error assignment makes problems immediately visible and immediately correctable, all without a lot of blame and shame.

Documentation Extraction

Related to this principle is the need to automatically extract documentation from the source code and make it available on line for everyone to use. If you don't do this documentation will be seen as generally useless and developers won't put as much effort into it. Making the documentation visible encourages people to do a better job.

Connect Source Code Control System and Bug Tracking System

     
  1. When a check-in of source code fixes a bug then have the check-in automatically tell the bug tracking system that the bug was fixed.
  2.  
  3. When a bug fix is built in a build change the state of the bug to BUILT.
  4.  
  5. Have a submit tool where people ask judges of they can submit a bug fix on the branch.

There are lots of things you can do depending on how complicated your environment. The more complicated the environment the moreyou should think about connecting all systems together.

Tools Agreement

The reality of different tool preferences is something to deal with explicitly and openly. Tools include IDEs, languages, editors, make program, source code control, bug system, debuggers, test framework, etc. Some tool decisions by their nature must be project wide, other decisions can be customized per developer.

A split might also be done by who is performing the build. For example, an IDE should be able to used in local builds, but the make program would be used for nightly and release builds.

Certain things are easy/trivial/useful with one tool, but hard/complicated/stupid with another tool. Unstated tool assumptions can be the source of a lot of confusion. "Get a better editor" is not always a workable response, though sometimes that's all there is to it!

Non-Blocking Scheduling

Schedules are lies. Schedules suck. Yes, yes, yes. But we still need them.

The most effective scheduling rule i've used is to schedule so as to unblock others. The idea is to complete the portions of   a feature that will unblock those dependent on you. This way development moves along smoothly because more lines of development can be active at a time. For example, instead of implementing mthe entire database, implement the simple interface and stub it out. People can work for a very long time this way using that portion of the feature that caused others not to block. Plus it's a form of rapid prototyping because you get immediate feedback on these parts. Don't worry about the quality of implementation because it doesn't matter yet.

Using Personas

Personas are a powerful design tool, especially when combined with responsibility driven design. Cooper's personas are:.

simply pretend users of the system you're building. You describe 
them, in a surprising amount of detail, and then design your
system for them.

I have a standard set of personas that i consider when creating a design/architecture that don't seem to be common. When you write  code their are a lot of personas looking over your shoulder:

     
  1. other programmers using the code
  2.  
  3. maintenance
  4.  
  5. extension
  6.  
  7. documentation group
  8.  
  9. training group
  10.  
  11. code review
  12.  
  13. test and validation
  14.  
  15. manufacturing
  16.  
  17. field support
  18.  
  19. first and second line technical support
  20.  
  21. live debugging
  22.  
  23. post crash debugging
  24.  
  25. build system (documentation generation and automatic testing)
  26.  
  27. unit testing
  28.  
  29. system testing
  30.  
  31. source code control
  32.  
  33. code readers
  34.  
  35. legal

You are much more careful and more thorough when you really thing about all the personas, all the different people and all their different roles and purposes.

Use a Continuous Build System

Setup a continuous build system for your group. It should build all new check-ins and run the unit tests for each change. If you have the resources run a smoke test for each build as well.

If there's a failure email should go out to the developer's who made the check-ins.

This policy will allow you to catch errors as early as possible which will make your system more stable over time.

Code in the Dominant Style

Let's say someone invites you into your home as a guest. How do you act? Do you act as you do at home or do you try and fit in with the household in which you are staying? You try to fit in of course.

So when you have to write code for a new codebase do you 1) write code however you want or 2) write code like the code that already exists?

When writing code in a new codebase write code how the code is already written. Don't use your own style. Take some time, look around, and see how the code is written. To come in like a bull in a china shop is the mark of someone who is not a professional developer.

Run Unit Tests Before Every Check-in

Before every check-in developers must run unit tests to verify all unit tests should pass. This prevents letting any errors creep in.

Finding, debugging, and handling errors is a tremendous drain on the development process so we want have a solid working system from the start. The start means your code that you check-in should always work and we know it works by running unit tests and smoke tests if your organization has them.

About the Author:

No further information.




Comments

No comment yet. Be the first to post a comment.