>> This is one of my gripes with the dogmatic application of the "break it >> into multiple statements" mantra of Python. > > I must admit I don't recognise that one, unless you're talking about "not > everything needs to be a one liner". > ... > Perhaps you could give some examples (actual or contrived) of stuff where > "breaking it into multiple statements" is a bad thing?
One example is performing a series of transformations on a collection of data, with the intent of finding an element of that collection that satisfies a particular criterion. If you separate out the individual transformations, you need to understand generators or you will waste space and perform many unnecessary calculations. If you only ever do a single transformation with a clear conceptual meaning, you could create a "master transformation function," but what if you have a large number of potential permutations of that function? What if you are composing three or four functions, each of which is conditional on the data? If you extract things from a statement and assign them somewhat arbitrary names, you've just traded horizontal bloat for vertical bloat (with a net increase in volume), while forcing a reader to scan back and forth to different statements to understand what is happening. To steal a line from Einstein, "Make things as simple as possible, but not simpler" >> I agree, docstrings/code comments are a pretty obvious indication that >> code (as it exists currently) fails as a human communication medium. > > > The fact that scientific journal articles start with a documentation string > called an abstract does not indicate that scientific English fails as a > human communication medium. Function docstrings say what the function does > and how to use it without reading the code. They can be pulled out and > displayed elsewhere. They also guide the reading of the code. Abstracts > serve the same functions. A paper, with topic introduction, methods exposition, data/results description and discussion is a poor analog to a function. I would compare the abstract of a scientific paper to the overview section of a program's documentation. The great majority of the docstrings I see are basically signature rehashes with added type information and assertions, followed by a single sentence English gloss-over. If the code were sufficiently intuitive and expressive, that would be redundant. Of course, there will always be morbidly obese functions and coders that like to wax philosophical or give history lessons in comments. Also, because of Sphinx, it is very common in the Python community weave documents and code together in a way that is convenient for authors but irritating for readers. I personally would prefer not to have to scroll past 100 lines of a tutorial with examples, tests and what not in order to go from one function to another. It would be really awesome if everyone used links to that material in docstrings, and the default sphinx theme created an inline collapsible iframe that included that material for the HTML version. Don't get me wrong, I adore Sphinx, the problem here is people who are lazy or don't know the right way to structure docs. -- http://mail.python.org/mailman/listinfo/python-list
