multiline comments
in [Python]
|
From: Jorge Godoy on 19 Apr 2006 07:40 Edward Elliott wrote: > Sure they can be abused. So can a thousand other language features. My > point is you can't teach good coding through syntax, and trying to causes > more problems than it solves. I like the phrase: there are some languages that incentivates bad practices in programming; there is Python that doesn't. Some rigid syntax indeed makes you think one way -- and that's one of Python's motto, isn't it? "There's one right way to do it" -- but that will make your code more understandable and readable in the future. > I would argue the current system is in fact slightly worse, because people > will comment out code chunks anyway (either lots of #s or triple-quotes) > and are less likely to remove them when it's more work. But either way, > social pressure is infinitely more effective at cleaning up code than > comment syntax. Is it harder to remove "n" lines of code commented out with "#" than "n" lines of multiline commented code? How? The same question goes for triple quoted code. -- Jorge Godoy <godoy(a)ieee.org> "Quidquid latine dictum sit, altum sonatur." - Qualquer coisa dita em latim soa profundo. - Anything said in Latin sounds smart.
From: Jorge Godoy on 19 Apr 2006 07:49 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(a)ieee.org> "Quidquid latine dictum sit, altum sonatur." - Qualquer coisa dita em latim soa profundo. - Anything said in Latin sounds smart.
From: Jorge Godoy on 19 Apr 2006 07:51 Edward Elliott wrote: > And when the section I want to comment out contains a legit doc string in > the middle, triple-quotes won't work. There are valid reasons to nest You can use either """ or '''. I don't keep changing them in my code, so I can always use the other type (usually I use " so for commenting things out I'd use ') to do that. > comments which have nothing to do with laziness or sloppy code. > > Forcing programmers to write clean code with syntax is like teaching a pig > to sing: it wastes your time and annoys the pig. Good coding is a state > of mind, not a parser option. If the latter can help, why not? -- Jorge Godoy <godoy(a)ieee.org> "Quidquid latine dictum sit, altum sonatur." - Qualquer coisa dita em latim soa profundo. - Anything said in Latin sounds smart.
From: Peter Tillotson on 19 Apr 2006 08:51 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
From: Sion Arrowsmith on 19 Apr 2006 10:39
Edward Elliott <nobody(a)127.0.0.1> wrote: >On top of that, the expressive power of nested comments seems greater than >an endless string of ^#s. Sometimes it's just easier to see what's going on. Really? Under what circumstances is it easier to see what's going on with start/end comments than with comment-to-end-of-line? -- \S -- siona(a)chiark.greenend.org.uk -- http://www.chaos.org.uk/~sion/ ___ | "Frankly I have no feelings towards penguins one way or the other" \X/ | -- Arthur C. Clarke her nu become? se bera eadward ofdun hl?ddre heafdes b?ce bump bump bump |