program codecomments(input, output);
(* codecomments: comment density of a pascal program

  Dr. Thomas D. Schneider
  National Cancer Institute
  Laboratory of Experimental and Computational Biology
  Frederick, Maryland  21702-1201
  toms@ncifcrf.gov
  permanent email: toms@alum.mit.edu
  http://www.lecb.ncifcrf.gov/~toms/

   modules: delman *)

const
(* begin module version *)
version = 2.10; (* of codecomments.p 2001 June 7
2001 Jun  7, 2.10: lowest percentage is 30
2001 Jun  7, 2.09: output upgrade
2000 Oct 24, 2.07: change name from code.p to codecomments.p
                   use standard input instead of fin
2000 May 26, 2.06: last change
1986 dec 9 last major change as code.p
origin before 1982 august 29 *)
(* end module version *)

(* begin module describe.codecomments *)
(*
name
   codecomments: find the comment density of a pascal program

synopsis
   codecomments(input: in, output: out)

files
   input: a pascal source code.
   output: a report on the comment density of the pascal program.

description

   With the comment density program, you can find out how much of your
   program is devoted to comments.  In general, the better programs will have
   more comments than those that are poor.  The program gives you the percent
   of characters devoted to comments.  A typical value should probably be
   around 50 percent of the characters devoted to description.  Suggested
   places to put comments are in the delman manual in the module
   delman.guide.programming.

examples

   Here is the distribution of comments in all Delila programs
   on 2000 Oct 24:

* genhis 1.75: generalized histogram data from
* name percent
*
* parameters:
*          6  is the data column used
*        314  numbers are in the file
*   31.60000  is the minimum number
*   91.60000  is the maximum number
*   52.11592  is the MEAN
*   11.50619  is the STANDARD DEVIATION
*    0.65037  is the STANDARD ERROR OF THE MEAN (SEM)
*  132.39246  is the variance
*    3.41127  is the uncertainty in bits
*    5.57143  is the computed uncertainty in bits (Shannon p.57)
*
*    0.00000  to   100.00000 is the range of data plotted
*    4.00000  is the x-axis interval
*     26     is the number of intervals
*         51 is the maximum y-axis value
*    1.00000 is the y-axis scale
*
* gaussian standard plotted
*
* interval    histogram
* beginning     value
*
    0.00000          0   
    4.00000          0   
    8.00000          0   
   12.00000          0   
   16.00000          0   :
   20.00000          0   :
   24.00000          0     :
   28.00000          1   +     :
   32.00000          9   +++++++++   :
   36.00000         26   ++++++++++++++++++++*+++++
   40.00000         50   +++++++++++++++++++++++++++++*++++++++++++++++++++
   44.00000         51   +++++++++++++++++++++++++++++++++++++*+++++++++++++
   48.00000         41   +++++++++++++++++++++++++++++++++++++++++ :
   52.00000         41   +++++++++++++++++++++++++++++++++++++++++ :
   56.00000         25   +++++++++++++++++++++++++            :
   60.00000         14   ++++++++++++++               :
   64.00000         21   ++++++++++++++++++++*
   68.00000         15   ++++++++++++*++
   72.00000         10   ++++++*+++
   76.00000          5   ++*++
   80.00000          0   :
   84.00000          2   *+
   88.00000          3   +++
   92.00000          0   
   96.00000          0   
  100.00000          0   

documentation

see also

   {Current list of Delila programs and graph of % comments:}
   http://www.lecb.ncifcrf.gov/~toms/timelist.html

   decom.p

   nocom.p

   genhis.p

   http://www.lecb.ncifcrf.gov/~toms/delman1.html

author

   Thomas D. Schneider

bugs

   The program does not keep track of blanks, so one's style with
   blanks could affect the percentage.

   The program does not know about comments of the form {}

   The program does not handle comments inside quotes.

*)
(* end module describe.codecomments *)

(* more const *)
      debugging = false; (* to write debug output *)

var
      numchar,    (* number of characters *)
      numcomchar, (* number of characters in comments *)
      numcom,     (* number of comments *)
      numline:    (* number of lines *)
         integer; (* in the input file *)
      comment: boolean; (* true when inside a comment *)

      first, second: char; (* two neighboring characters in input *)
      percent: real; (* the percent of comments in the program by characters *)

begin
      writeln(output, ' codecomments ', version:4:2,
                     ': comment density of a pascal program');
      writeln(output, ' Only comments of the form (* ... *) are recorded, ');
      writeln(output, ' including comments inside quote marks...'); (* zooks *)
      writeln(output);

      (* initialize *)

      numchar:=0;
      numcomchar:=0;
      numcom:=0;
      numline:=0;
      comment:=false;

      if not eof(input) then begin
         read(input, second); (* first will be set below *)
         numchar:=succ(numchar)
      end;

      while not eof(input) do begin
         if eoln(input)
         then begin
            readln(input);
            numline:=succ(numline);
            second:=' '; (* block fragmented comments from being recorded *)
            if debugging then writeln(output, 'eoln ', numline:3)
         end
         else begin
            (* step forewards *)
            first:=second;
            read(input, second);
            numchar:=succ(numchar);
            if debugging then write(output, second, numchar:3);

            case comment of
               false: if first = '(' then if second = '*' then begin
                  comment:=true;
                  numcom:=succ(numcom);
                  numcomchar:=numcomchar+2 (* count comment start *)
               end;
               true: begin
                  numcomchar:=succ(numcomchar);
                  if first = '*' then if second = ')' then comment:=false
               end
            end;
            if debugging then if comment then writeln(output, 'c')
                                         else writeln(output)
         end
      end;

      writeln(output, ' number of characters: ', numchar:1);
      writeln(output, ' number of lines: ', numline:1);

      if numchar <> 0 then begin
         writeln(output, ' number of comment characters: ', numcomchar:1);
         writeln(output, ' number of comments: ', numcom:1);
         percent := 100*(numcomchar/numchar);
         writeln(output, ' percent comments by characters: ', percent:3:1);
         if percent < 30
         then writeln(output, ' The program needs more comments!')
         else writeln(output);
      end
end.