C++ Coding Standards: Process And Coding Pattern - Online Article


Use a Design Notation and Process

Programmers need to have a common language for talking about coding, designs, and the software process in general. This is critical to project success.

Any project brings together people of widely varying skills, knowledge, and experience. Even if everyone on a project is a genius you will still fail because people will endlessly talk past each other because there is no common language and processes binding the project together. All you'll get is massive fights, burnout, and little progress. If you send your group to training they may not comeback seasoned experts but at least your group will all be on the same page; a team.

There are many popular methodologies out there. The point is to do some research, pick a method, train your people on it, and use it. Take a look at the top of this page for links to various methodologies.

You may find an Agile methodology to your liking. For more information see http://www.possibility.com/epowiki/Wiki.jsp?page=agile.

You may find the CRC (class responsibility cards) approach to teasing out a design useful. Many others have. It is an informal approach encouraging team cooperation and focusing on objects doing things rather than objects having attributes. There'seven a whole book on it: Using CRC Cards by Nancy M. Wilkinson.

Using Use Cases

A use case is a generic description of an entire transaction involving several objects. A use case can also describe the behaviour of a set of objects, such as an organization. A use case model thus presents a collection of use cases and is typically used to specify the behavior of a whole application system together with one or more external actors that interact with the system.

An individual use case may have a name (although it is typically not a simple name). Its meaning is often written as an informal text description of the external actors and the sequences of events between objects that make up the transaction. Use cases can include other use cases as part of their behaviour.

Requirements Capture

Use cases attempt to capture the requirements for a system in an understandable form. The idea is by running through a set of use case we can verify that the system is doing what it should be doing.

Have as many use cases as needed to describe what a system needs to accomplish.

The Process

  • Start by understanding the system you are trying to build.
  • Create a set of use cases describing how the system is to be used by all its different audiences.
  • Create a class and object model for the system.
  • Run through all the use cases to make sure your model can handle all the cases. Update your model and create new use cases as necessary.

Using Stories

A user story consists of just a phrase or a few sentences written down, announcing something the user wants to do. The user story is not used as a requirements specification, but as a marker for a future conversation.

  • User stories are used as tokens in the planning process after assessment of business value and risk. The customer prioritizes the stories and schedules them for implementation.
  • User Story is a story about how the system is supposed to solve a problem. Each UserStory represents a chunk of functionality that is coherent in some way to the customer.
  • User Story is a token that stands in for a conversation whose purpose is roughly equivalent to that of a UseCase. The content of a UserStory is often an abbreviated version of the main success scenario of a UseCase, but it doesn't have to be.
  • User Story is a marker that reminds the customer and developers what to talk about, and also inspires them in exploring some particular area of business value. A UserStory, then, contains whatever the customer thinks is necessary to jog the memories and inspirations of those who will later explore the story. Expertise in the business area will help the customer decide what are theessential "jogs" to record in the initial UserStory marker.
  • Developers should be able to implement a story in 2-4 weeks. The iteration length depends on you project.

A Story Is

  • Testable -You can write automatic tests to detect the presence of the story.
  • Progress - The customers side of the team is willing to accept the story as a sign of progress toward their larger goal
  • Bite-sized - The story should be completable within the iteration.
  • Estimatable - The technical side of the team must be able to guess how much of the team's time the story will require to get working.

How It All Fits Together

There are a lot of entrants in this part of the development process. We have user stories, use cases, task analysis, task cases, usage scenarios, etc and etc.

It seems we need something more detailed than requirements as requirements tend to be fairly high level and are usually not directly useful for development. A requirement will cut across many subsystems and each of the cross-cuts must be identified. Thus requirements need to go through refinement and elaboration to be used in development.

If we get too detailed then we get bogged down in detailed design before we are ready. If we aren't detailed enough then we can't know if our requirements are met. Nor can we convince ourselves that we know how to solve the problem.

User Stories Need to be Fleshed Out

User Stories are symbolic of the stuff that needs to get done. They are like the reminder notes you make to yourself. In the detailed design these can be expanded out to uses cases, to more detailed notes, state machines, etc. Or TestDrivenDesign practices could be used to flesh out the detailed implementation.

For more information see http://www.possibility.com/epowiki/Edit.jsp?page=UserStory.

Unified Modeling Language

The Unified Modeling Language is too large to present here. Fortunately you can see it at Rational's web site. Since you do need a modeling language UML is a safe choice. It combines features from several methods into one unified language. Remember all languages and methods are open to local customization. If their language is too complex then use the parts you and your project feel they need and junk the rest.

