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

[Peter Ross]

On Wed, Oct 11, 2000 at 06:40:51PM +1100, Fergus Henderson wrote:
> 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.
> 
			% 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 is how I would indent the same bit of code, not that line
continuations are always indented two tabs to avoid the problem you mentioned.
--------------------------------------------------------------------------
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
--------------------------------------------------------------------------