Enforcing Standards with CodeCheck
Overview
CodeCheck is a tool for professional programmers which detects violations of standards for C++ source code. It works very much like a compiler, in that it reads parses and understands every line of code, including lines in header files, exactly the way a compiler does. However, instead of compiling the source code into machine code, CodeCheck detects violations of a specified set of coding rules, and issues warning messages and advisories. In other words, CodeCheck performs an automated code walk-through, using a set of coding rules to determine when the standards have been violated.
CodeCheck is a command-line tool, similar in operation to most Unix, DOS, and VMS tools. Windows and OS/2-PM programmers must use a DOS shell to run CodeCheck, while Macintosh programmers must use the MPW shell.
In order to find the header files that each source file includes, CodeCheck must know which directories to search. In most cases, the CodeCheck user lists these directories in an environmental variable named INCLUDE. Please see the CodeCheck Technical Notes for discussion and examples of environmental variables for each operating system.
In a typical application of CodeCheck, (using the XYZ Coding Rules, for example), the CodeCheck user only wishes to apply to coding rules to the source and header files that comprise the current project, and does not want to apply these rules to "standard" C and C++ headers, nor to libraries that have already been thoroughly tested. In this case, once again, CodeCheck needs to know which directories contain source and header files that are to be checked, and which directories are to be excluded from checking. The directories that are to be excluded are listed in the environmental variable CCEXCLUDE. Again, please see the CodeCheck Technical Notes for discussion and examples of environmental variables for each operating system. Coding rules will be applied to all source and header files in any directory not listed in this environmental variable.
In order to find the CodeCheck rule files that the user might wish to apply, CodeCheck must also know which directories to search for rule files. These are listed in the environmental variable named CCRULES. Please see the CodeCheck Technical Notes for discussion and examples of environmental variables for each operating system.
CodeCheck Messages and Options
CodeCheck sends all advisory messages to the stderr output stream. Each message includes the file name and line number of the line that contained the problematic code. To see these messages in the exact context in which they occurred, have CodeCheck generate a listing file (use the -L option). The listing file will show each advisory message immediately underneath the offending line of code, with a marker pointing to the token that was being parsed when the message was triggered.
Most professional-grade C and C++ code makes extensive use of the preprocessor to selectively suppress platform-specific and debugging code. The CodeCheck listing file clearly distinguishes suppressed code from live code, by simply omitting line numbers on lines that are suppressed by the preprocessor. This can be extremely useful when trying to determine which code the compiler actually sees when it parses the source code.
To have CodeCheck display all preprocessor macros completely expanded in the listing file, use the -M option. When this option is in force, every line that contains a macro will be shown twice: first before expansion, and second after all macros have been expanded. This feature can be invaluable when debugging complex or deeply nested macros.
To have CodeCheck display all header files in the listing file, use the -H option. Although this may create huge listing files, it is essential when trying to debug C++ class libraries (which are normally defined in headers).
Alone among all command-line shells, MS-DOS does not allow the programmer to redirect the stderr output stream to a file. For deprived DOS users, CodeCheck provides a special option (-O), which causes CodeCheck to send all advisory and error messages to a file named "stderr.out" instead.
Assuming that all CodeCheck users will use the INCLUDE and CCEXCLUDE environmental variables to control which source and header files are read and checked, the -S3 option should always be specified. This option tells CodeCheck to check every header file, except those in specifically excluded directories.
Special Keywords and C++ Dialects
CodeCheck can handle all of the common C and C++ dialects, as implemented by the major compiler vendors. Each of these dialects differs from standard C or C++, usually by virtue of having its own special reserved keywords (e.g. near, far, huge) and predefined macro constants (e.g. __BORLANDC__). Many dialects also have language extensions, in the form of special grammatical constructions that are not allowed in ANSI standard C or C++. Because of these dialectical variations, CodeCheck needs to know which compiler is being used to compile the source code. This is true even if the source code is pure ANSI standard, because the compiler vendor's header files usually make use of these extensions. The -K option informs CodeCheck which compiler the source code is intended for.
In addition, the user can predefine macro constants on the command line, with the -D option. This option works in exactly the same way for CodeCheck as it does for the major compilers.
Suggested CodeCheck Options for XYZ
First, remember to set the INCLUDE and CCEXCLUDE environmental variables. Without this information, CodeCheck cannot function properly.
For a project that uses Microsoft C++ on a DOS or Windows machine, when a full listing file is desired, the following command line will cause CodeCheck to apply the XYZ coding rules to all source files in the current directory:chk32 -Rxyzrule -K7 -L -H -S3 *.c
The option -K7 identifies the dialect used by all Microsoft C++ compilers. For a project that uses generic (AT&T) C++ on a Unix machine, only the -K option changes:check -Rxyzrule -K4 -L -H -S3 *.c
For a project that uses Borland C++ on an OS/2 machine, once again only the -K option changes:check -Rxyzrule -K6 -L -H -S3 *.c
As an alternative to the wildcard file specification in the above examples, it is possible to list explicitly every file that is to be checked, or to list the name of a file that simply contains the name of every file that is to be checked. The latter is called a "project file", and must have the extension ".ccp". Common command-line options can also be placed at the beginning of the project file, one per line. See the CodeCheck Reference Manual for details about project files.