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 -- http://mail.python.org/mailman/listinfo/python-list
