Velocity Reviews - Computer Hardware Reviews

Velocity Reviews > Newsgroups > Programming > Python > multiline comments

Reply
Thread Tools

multiline comments

 
 
Roel Schroeven
Guest
Posts: n/a
 
      04-19-2006
Duncan Booth schreef:
> Would you care to name a few languages which support nested block
> comments? There really aren't many: ML as you mentioned; Standard Pascal
> doesn't permit nesting of comments but *some* implementations do allow it.
>
> Want to comment out a block of code in C++? The only (nearly) reliable way
> is to insert single-line comments down the block. You can't use a block
> comment if there are any other block comments inside the code you want to
> block out.


Depends, some compilers support that. But the preferred way, which works
very well, is to use preprocessor directives:

#if 0
...
#endif

Works in both C and C++.

--
If I have been able to see further, it was only because I stood
on the shoulders of giants. -- Isaac Newton

Roel Schroeven
 
Reply With Quote
 
 
 
 
Edward Elliott
Guest
Posts: n/a
 
      04-19-2006
Duncan Booth wrote:
> Want to comment out a block of code in C++? The only (nearly) reliable way
> is to insert single-line comments down the block. You can't use a block
> comment if there are any other block comments inside the code you want to
> block out.


As Roel said, #if 0 is the standard way. It abuses the preprocessor and
doesn't show up in syntax highlighting, but other than that works very
well. Honestly though, /* and */ should have nested properly since day 1.
Adding it wouldn't even break existing code.

> The danger of block comments is that if you forget to close the comment
> you can accidentally comment out a large part of your code.


No, unclosed comments should raise a syntax error. Would you accept an
unclosed string literal?

> Doc strings will usually work as an alternative, especially since you
> have a choice of two flavours of triple quoted strings, so if you use
> one for docstrings the other is always free for your temporary block
> comments.


That's a fair point, if a bit of a kludge. 90% there is good enough in
practice.

> This pig gets much more annoyed having to maintain code which has large
> chunks of unneeded commented out code left over from some other programmer,
> or which has completely messed up indentation.


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 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.
 
Reply With Quote
 
 
 
 
Gregor Horvath
Guest
Posts: n/a
 
      04-19-2006
Edward Elliott schrieb:

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


not if you are using grep

--
Gregor
http://www.gregor-horvath.com
 
Reply With Quote
 
Peter Tillotson
Guest
Posts: n/a
 
      04-19-2006
Ben Finney wrote:
> "Atanas Banov" <(E-Mail Removed)> writes:
>
>> Edward Elliott wrote:
>>> Saying coders shouldn't use multiline comments to disable code
>>> misses the point. Coders will comment out code regardless of the
>>> existence of multiline comemnts. There has to be a better
>>> argument for leaving them out.

>> i beg to differ: you'd be surprised how much effect can little
>> inconveniences have.
>>
>> want to comment block of code? use tripple-quotes. does not nest?
>> ahhh, maybe it's time to get rid of that block you commented out a
>> month ago "just in case the new code doesnt work".

>
> Indeed. Using revision control means never needing to comment out
> blocks of code.
>
> If your revision control system is so inconvenient to use that you'd
> rather have large blocks of commented-out code, it's time to start
> using a better RCS -- perhaps a distributed one, so you can commit to
> your own local repository with abandon while trying out changes.
>


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

Personally, I prefer clear code, minimally commented with good high
level descriptions of particularly complex section / algorithms. The
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.

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
 
Reply With Quote
 
Jorge Godoy
Guest
Posts: n/a
 
      04-19-2006
Edward Elliott wrote:

> Typing (* and *) on a few line will always be quicker, easier, and less
> confusing than any rcs diffs/restores. Once you delete the code you can
> no longer see it or add pieces back in without retrieving it from an
> external store.


Try using Subversion. You can work and make diffs disconnected from the
network. You can't, of course, commit / update but you can work with it
and have what you need to compare original code (i.e. the one from the last
commit) to new code and go back to original code if needed.

> I'm not saying nested comments solve every problem, just that
> there exists a certain (perhaps small) class of problems they solve
> particularly well.


I don't miss them.

> Personally, I rarely leave code commented out beyond a single coding
> session. But my particular coding habits aren't relevant here.


Well, I believe they are since it looks like a habit of yours to use
multiline comments. It is common for people coming from other programming
languages that support them.

--
Jorge Godoy <(E-Mail Removed)>

"Quidquid latine dictum sit, altum sonatur."
- Qualquer coisa dita em latim soa profundo.
- Anything said in Latin sounds smart.
 
Reply With Quote
 
Jorge Godoy
Guest
Posts: n/a
 
      04-19-2006
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 <(E-Mail Removed)>

"Quidquid latine dictum sit, altum sonatur."
- Qualquer coisa dita em latim soa profundo.
- Anything said in Latin sounds smart.
 
Reply With Quote
 
Jorge Godoy
Guest
Posts: n/a
 
      04-19-2006
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 <(E-Mail Removed)>

"Quidquid latine dictum sit, altum sonatur."
- Qualquer coisa dita em latim soa profundo.
- Anything said in Latin sounds smart.
 
Reply With Quote
 
Jorge Godoy
Guest
Posts: n/a
 
      04-19-2006
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 <(E-Mail Removed)>

"Quidquid latine dictum sit, altum sonatur."
- Qualquer coisa dita em latim soa profundo.
- Anything said in Latin sounds smart.
 
Reply With Quote
 
Peter Tillotson
Guest
Posts: n/a
 
      04-19-2006
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
 
Reply With Quote
 
Sion Arrowsmith
Guest
Posts: n/a
 
      04-19-2006
Edward Elliott <nobody@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 -- http://www.velocityreviews.com/forums/(E-Mail Removed) -- 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
 
Reply With Quote
 
 
 
Reply

Thread Tools

Posting Rules
You may not post new threads
You may not post replies
You may not post attachments
You may not edit your posts

BB code is On
Smilies are On
[IMG] code is On
HTML code is Off
Trackbacks are On
Pingbacks are On
Refbacks are Off


Similar Threads
Thread Thread Starter Forum Replies Last Post
Flex source for parsing files with multiline comments Uwe Ziegenhagen C++ 5 01-27-2010 01:09 AM
Case Sensitive, Multiline Comments Elliot Temple Python 32 06-02-2005 12:06 AM
Re: Case Sensitive, Multiline Comments Philippe C. Martin Python 0 05-26-2005 08:09 PM
how to define a variable to hold a multiline text input in perl from html multiline textbox dale zhang Perl Misc 8 11-30-2004 06:53 AM
Re: Stripping multiline C comments without using Lex Stephane CHAZELAS C Programming 3 02-05-2004 01:42 PM



Advertisments