Go to the first, previous, next, last section, table of contents.


COMMENTING STYLES

FWEB allows a variety of commenting styles. The visible comments are in the font \cmntfont, which defaults to \mainfont, a ten-point Roman font.

Invisible comments

@z...@x -- If a source or include file begins with `@z' (in the
            very first two characters of the file), then all
            material is skipped until and including a line beginning in
            column 1 with `@x' (except that lines of the form
            $Keyword: text of keyword $ are processed; see
            section $KEYWORD:  Value of RCS-like keyword). 

@%       -- All material until and including the next newline is
            completely ignored.

@%%      -- As `@%', but also skip blank lines that immediately
             follow the current line.

For example,

@z
Author:  J. A. Krommes
@x
@c @% This sets the global language to C.
@* EXAMPLE.

Visible comments

`/* ... */' is a long comment (may extend over several lines).

`// ...' is a short comment (terminated by the next newline).

`@(...@)' is a meta-comment. Meta-comments are a localized form of the N mode (see section LANGUAGES). Tangled meta-comments are begun by the contents of the style-file entry `meta.top' and terminated by `meta.bottom'. Each line of the meta-comment is begun by `meta.prefix'. Woven meta-comments are begun by `meta_code.begin' and ended by `meta_code.end'. See section Miscellaneous style-file parameters.

@n
@a
        program main
/* Get input. */
        call get_input // Read the parameter file.
/* Process information.  Comments like this
   can be split over several lines. */
@(
Meta-comments provide a poor-man's alignment feature
 i -- counter
 x -- data value
@)
        i = 1
        x = 2.0
        call exec(i,x)
        end

The use of meta-comments is not recommended. Use ordinary long comments instead. Inside of them, use the various powerful features of TeX or LaTeX (such as \halign or \begin{verbatim} ... \end{verbatim}) to format your comment appropriately.

Temporary comments

During development, one frequently desires to temporarily comment out a section of code. C programmers sometimes try to do this by enclosing the code in /*...*/, but this is not good style for several reasons. First, it is impossible if the code itself includes comments, since comments do not nest in C. Second, FWEAVE will treat the commented code as TeX rather than C code and will format it very poorly.

The proper way of commenting out sections of code is to use preprocessor constructions: #if 0...#endif in C, or more generally @#if 0...@#endif (usable in all languages). (The FWEB preprocessor is described in section Preprocessing.) With this method, there is no trouble with nested comments, and FWEAVE will continue to format the code as code, so the documentation will make sense.


Go to the first, previous, next, last section, table of contents.