do people really complain about significant whitespace?

[Stephen Kellett]

conclusion for me: they must not like self-documenting code...

Oh dear. So if the code is wrong it is self documenting?

Comments document what the code should do.
The code shows what the code actually does.

Also from a maintenance perspective reading comments is a lot faster
than reading the code. For a whitespace significant language this can be
very helpful when the formatting gets mangled for some reason.

There is no such thing as self-documenting code.

People that say they don't need to document their code because its self
documenting - no hire. I've been writing and selling software for 23
years now and I still keep hearing this bull about self documenting
code. Sigh.

Stephen

 

[Carl Banks]

Op 8-aug-2006, om 1:49 heeft Ben Finney het volgende geschreven:


Well, I most certainly disagree with that, of course, but you gotta
admit that there's something really charming about running an auto-
formatting script on a large piece of C code, turning it from an
unreadable mess into a beautifully indented and organized document.

The only time I get that satisfaction is when I run the formatter to
format some C code I'm asked to debug. Quite often the problem was
something that could have been easily spotted if the coder had used
good indentation in the first place. Though they probably wouldn't
have seen it anyways, considering the poor programming skills of most
engineers (the classical definition, not computer engineers).

The very fact the code formatters exist should tell you that grouping
by indentation is superior.


Carl Banks

 

[Gerhard Fiedler]

Oh dear. So if the code is wrong it is self documenting?

?? I'm not sure you are actually responding to what I wrote. I did not make
any affirmation about a relationship between correctness of code and its
self-documenting properties.

Comments document what the code should do.
The code shows what the code actually does.

That's only in theory like this, and then only in a bad theory. I'm sure in
23 years you have seen as many code comments as I have that documented what
a previous version of the code should have done...

Also from a maintenance perspective reading comments is a lot faster than
reading the code.

This depends a lot on the code, the comments and the reader. I prefer code
that reads as fast or faster than inline comments and coders that read code
as fast as comments

(I'm not talking about useful header comments. But even these can be made a
lot more succinct through appropriate coding.)

There is no such thing as self-documenting code.

But there is well-written code that is as much as reasonably possible
self-documenting, meaning easy to read and understand, with a clear
structure, helpful names, appropriate types (where applicable) etc etc.
Come on, if you have been in the business for 23 years you know what I
mean.

"Self-documenting" -- as used by me -- is always meant as a goal to be
approached gradually, not a state where you are or not; "as much as
possible" is always implied, the question is "more or less" not "whether or
not". I thought that was somehow obvious...

People that say they don't need to document their code because its self
documenting - no hire.

People that need a line of comment for every line of code -- no hire either
It's the right balance.

This is not really a subject for quick shots. And it is utterly off-topic
for my post.

Here's the long version of what I wrote:

Python's indent-based code structure is more self-documenting than for
example the brace-based structure of C in the following way. In C, it is
common practice to document the code structure by indenting. Indenting in C
is mere /documentation/ -- it is not required for the code to work as
written, but it is required (or commonly considered required) to document
its structure. When done properly, it's part of the "self-documentation" of
C code: you don't write a bunch of white space-stripped C and then document
the structure of that blob; you document the structure in the code by
correctly indenting it. However, it is easy to write C code where the
indenting and the structure are out of sync. (I know that there are tools
for that, but still...) In Python, the indenting is not a documentation
convention dissociated from the code structure, it /is/ the code structure.
In that sense, Python code is more "self-documenting" than C.

Gerhard

 

[Slawomir Nowaczyk]

On Mon, 07 Aug 2006 16:47:57 -0700

#> It is annoying that certain communication channels do not respect
#> white-space. I dislike using braces because I have to indicate my
#> intentions twice: once for the compiler and once for humans.

I must admit I do not get this "indicate intentions twice" argument,
even though I heard it a number of times now... It's not that braces
require more work or more typing or something, after all -- at least
not if one is using a decent editor.

Really, typing brace after function/if/etc should add newlines and
indent code as required -- automatically. Actually, for me, it is even
*less* typing in C and similar languages... I probably should teach my
Emacs to automatically add newline after colon in Python, just as it
does after a brace in C... As soon as I figure out how to deal with
dictionary literals. Hmmm.

--
Best wishes,
Slawomir Nowaczyk
( (e-mail address removed) )

"Be strict when sending and tolerant when receiving."
RFC 1958 - Architectural Principles of the Internet - section 3.9

 

