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 global RCS-like keyword, section `@K': Extract global RCS-like keyword (source files), or section `@k': Access local RCS-like keyword (include files)].
@%
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 (it 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-person'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; they are only marginally supported. 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 (at best) format it very poorly. In fact, LaTeX will frequently complain, because the commented code might contain characters such as underscores that TeX expects to be in math mode. (Those are dealt with automatically when @FWEAVE{} is in code mode.) The trivial example `/* a_b; */' is sufficient to illustrate this point.

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.

For FORTRAN programmers converting an existing code to @FWEB{}, the `-nC' option (see section `-nC': Ignore single-line comments [FORTRAN]) may be helpful.


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