multiline comments

[Peter Tillotson]

Ben Finney wrote:
> "Atanas Banov" <enterr at gmail.com> writes:
> 
>> Edward Elliott wrote:
>>> Saying coders shouldn't use multiline comments to disable code
>>> misses the point.  Coders will comment out code regardless of the
>>> existence of multiline comemnts.  There has to be a better
>>> argument for leaving them out.
>> i beg to differ: you'd be surprised how much effect can little
>> inconveniences have.
>>
>> want to comment block of code? use tripple-quotes. does not nest?
>> ahhh, maybe it's time to get rid of that block you commented out a
>> month ago "just in case the new code doesnt work".
> 
> Indeed. Using revision control means never needing to comment out
> blocks of code.
> 
> If your revision control system is so inconvenient to use that you'd
> rather have large blocks of commented-out code, it's time to start
> using a better RCS -- perhaps a distributed one, so you can commit to
> your own local repository with abandon while trying out changes.
> 

I'm not sure I agree, revision control is great but not the only answer.
In multi-developer teams working on the trunk, it its kind of
inconvenient if someone checks in broken code. It also blocks critical
path development if the person responsible for the code you conflict
with happens to be out on holiday. Block commenting is a clear flag to
that developer that something has changed - ideally he'd notice, see
sensible revision control comments, see the flag on the wiki or you
would remember to tell him. But if all of that fails, if it is commented
in the code it should get picked up at a code review.

Personally, I prefer clear code, minimally commented with good high
level descriptions of particularly complex section / algorithms. The
later doesn't always fit neatly on one line. There is an argument that
these should go into their own functions and be commented at the
function level. Again I'm not sure I agree entirely - function comments
that are auto extracted to create api docs (sorry Java background :-))
need only outline What a function does. There is a place for multiline
comments to describe How that is achieved.

Having said all that, I generally don't like comments, they are often
maintained poorly, too numerous, too verbose (red rag :-)) - so i'm
undecided whether they should be made easier for developers or
discouraged except where vital. Perhaps we should make them really hard
and elegant - mandate latex/mathml markup so good editors can display
the equations we are implementing :-)