[brianmce]

I must admit I do not get this "indicate intentions twice" argument,
even though I heard it a number of times now... It's not that braces
require more work or more typing or something, after all -- at least
not if one is using a decent editor.

Its not the typing, its the fact that when you say the same thing
twice, there is the potential for them to get out of sync. If the
method the compiler uses (braces) and the method the human uses
(indentation) to determine what the code does don't agree, then a
reader will be likely to misunderstand what it will actually do. One
of the driving principles behind Python is that, because code will be
read more often than written, readability is more important.

 

[Pierre Barbier de Reuille]

The only time I get that satisfaction is when I run the formatter to
format some C code I'm asked to debug. Quite often the problem was
something that could have been easily spotted if the coder had used
good indentation in the first place. Though they probably wouldn't
have seen it anyways, considering the poor programming skills of most
engineers (the classical definition, not computer engineers).

The very fact the code formatters exist should tell you that grouping
by indentation is superior.


Carl Banks

Problem being : grouping by indentation do *not* imply good indentation.
For example, I had to read a piece of (almost working) code which looked
like that :


if cond1 : stmt1
stmt2
stmt3
if cond2: stmt4
stmt5
elif cond3: stmt6
stmt7
else: stmt8
stmt9
stmt10
stmt11



So you can tell what you want, but this code is valid but impossible to
read and impossible to reindent correctly. So although I personnaly like
Python, I still don't think meaningful indentation is good.

Pierre

 

[Brett g Porter]

Its not the typing, its the fact that when you say the same thing
twice, there is the potential for them to get out of sync. If the
method the compiler uses (braces) and the method the human uses
(indentation) to determine what the code does don't agree, then a
reader will be likely to misunderstand what it will actually do. One
of the driving principles behind Python is that, because code will be
read more often than written, readability is more important.

Not to mention the errors that creep in when code is maintained, like
when C code starting out as

if (i < SOME_CONSTANT)
doSomething();

gets "maintained" to

if (i < SOME_CONSTANT)
doSomething();
doSomethingDangerous();

without the programmer adding the surrounding braces. The programmer's
intent is clear to me as a human, but the C compiler will disagree with
me, and in this case, the compiler will be right and I'm wrong.

You can (and we do, at my company) have coding standards that mandate
braces around single line if()s in C/C++, but that's really just
patching around the problem (and it counts on humans being consistent).

Pushing the scutwork down onto tools is not as good a solution as
eliminating the scutwork, especially when it shouldn't be necessary at
all...

 

[Stephen Kellett]

of the driving principles behind Python is that, because code will be
read more often than written, readability is more important.

In which case, for long functions with multiple levels of indentation
Python fails compared to languages that use braces or END or end; etc.

Stephen

 

[Stephen Kellett]

But there is well-written code that is as much as reasonably possible
self-documenting, meaning easy to read and understand, with a clear
structure, helpful names, appropriate types (where applicable) etc etc.

But that code is documenting what is does, not what it should do.
That is the fallacy of self-documenting. It is simply a bogus concept.
If you have the two together then if they match, most likely the program
is written correctly. If you have only the one you can't make the
comparison.

I don't think you should have a line of comment per line of code. I once
worked in a place where they insisted on 1 comment per 5 lines of code.
I was the #1 troublemaker there after they created that rule - I hated
it. It resulted in a lot of bogus comments that added nothing. Its what
you write and where. The problem with the self-documenting crowd is they
don't write anything so you can't follow their assumptions in the
comments.

It should be as sparse as you can get but enough so that each
block/chunk of code can be validated by comparing it with the comment
that describes what you are doing.

My first code was basic on a VIC-20, then assembly on a variety of
different 6502/6510 based machines (C64, C16, Atari...). I didn't bother
much with comments back then. I was writing games and once they are done
you never revisit them so you didn't care too much as long as you got
the job done. I thought it was reasonably obvious what each function did
etc. Ding! I went back some years later and looked at some of my own
code. I had little idea what a lot of it did. I started commenting my
code after that. So when it came time to port a game written for the
6510/6516/6502 to the 68000 (Atari ST) and IBM PC-AT (80286) the
comments came in handy. Sadly the game never saw the light of day for
legal reasons outside of my control. The game was a copy of the
wonderful arcade game "Dingo" written by Ashbury Computers and Graphics
(the team that later became Ultimate Play the Game who wrote for the
Sinclair ZX Spectrum very successfully in the 1980s). A bit of history
for you

