William Smith is the engineering manager at Montana Software, a sorftware development company specializing in custom applications for MS-DOS and Windows. You may contact him by mail at P.O. Box 663, Bozeman, MT 59771-0663.
C is a free format language. It opens the door to an infinite variation of appearances based on the programmers personal preference. Nearly every programmer has opinions, sometimes very strong, of how C code should be formatted. Arguments over curly brace placement, indentation, white space, and comment placement abound. Over time, programmers first become comfortable with a certain style, then attached and eventually religiously committed.
Style, especially the appearance aspect of style is a matter of personal taste. You can radically change the appearance of C without changing what the code does. Depending on the placement of indentation and white space you can make the code very readable or nearly unreadable. Obviously the goal is to use appearance to enhance the visibility of programming structures such as functions, blocks, loops, etc. Unfortunately what is readable and visible to one programmer is obfuscated to another.
C-Clearly by V Communications is a C & C++ source code formatting utility that claims to be able to give you complete control over code appearance. It is a "you can have it any way you like it" utility. C-Clearly attempts to be the ultimate code beautifier/formatter.
If true, it ends the argument on what appearance is appropriate. Every programmer can have it his or her own way. In a work group situation, programmers can use the style they are comfortable with and later reformat their code to the standards specified by the group. Alternatively, a programmer can take someone else's code and reformat it into the style that he or she is most comfortable with and efficient at reading. Sounds good in theory, but there are limitations.
First of all, style is not just where the curly braces go. Style consists of both structure and appearance. Structure involves programming constructs, variable naming, and the type of techniques to execute a certain process. C-Clearly cannot do anything about this aspect of coding style. What it can do is alter the appearance of code. And even this has its limits.
What C-Clearly Does
There are infinite combinations of appearance options for C and C++ code. Instead of a long list of command-line options or an input screen containing a myriad of check boxes and radio buttons, C-Clearly's user interface for selecting a specific combination of appearance options is a template file. The template file is a recipe of pseudo-C commands that set the formatting definitions.C-Clearly comes with six template files, three each for C and C++. Listing 1, knr. ccl, is the template file for K&R-style C code. You can create your own template file by starting with one of the delivered template files and editing it. You have to be careful when editing a template file. You can only modify the white space in the template file.
In addition to the this restriction, the fact that some constructs are defined in more than one place creates another restriction. The constructs that are defined in more than one place must be consistent or C-Clearly will warn you when you have conflicting appearance constraints.
C-Clearly supports both a command-line and an interactive user interface. The command-line interface is a subset of the interactive user interface. You cannot specify any style formatting options on the command line. You must use the interactive user interface to specify formatting options and then save them as the default.
C-Clearly stores the default settings directly in the executable file. This means it writes to and modifies the executable file. Most Anti-Virus software will detect this. So you will have to tell your Anti-Virus program to ignore this situation.
Besides the template file there are four categories of additional appearance choices. The first category involves margins, tabs, and nesting lines. Nesting lines involve adding lines to show the connection between the beginning and end of logical blocks.
The second category involves comments. You can select how to align and group comments. C-Clearly will make attempts to beautify comments, but I have never found what it does to my liking. I usually turn most of the comment formatting options off.
The third category applies to white space. You can tell C-Clearly to retrain existing blank lines depending upon their placement.
The fourth category is for hardcopy output only. You can send the output directly to a printer or to a file that is ready to print. When generating hardcopy output, C-Clearly can add line numbers, printer escape codes, and additional information such as headers, footers, and code metrics information. By inserting printer escape codes around different code constructs you can select printing styles or fonts. For example, you can print all comments in italics. There are no printer drivers so you will have to determine the escape codes for the printer you are using.
The combination of code templates, an interactive user interface for additional style selection, and a terse commandline interface works well for C-Clearly. I find it quite easy to use.
The user manual is perfect bound and about 55 pages in length. Chapter 2 covers template files. It is only a couple of pages in length, but if you are going to create your own template file it is must reading.
This all sounds good until you have to start formatting some code. Even though C-Clearly has a lot going for it, it has some severe limitations. As soon as you are faced with the chore of formatting files, you will most certainly bump up against C-Clearly's unfortunate limitations.
What C-Clearly Doesn't Do
C-Clearly requires syntactically correct source code. This in itself is not that big a drawback. If your code complies it is probably syntactically correct. Well, not always, according to C-Clearly. C-Clearly does not like some C constructs that are rigorously correct in syntax and compile just fine.The ability of C-Clearly to have so much control and flexibility in formatting code means that it has to parse and understand code nearly to the same level as a compiler. Unfortunately, it chokes on many complex but entirely valid C constructs. When C-Clearly finds a syntax it does not like, it quits and makes no further attempt to format the file.
This problem is a serious flaw in C-Clearly. It truly cripples an otherwise fine product. From experience, an important area of weakness that I have identified is in handling types and macros that deal with types.
C-Clearly has trouble dealing with typedefs, structures, defines, and variables that happen to have the same name. This may not be a good idea to have the same name for all these different things, but it is valid. C-Clearly also has problems with macros that expand to structure member references. For example macros similar to the following have caused me trouble with C-Clearly.
#define MEMBER StructInstance->MemberThe token pasting preprocessor operator, ##, can also cause C-Clearly to fail on perfectly correct code.Sometimes you can coax C-Clearly to still format a file by turning off formatting or syntax checking for the sections it can not handle. This has the drawback of requiring you to insert C-Clearly instructions in the form of specialized comments into your code. It may still not get some files to work. C-Clearly ignores the code that you have flagged and then expects the unflagged code to still be syntactically correct.
Since C-Clearly has the bad habit of not liking certain code structures and flagging them as syntax errors, I have found it useful to monitor the program's return code from within a batch file. Although not documented in the users manual, C-Clearly returns 1 if it fails. You can access this in a batch file as the MS-DOS errorlevel. I use this technique to conditionally execute further processing on the source file after C-Clearly.
I have not had success getting C-Clearly to consistently output tabs for indentation. Consequently, I process the file after C-Clearly to convert groups of leading spaces to tabs. The following is an MS-DOS batch file listing.
CCL %1 OUTPUT.CCL IF ERRORLEVEL 1 GOTO :EXITERROR ENTAB OUTPUT.OUT 8 COPY OUTPUT.OUT %1 :EXITERROR ERASE OUTPUT.CCLI also add the comment, /* End of File */ to the end of every source file. Although C-Clearly can add comments to closing braces, it does not add comments (footers) to file output. You can add footers to hard-copy (printer-ready) output.I have an additional major complaint. Even with all of its flexibility, I cannot get C-Clearly to format code exactly the way I want. The problem is with long expressions that must be continued on multiple lines. With very long source lines, I like to find a convenient place to make a new line and continue the expression on the next line indented two levels from the indent level of the expression. Try as I might, I have not been able to get C-Clearly to do this exactly the way I want. I cannot even get it to leave continued lines alone. Since C-Clearly comes so close to giving you what you want and your expectations are high, this is especially annoying.
The other complaints stem from the limitations of memory imposed by MS-DOS. I have started to run out of memory with long listings, especially code for Microsoft Windows that include WINDOWS.H. Since WINDOWS.H is more than 5,000 lines in length, this is not surprising. As file length goes up, C-Clearly gets significantly slower. A protected-mode version may remedy these problems.
User Support — Upgrade Policy
I started using C-Clearly when it first came out about three years ago. I expected a lot from the product. I was not shy in calling V Communications and expressing my desires for C-Clearly to do something that it presently could not do or pointing out limitations and bugs in the product. V Communications responded with a closely-spaced series of upgrades. Many of these upgrades came free of charge.This experience and the ease of access to the technical people involved with the product impressed me. V Communications seemed committed to a quality product and committed to user support.
C-Clearly has evolved to a state that works for me. I have found work arounds for most of the limitations and rarely contact the company anymore. The last upgrade cost me $45.00.
Conclusions
C-Clearly ambitiously sets out to be the ultimate C and C++ source code reformatting utility. It comes close. It fails in two critical areas. The first is that I cannot get C-Clearly to format code exactly the way I want it. The other serious flaw is that it will not format some perfectly good code. It stops when it thinks it has found a syntax error or runs low on memory.If you are willing to live with these limitations, C-Clearly is a powerful source code maintenance tool. I have found it useful and use it frequently. I have also found it frustrating and nearly always do additional processing to files after C-Clearly is done with them.
When I have to read someone else's code that is in a style I am not comfortable with, C-Clearly has come to my rescue many times. C-Clearly is not a replacement for good coding style rules such as choice of variable names, consistency, and commenting, but it sure helps put to rest some of the code appearance arguments.
Note from the editor:
V Communications has released version 2.1 of C-Clearly which addresses some of the limitations outlined in this review. For specific differences please contact V Communications.C-Clearly, Version 2.0
V Communications, Inc.
4320 Stevens Creek Blvd., Suite 275
San Jose, CA 95129
Phone: 800-648-8266
Price: $129.95
Hardware Requirements: IBM PC Compatible, MS-DOS, and 512K RAM