Commenting calculations

[LaRetta]

There are two methods of commenting calculations:

C style which beings with /* and ends with */

C++ style which starts with // and ends at end of line

When reading calculations, C style (appears) more cluttered, requires more typing, and requires remembering to close it. Nesting sounds good but a hard return in the calc would achieve the same results and no close required. C style opens up possibility of errors (forgetting to add the close) or even using it when not needed as FM even demonstrates (I'm sure without meaning to). From FM Help:

Everything shown below can be entered inside a formula:

/* This is a calculation with C style nested and multi-line comments

/*----- It returns the title if it exists in a name -----*/ [color:blue] (why another open here? It wasn't closed on the prior line.)

*/ [color:blue] (Close it so it closes the first line. But why open and close on the prior line? Good grief - open, close, open, close.)

Case(

PatternCount("MrMsMrs", LeftWords(Name, 1)), /* returns true if the first word in fieldName matches anyone of the titles Mr, Ms or Mrs*/ [color:blue](FM unnecessarily puts a hard return here which diminishes the power of C style's nesting for the example). In fact, it DOESN'T show it nested at all.

LeftWords(Name, 1) /*extracts the title */

)

I realize they are attempting to show C style nesting abilities but using it on 3 comments doesn't work for me. It could be more simply written as:

// This is a calculation with C style nested and multi-line comments

// It returns the title if it exists in a name

Case (

PatternCount("MrMsMrs", LeftWords(Name, 1)) // returns true if the first word bla bla ...

LeftWords(Name, 1) // extracts the title

I would never want to insert a comment within a calc without a hard return separating it anyway or without the comment appearing at the end of the line. Maybe (for me at least) this:

// This is a calculation with C style nested and multi-line comments

// It returns the title if it exists in a name

... looks more like commenting scripts and is much more readable.

This seems like a small thing but before I adopt one style or the other (and let it become habit), I wanted to understand. Is one method more sound, more efficient, or more 'standard' than the other? If both work as well then C++ seems cleaner. I can see no reason that 'nesting' abilities with comments would be of benefit. If I want to comment out a portion of a calc, I insert // at the beginning and place a hard return.

Can anyone give me an example when using C style's nesting would be helpful here? Because FM's example just doesn't convince me.

LaRetta

[Raybaudi]

Hi LaRetta

I like to use comments with C style, obviously without nesting.

And a good reason to use that type of comment is when you write your code; if you wish to try another calc, simply use 2 tag (one at start and another to end) to enclose all the previous calc.

But when i want to change only a line, the C++ type is better.

[Genx]

Not sure why you would nest them, but i use C when i want to comment out 4 or 5 lines directly, and then C++ much more often to comment out individual lines.

[SteveB]

I use C Style at the top of a CF, since this style allows for multiple lines. I list a CF as follows:

/*

CF: ParseParam: This CF performs the .....

start: Contains...

end: Contains....

list: Contains...

Usage:

*/

The 'C' style is more convenient in this case because the comment extends over multiple lines. The above also makes it easy to copy CFs between files since the entire function including name and parameters get copied all at once...no looking back for names, spelling, etc.

Steve

Edited July 23, 2006 by Guest

[T-Square]

I use the C-style comments because I find them visually clearer, which is purely subjective. I guess i could say that it helps me see where the comments start AND end. Once I learned to remember that the asterisks go closest to the comment, it has become second nature.

WRT the embedded C comments, you're right they're redundant, but that sort of thing happens to me all the time when I am debugging, and I comment out (I almost said "REM out"--that surely ages me!) a section that includes my ever-helpful (HAH!) code comments.

Cheers,

David