On 2006-08-08 19:02:27, Stephen Kellett wrote: > In message <[EMAIL PROTECTED]>, > Gerhard Fiedler <[EMAIL PROTECTED]> 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 -- http://mail.python.org/mailman/listinfo/python-list