Since someone mentioned assemblers and significant whitespace and I'm
rambling about assembly: I don't every remember whitespace being
significant for any of the assemblers I used (650x, 630x, 680x, 8085,
80286, 68000). There was a convention though - you indented to column 8
to write the mnemonics and used the first 6 or 7 chars for labels for
branch/jmp instructions.

Come on, if you have been in the business for 23 years you know what I
mean.

If you mean, should code be well written, thought about, well formatted,
sensible class/variable names, redesigned if you find a better way, sure
no problem with that.

Stephen

 

[skip]

Stephen> In which case, for long functions with multiple levels of
Stephen> indentation Python fails compared to languages that use braces
Stephen> or END or end; etc.

No. In that case Python makes it more readily apparent that your code is
too complex. With C, Java, C++, Perl or FORTRAN you just smush everything
over to the left and pretend it's not. ;-)

Skip

 

[Slawomir Nowaczyk]

On Wed, 09 Aug 2006 05:00:20 -0700

#> Slawomir Nowaczyk wrote:
#> >
#> > I must admit I do not get this "indicate intentions twice" argument,
#> > even though I heard it a number of times now... It's not that braces
#> > require more work or more typing or something, after all -- at least
#> > not if one is using a decent editor.
#>
#> Its not the typing, its the fact that when you say the same thing
#> twice, there is the potential for them to get out of sync.

Which, in my book, is the *right* thing... if I see a wrongly indented
piece of code, that's a good sign that it needs to be checked. It's
the same principle as in "if documentation and code disagree, both are
probably wrong."

YMMV, of course.

#> If the method the compiler uses (braces) and the method the human
#> uses (indentation) to determine what the code does don't agree,
#> then a reader will be likely to misunderstand what it will actually
#> do.

Well, not in my experience. In my experience, such discrepancies
usually only show up in places where something bad happens anyway.

#> One of the driving principles behind Python is that, because code
#> will be read more often than written, readability is more
#> important.

That's exactly my point

--
Best wishes,
Slawomir Nowaczyk
( (e-mail address removed) )

Today advance is so rapid that even the astronauts who set foot on the
moon in 1969 had never seen a digital watch

 

[Slawomir Nowaczyk]

#>
#> >> of the driving principles behind Python is that, because code will be
#> >> read more often than written, readability is more important.
#>
#> Stephen> In which case, for long functions with multiple levels of
#> Stephen> indentation Python fails compared to languages that use braces
#> Stephen> or END or end; etc.
#>
#> No. In that case Python makes it more readily apparent that your code is
#> too complex. With C, Java, C++, Perl or FORTRAN you just smush everything
#> over to the left and pretend it's not. ;-)

Well, one space is sufficient indentations for Python, right? So even
on 80 column screen, you can easily fit about 40 levels of nesting
before it becomes a real problem

In other words, it is possible to write bad code in any language. We
should focus on making it easier to write good code, not to make
writing bad code difficult.

--
Best wishes,
Slawomir Nowaczyk
( (e-mail address removed) )

The nice thing about standards is that there are so
many of them to choose from.

 

[Carl Banks]

In which case, for long functions with multiple levels of indentation
Python fails compared to languages that use braces or END or end; etc.

I don't really understand how a closing brace helps here. Care to
explain why it helps you?

