multiline comments

[Jorge Godoy]

Peter Tillotson wrote:

> 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

This is something that should be a policy: no untested and working code
should be commited to the trunk; if you need to commit it for any reason
create a branch and do it there.

> 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

Here I believe that no code revision system is a substitute for project.  If
you have two conflicting changes on the same line of code, then you surely
are missing some discussion on the code and more documentation on what is
being done / has been done.  Revision management is no substitute for
meetings and projects.

> 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.

I believe that it is easier to see multiple commented out lines than just
the beginning and ending of a multiline comment.  Specially when you're
screening the code instead of reading it line by line.

> Personally, I prefer clear code, minimally commented with good high
> level descriptions of particularly complex section / algorithms. The

We have the same taste, except that I prefer documenting more things than
just complex algorithms so I have a lot of comments and docstrings in my
code.

> 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.

I still believe that you're working with an inappropriate environment if
your editor can't use some extension for the language you choose (coming
from a Java background you might like PyDev on Eclipse, even though its
indentation features aren't as nice as Emacs' features...) or being able to
repeat the comment symbol from one line to the next when it wraps (keeping
indentation, of course!)

> 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 :-)

:-)  There's an approach that allows using those...  I don't remember which
docsystem allows for MathML markup.  But then, I'd go with DocBook + MathML
+ SVG ;-)  (Hey!  You started!  And you even said that you didn't like
verbose comments... ;-))

-- 
Jorge Godoy      <godoy at ieee.org>

"Quidquid latine dictum sit, altum sonatur."
- Qualquer coisa dita em latim soa profundo.
- Anything said in Latin sounds smart.