multiline comments

[Peter Tillotson]

nice one Jorge :-)

Jorge Godoy wrote:
> 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.
typo

committing broken code to trunk should punishable by stocks at least --
perhaps a public flogging.

Though on a serious note, you need a good reason for creating arbitrary
branches and a clearly defined naming policy. You also need to remember
to get off the branch asap before you inadvertently start a major fork.

>> 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!)
Sadly i don't get to code at the coalface much recently. I've tinkered
in python with pydev and vi over the last couple of years - i just
really dislike coding on a white background. I'm sure eclipse can do it
- i'm just not sure i've got the perseverance to work out how.

>> 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... ;-))
> 
oooh - but surely a picture is worth a thousand words and with SVG no
truer word was spoken :-)

I was only half kidding about latex. I can just about read pure latex
but that human readable xml stuff always defeats me