Commenting style, was RE: [m-dev.] for review: MLDS backend to do structure reuse and compile time gc

[Fergus Henderson]

On Mon, Oct 09, 2000 at 10:45:15AM -0700, Ralph Becket wrote:
> I agree that mixing styles within a file is a bad thing.  But IMHO
> indented comments make code more legible since they are clearly
> separated from the code itself.

That's not my experience.  Code itself is often indented, either due
to its structure, or because lines often wrap.  So indenting comments
can and IMHO often does lead to situations where the comments are less
clearly separated from the code.

For example, from Tyson's IL back-end diff:

 |                     % Add a store after the alloc instrs (if necessary)
 |             { AllocInstrs = list__condense(tree__flatten(
 |                     tree(AllocComment,
 |                     tree(AllocInstrsTree, StoreAllocTree)))) },
 |                     % Add a load before the init instrs (if necessary)
 |             { InitInstrs = list__condense(tree__flatten(
 |                     tree(InitComment,
 |                     tree(LoadTree, tree(InitInstrTree, StoreInitTree))))) },

Here the comment is not clearly separated from the code, and even
worse the indentation makes it look like the second comment belongs
with the first goal.

-- 
Fergus Henderson <fjh at cs.mu.oz.au>  |  "I have always known that the pursuit
WWW: <http://www.cs.mu.oz.au/~fjh>  |  of excellence is a lethal habit"
PGP: finger fjh at 128.250.37.3        |     -- the last words of T. S. Garp.
--------------------------------------------------------------------------
mercury-developers mailing list
Post messages to:       mercury-developers at cs.mu.oz.au
Administrative Queries: owner-mercury-developers at cs.mu.oz.au
Subscriptions:          mercury-developers-request at cs.mu.oz.au
--------------------------------------------------------------------------