(Deeply nested long functions are evil anyways. If you have such a
function then you have bigger problems than minor defects in
readability.


Carl Banks

 

[Rob Wolfe]

Really, typing brace after function/if/etc should add newlines and
indent code as required -- automatically. Actually, for me, it is even
*less* typing in C and similar languages... I probably should teach my
Emacs to automatically add newline after colon in Python, just as it
does after a brace in C... As soon as I figure out how to deal with
dictionary literals. Hmmm.

Are you sure? My Emacs already know how to do it with the help
of python-mode and magic function py-newline-and-indent.

emacs-version "21.3.1"
py-version "$Revision: 4.63 $"

Regards,
Rob

 

[skip]

Slawomir> #> No. In that case Python makes it more readily apparent
Slawomir> #> that your code is too complex. With C, Java, C++, Perl or
Slawomir> #> FORTRAN you just smush everything over to the left and
Slawomir> #> pretend it's not. ;-)

Slawomir> Well, one space is sufficient indentations for Python, right? So even
Slawomir> on 80 column screen, you can easily fit about 40 levels of nesting
Slawomir> before it becomes a real problem

Oh, sure. Hence the smiley in my post...

Smileys all around. I'm happy.

Skip

 

[Carl Banks]

Problem being : grouping by indentation do *not* imply good indentation.

By itself, it doesn't. But with grouping by indentation, bad
indentation no longer results from mere carelessness, which is no small
thing.

Although Python doesn't do this, it is possible to mandate a specific
indent (4 spaces, say), or at least a reasonable consistent indent,
which would indeed all but guarantee good indenting. (I say "all but"
only to account for deliberately misleading code, perhaps using clever
line breaks and comments.)

For example, I had to read a piece of (almost working) code which looked
like that :

if cond1 : stmt1
stmt2
stmt3
if cond2: stmt4
stmt5
elif cond3: stmt6
stmt7
else: stmt8
stmt9
stmt10
stmt11

So you can tell what you want, but this code is valid but impossible to
read and impossible to reindent correctly. So although I personnaly like
Python, I still don't think meaningful indentation is good.

Even if this were legal code (it isn't), it's still more transparent
than some of the C code I've seen.


Carl Banks

 

[Michiel Sikma]

Op 9-aug-2006, om 16:48 heeft Carl Banks het volgende geschreven:

Even if this were legal code (it isn't), it's still more transparent
than some of the C code I've seen.


Carl Banks

Still kind of too bad that means there won't ever be an International
Obfuscated Python Code Contest.

#define _ -F<00||--F-OO--;
int F=00,OO=00;main(){F_OO();printf("%1.3f\n",4.*-F/OO/OO);}F_OO()
{
_-_-_-_
_-_-_-_-_-_-_-_-_
_-_-_-_-_-_-_-_-_-_-_-_
_-_-_-_-_-_-_-_-_-_-_-_-_-_
_-_-_-_-_-_-_-_-_-_-_-_-_-_-_
_-_-_-_-_-_-_-_-_-_-_-_-_-_-_
_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_
_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_
_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_
_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_
_-_-_-_-_-_-_-_-_-_-_-_-_-_-_
_-_-_-_-_-_-_-_-_-_-_-_-_-_-_
_-_-_-_-_-_-_-_-_-_-_-_-_-_
_-_-_-_-_-_-_-_-_-_-_-_
_-_-_-_-_-_-_-_
_-_-_-_
}



Michiel

(source: http://www0.us.ioccc.org/years.html#1988)

 

[Ed Jensen]

Where are they-who-hate-us-for-our-whitespace? Are "they" really that
stupid/petty? Are "they" really out there at all? "They" almost sound
like a mythical caste of tasteless heathens that "we" have invented.
It just sounds like so much trivial nitpickery that it's hard to
believe it's as common as we've come to believe.

I like Python, but I do wish it used braces instead, if only because
every editor I'm likely to use supports brace matching, which makes it
easy to (for example) jump to the bottom or top of a block.

 

[Carl Banks]

Op 9-aug-2006, om 16:48 heeft Carl Banks het volgende geschreven:


Still kind of too bad that means there won't ever be an International
Obfuscated Python Code Contest.

#define _ -F<00||--F-OO--;
int F=00,OO=00;main(){F_OO();printf("%1.3f\n",4.*-F/OO/OO);}F_OO()
{
_-_-_-_
_-_-_-_-_-_-_-_-_
_-_-_-_-_-_-_-_-_-_-_-_
_-_-_-_-_-_-_-_-_-_-_-_-_-_
_-_-_-_-_-_-_-_-_-_-_-_-_-_-_
_-_-_-_-_-_-_-_-_-_-_-_-_-_-_
_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_
_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_
_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_
_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_
_-_-_-_-_-_-_-_-_-_-_-_-_-_-_
_-_-_-_-_-_-_-_-_-_-_-_-_-_-_
_-_-_-_-_-_-_-_-_-_-_-_-_-_
_-_-_-_-_-_-_-_-_-_-_-_
_-_-_-_-_-_-_-_
_-_-_-_
}



Michiel

(source: http://www0.us.ioccc.org/years.html#1988)

*yawn*


Carl Banks

 

[Gerhard Fiedler]

If you mean, should code be well written, thought about, well formatted,
sensible class/variable names, redesigned if you find a better way, sure
no problem with that.

I mean the code should be written so that as few as possible comments are
necessary to understand it. I don't mean that additional comments are a bad
thing.

Gerhard