User`s manual

Dynamic C User’s Manual digi.com 109

6.5 Debug Strategies

Since bug-free code is a trade-off with time and money, we know that software has bugs

. This section dis-

cusses ways to minimize the occurrence of bugs and gives you some strategies for finding and eliminating

them when they do occur.

6.5.1 Good Programming Practices

There is a big difference between “buggy code” and code that runs with near flawless precision. The latter

program may have a bug, but it may be a relatively minor problem that only appears under abnormal cir-

cumstances. (This touches on the subject of testing, which are the actions taken specifically to find bugs, a

larger discussion that is beyond the scope of this chapter.) This section discusses some time-tested methods

that may improve your ability to write software with fewer bugs.

• The Design: The design is the solution to the problem that a program or function is supposed to solve.

At a high level, the design is independent of the language that will be used in the implementation. Many

questions must be asked and answered. What are the requirements, the boundaries, the special cases?

These things are all captured in a well thought out design document. The design, written down, not just

an idea floating in your head, should be rigorous, complete and detailed. There should be agreement and

sign-off on the design before any coding takes place. The design underlies the code—it must come first.

This is also the first part of creating full documentation.

• Documentation: Other documentation includes code comments and function description headers,

which are specially formatted comments. Function description headers allow functions from libraries

listed in lib.dir to be displayed in the Function Lookup option in Dynamic C’s Help menu (or by

using the keyboard shortcut Ctrl+H). See Section 4.24 for details on creating function description head-

ers for user-defined library functions.

Another way to comment code is by making the code self-documenting: Always choose

descriptive names for functions, variables and macros. The brain only has so much memory

capacity, why waste it up by requiring yourself to remember that cwl() is the function to call

when you want to check the water level in your fish tank; chk_h20_level(), for example, makes

it easier to remember the function’s purpose. Of course, you get very familiar with code while

it is in development and so your brain transforms the letters “cwl” quite easily to the words

“check water level.” But years later when some esoteric bug appears and you have to dig into

old code, you might be glad you took the time to type out some longer function names.

•

Modular Code: If you have a function that checks the water level in the fish tank, don’t have the same

function check the temperature. Keep functions focused and as simple as possible.

i. For an account of what can happen when time and money constraints all but disappear, read

“They Write the Right Stuff” by Charles Fishman.