35.4 recomment: Clean Up Program Comment Blocks

Lines in a program's comment block usually start with one or more special characters, like:

# line 1 of the comment
# line 2 of the comment
# line 3 of the comment
    ...

It can be a hassle to add more text to one of the comment lines in a block because the line can get too long, which requires you to fold that line onto the next line, which means you have to work around the leading comment character(s).

The fmt (35.2) program neatens lines of a text file. But the standard fmt won't help you "neaten" blocks of comments in a program: it mixes the comment characters from the starts of lines with the words. (If your fmt has the -p option, it handles this problem; there's an example below.) The recomment script is fmt for comment blocks. It's for people who write shell, awk, C, or almost any other kind of program with comment blocks several lines long.

I usually use recomment from inside vi, with filter-through (30.22) commands like:

!}recomment reformat to the next blank line
5!!recomment reformat this line and the next 4

Normally, recomment lets fmt choose the width of the comment block (72 characters, typically). To get another width, you can either:

• Give the width on the command line, like this:

  recomment -50

• Set an environment variable named CBLKWID. Give the maximum width, in characters, for the comment text. For example, in the C shell, use:

  % setenv CBLKWID 50

recomment isn't perfect, but it's usually much better than nothing! Here's the part of the script that does the work. The first two commands get the comment character(s) and count their length. The next three commands strip the comment characters, clean up the remaining comment text, and add the same comment characters to the start of all reformatted lines:

expr

# GET COMMENT CHARACTERS USED ON FIRST LINE; STORE IN $comment: comment="`sed -n \"1s/^\([$cchars]*\).*/\1/p\" $temp`" # GET NUMBER OF CHARACTERS IN COMMENT CHARACTER STRING: cwidth=`expr "$comment" : '.*'` # RE-FORMAT THE COMMENT BLOCK. IF $widopt SET, USE IT: colrm 1 $cwidth < $temp | # STRIP OFF COMMENT LEADER FROM LINES fmt $widopt | # RE-FORMAT THE TEXT, AND sed "s/^/$comment/" # PUT THE COMMENT CHARACTERS BACK

If your system doesn't have the colrm (35.15) utility, change the third-to-last line to use cut (35.14) instead:

cut -c`expr $cwidth + 1`- < $temp |  # STRIP OFF COMMENT LEADER

That makes a command like cut -c4- instead of colrm 1 3.

Some versions of fmt (like the one on the CD-ROM) have a -p option that does the same thing. Unlike the automatic system in recomment, you have to tell fmt -p what the prefix characters are. For example, here's the start of a C program. The prefix character is *:

% cat prog.c
/*
 * This file, load.cc, reads an input 
 * data file. 
 * Each input line is added to a new node
 * of type struct Node.
 */
% fmt -p '*' prog.c
/*
 * This file, load.cc, reads an input data file.  Each input line is
 * added to a new node of type struct Node.
 */