Code Reviews

If you can make a formal code review work then my hat is off to you. Code reviews can be very useful. Unfortunately they often degrade into nit picking sessions and endless arguments about silly things. They also tend to take a lot of people's time for a questionable payback.

My god he's questioning code reviews, he's not an engineer!

Not really, it's the form of code reviews and how they fit into normally late chaotic projects is what is being questioned.

First, code reviews are way too late to do much of anything useful. What needs reviewing are requirements and design. This is where you will get more bang for the buck.

Get all relevant people in a room. Lock them in. Go over the class design and requirements until the former is good and the latter is being met. Having all the relevant people in the room makes this process a deep fruitful one as questions can be immediately answered and issues immediately explored. Usually only a couple of such meetings are necessary.

If the above process is done well coding will take care of itself. If you find problems in the code review the best you can usually do is a rewrite after someone has sunk a ton of time and effort into making the code "work."

You will still want to do a code review, just do it offline. Have a couple people you trust read the code in question and simply make comments to the programmer. Then the programmer and reviewers can discuss issues and work them out. Email and quick pointed discussions work well. This approach meets the goals and doesn't take the time of 6 people to do it.

For more information on code reviews please take a look at here.

You'll find a lot of information on justifying code reviews if you are having troubles instituting them and lots of suggestions on how to conduct them.

Create a Source Code Control System Early and Not Often

A common build system and source code control system should be put in place as early as possible in a project's lifecycle, preferably before anyone starts coding. Source code control is the structural glue binding a project together. If programmers can't easily use each other's products then you'll never be able to make a good reproducible build and people will piss away a lot of time.It's also hell converting rogue build environments to a standard system. But it seems the right of passage for every project to build their own custom environment that never quite works right.

Some issues to keep in mind:

  • Appoint a buildmaster who is in charge of the build environment and making builds. If you have a tools group so much the better as build environments generally generate a lot of tools.
  • Programmers should generally leave tagging and other advanced operations to the buildmaster.
  • Shared source environments like CVS usually work best in largish projects.
  • Makefiles should be completely templated so developers need no makefile expertise.
  • You will need multiple builds of the same code meaning programmers will want to have the option of building against optimized code versions, debugger code versions, code with the -DDEBUG macro defined and versions without, etc. One way to do this is have everyone check out all code and do a total rebuild. The other better way is for the buildmaster to build all necessary versions of code so programmers can check out only the code which they are modifying. The idea is that each combination of compile flags andmacros defines a build.
  • Dependency checking should work!
  • Maintain a cycle of builds. Create a nightly build so problems can be detected early. Create a valid build every week or for every feature set that is guaranteed to be good. Every release to QA or to customers should be tagged and available in the tree. Official builds should be official because they contain a certain set of features that assumably meet a schedule, not  because it's a certain date.
  • If you use CVS use a reference tree approach. With this approach a master build tree is kept of various builds. Programmers checkout source against the build they are working on. They only checkout what they need because the make system uses the build for anything not found locally. Using the -I and -L flags makes this system easy to setup. Search locally for any files and libraries then search in the reference build. This approach saves on disk space and build time.
  • Get a lot of disk space. With disk space as cheap it is there is no reason not to keep plenty of builds around and have enough space for programmers to compile.
  • Make simple things simple. It should be dead simple and well documented on how to:
    • check out modules to build
    • how to change files
    • how to setup makefiles
    • how to add new modules into the system
    • how to delete modules and files
    • how to check in changes
    • what are the available libraries and include files
    • how to get the build environment including all compilers and other tools

    Make a web page or document or whatever. New programmers shouldn't have to go around begging for build secrets from the old timers.

  • Use the idea of services. If using a feature requires linking to 3 libraries think about making a service specifiable in the makefile programmers can use instead of having to know the exact libraries needed. With this approach the libraries making up a service can be changed in a based makefile without requiring changes in all makefiles.
  • On checkins log comments should be useful. These comments should be collected every night and sent to interested parties.

Source Code Control Systems

Some options for source code control systems are:

  1. Subversion - a free, popular, and well featured system.
  3. Perforce - a not free, popular, and very solid system that scales beautifully and just works.
  5. Clear Case - a not free, popular in larger corporations, and requires a dedicated admin team, yet you can accomplish a lot with it.

There are many other options out there. It doesn't matter which one you pick as much as it does that you pick one and use it.

About the Author:

No further information.


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