Archives

Page Ranking

Trailing Comments Formatter

Commenting properly your C/C++ code isn’t always an easy task. Comments can be messy or they can really tell the story or translate it for people interested in the code (including you after the years). There are two types of comments programmers use in their code:

  • block of comments, usually separated from the code (for example, function headers or file headers);
  • inline comments, usually inserted in the code in order to explain its functionality.

This post deals with the last type — the inline comments. These comments can be either placed on a separate line, usually, before the code they intend to explain, or as a trailing comments following the lines of code that require explanation. If you are like me, coming from years of trying different programming styles and standards, you may appreciate trailing comments more — C style (/* comment */) or C++ style (// comment). My preference for trailing comments, if properly used and aligned, comes from the fact that they can tell the story “in parallel” with the code. The source becomes a two column text with the left side the code itself and with the right side the “translation” (i.e. the comments telling the story). Here is an example:

PUBLIC QUE_ITEM                 QueAdd              (PQUEUE             pque,
                                                     QUE_ITEM           pv_item)
{/* ------------------------------------------------------------------------------------------- */
    QUE_ENTER_CRITICAL ();

    if (pque->full == TRUE)                         /* if queue already full                    */
    {
        QUE_EXIT_CRITICAL ();
        return NULL;                                /* return NULL for full                     */
    }
    pque->tail = INCMOD (pque->tail, pque->size);   /* increment tail mod size                  */
    if (pque->head == pque->tail)                   /* is the queue full?                       */
    {
        pque->full = TRUE;                          /* set the indicator and                    */
        QUE_EXIT_CRITICAL ();
        return NULL;                                /* return NULL for full                     */
    }
    QUE_EXIT_CRITICAL ();
    return (pque->data[pque->tail] = pv_item);      /* return pointer to a new object           */
}

The main reason people don’t use trailing comments is related to the alignment I mentioned above. Maintaining the alignment is tedious and time consuming: when writing the code it is probably counterproductive to align the trailing comments all the time or to realign the comments after making changes to the code.

The idea of a little utility was born from this simple observation: it is easier to just add trailing comments wherever is necessary without any alignment and align them automatically at the end. Moreover, this utility program can convert C style comments to C++ style comments and vice versa performing the alignment in the same time.

Introducing TCAlign

TCAlign is a trailing comment formatting utility for C/C++ source files that has no effect on C style comment blocks (i.e. multi-line comments).

In order to preserve some inline comments, TCAlign uses a sensitivity threshold defined as the column of text from where the utility will process the comments (i.e. anything before the threshold column remains untouched). For example, if the sensitivity threshold is 25, comments beginning in columns 1-24 will remain unaffected while comments starting in a column greater or equal to 25 will be aligned and/or changed style. Obviously, if you set the threshold too low, some one line comments will be changed as well. The minimum value for the sensitivity threshold is 4 (this is to avoid touching any comments starting in the first column and meant to be used as headers for files, functions, etc.) and its default value is 25.

The user can indicate the trailing comment preferred position; by default this position is in column 65. If a source line extends beyond this position, the comment will be simply appended at the end. I recommend that you try to write your code in such a way that you will avoid extremely long one line statements by breaking them logically in more shorter lines. The code will gain in readability and will allow you adding even more meaningful trailing comments. Personally, I try to keep my code between columns 1 and 64 but some may find this too restrictive (I prefer to work with the monitor in portrait mode). Considering your typical monitor and typical text editor or IDE, you should be able to use as much as 150…160 columns (or more for wide screen monitors). Selecting a preferred position of 80 could make more sense to you.

The other important parameter is the trailing comment preferred length; by default the length is 42 characters, again derived from my own personal preference. If a comment is longer than the preferred length, the program will use it as-is. Use a larger value if you prefer long lines.

Here is the command line syntax with explanations:

TCAlign -fi <input_file> [-fo <output_file>] [options]

where the input file name (fully qualified, including path if necessary) designates a text file that would be interpreted as C/C++ source file. The output file name is optional: if missing, the utility will create a backup file before generating the output so that you have the option to revert to the original. If the output file name is indicated, the program will use it for output; don’t use the same name as the input file name or you will get an error.

The options are:

-cpp    use C++ comments style (default is C style);
-th     sensitivity threshold for trailing comments (default is 25);
-cpos   trailing comment preferred position (default is 65);
-csz    trailing comment preferred size (default is 42);
-help   this help text (other arguments are ignored).

Notes:

  • make sure that 3 < th < cpos; eventually, TCAling will swap th and cpos values in an attempt to order them correctly;
  • the minimum value for th, cpos and csz is 4; a smaller value will be quietly replaced with its corresponding default.

Examples:

  1. Align trailing comments and change their style from C to C++ style using the default parameters:
    tcalign -fi acmgmt.c -fo acmgmt_fmt -cpp
  2. Align trailing comments and change their style from C++ to C style using a threshold column of 80 and a comment length of 50:
    tcalign -fi acmgmt.c -fo acmgmt_fmt -cpos 80 -csz 50

Download TCAlign and start formatting your trailing comments. The TCAlign utility will also work for C# and other “C like” source files.

Disclaimer: TCAlign was written in less than a day and it may not be perfect. I fixed several obvious problems but I might have left something behind. If you want to contribute, the source code is available here (released under GPL). I will definitely appreciate your feedback and enhancements. I will post theme all here on this page. Thank you.

 

 

Comments are closed.