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 <[EMAIL PROTECTED]> "Quidquid latine dictum sit, altum sonatur." - Qualquer coisa dita em latim soa profundo. - Anything said in Latin sounds smart. -- http://mail.python.org/mailman/listinfo/python-list
