do people really complain about significant whitespace?

[Gerhard Fiedler]

On 2006-08-08 19:02:27, Stephen Kellett wrote:

> In message <mailman.9107.1155060736.27775.python-list at python.org>, 
> Gerhard Fiedler <gelists at gmail.com> writes
>>conclusion for me: they must not like self-documenting code... :)
> 
> 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