Home > technical > Project-Specific Coding Guidelines

Project-Specific Coding Guidelines

I’m about to embark on the development of a distributed, scalable, data-centric, real-time, sensor system. Since some technical risks are at this point disturbingly high, especially meeting CPU loading and latency requirements, a team of three of us (two software engineers and one system engineer) are going to prototype several CPU-intensive system functions.

Assuming that our prototyping effort proves that our proposed application layer functional architecture is feasible, a much larger team will be applied to the effort in an attempt to meet schedule. In order to promote consistency across the code base, facilitate on-boarding of new team members, and lower long term maintenance costs, I’m proposing the following 15 design and C++ coding guidelines:

  1. Minimize macro usage.
  2. Use STL containers instead of homegrown ones.
  3. No unessential 3rd party libraries, with the exception of Boost.
  4. Strive for a clear and intuitive namespace-to-directory mapping.
  5. Use a consistent, uniform, communication scheme between application processes. Deviations must be justified.
  6. Use the same threading library (Boost) when multi-threading is needed within a process.
  7. Design a little, code a little, unit test a little, integrate a little, document a little. Repeat.
  8. Avoid casting. When casting is unavoidable, use the C++ cast operators so that the cast hacks stick out like a sore thumb.
  9. No naked pointers when heap memory is required. Use C++ auto and Boost smart pointers.
  10. Strive for pure layering. Document all non-adjacent layer interface breaches and wrap all forays into OS-specific functionality.
  11. Strive for < 100 lines of code per function member.
  12. Strive for < 4 nested if-then-else code sections and inheritance tree depths.
  13. Minimize “using” directives, liberally employ “using” declarations to keep verbosity low.
  14. Run the code through a static code analyzer frequently.
  15. Strive for zero compiler warnings.

Notice that the list is short, (maybe) memorize-able, and (maybe) enforceable. It’s an attempt to avoid imposing a 100 page tome of rules that nobody will read, let alone use or enforce. What do you think? What is YOUR list of 15?

  1. Ray
    February 1, 2010 at 8:47 am

    How about prohibition on using “break”s and “continue”s inside of any looping construct. They are today’s “goto”s.

    Also only one “return” per function/method and it has to be at the bottom of function. If it is returning a value that value should be calculated before the return not in the return.

    • February 1, 2010 at 9:58 am

      Hi Ray,

      If loops are short, I don’t see a huge problem here. Plus, a million other “guidelines” can be added and “argued about”, but that would defeat the purpose of a short list. What’s your list of 15?

  2. Francesco
    May 6, 2010 at 9:26 am

    Hi, I agree with your points.

    With respect to #14, which static code analyzers have you found / tried / recommend?

    • May 6, 2010 at 10:32 am

      Hi Francesco, and thanks for the feedback.

      Regarding static code analyzers, we haven’t adopted one or integrated it into our process yet. I’ve made a “mild pitch” to management for Coverity’s product, but it seems to have fallen on deaf ears. I haven’t researched any open source products yet, but it’s on my “to do” list. Actually, it’s been on my list for awhile now but it keeps falling to the bottom as I add new tasks. Nobody else seems to care, and that’s why it’s not a high priority for me at the moment.

      • Francesco
        May 6, 2010 at 3:56 pm

        I see and I know the process of adding new tasks displacing the previous ones šŸ™‚
        I am considering to adopt some static analysis tools, too. Unfortunately, the open source ones I tried up to now didn’t fare too well and I hoped that you could share some experience about commercial ones. Will have to continue looking šŸ™‚

  3. RajKumar
    May 18, 2010 at 2:32 pm

    you could make an exception for the Poco libraries šŸ˜› .

    • May 18, 2010 at 4:20 pm

      I could, but I don’t šŸ™‚

      As the post says, if a good case (essential) can be made to the “software lead” charged with maintaining the code’s conceptual integrity (which is often NO ONE), then the guideline could of course be “bent”. The main reason is to prevent unnecessary technology and complexity “proliferation” – which causes decreased/costlier maintenance downstream.

  1. April 30, 2010 at 5:01 am

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: