4 ms·
Python doesn't have the glyph noise that brace-based languages do, and well-written Python is beautiful and easy to read. But lately I have been having an inte
by espeed 15y ago
Python doesn't have the glyph noise that brace-based languages do, and well-written Python is beautiful and easy to read.
But lately I have been having an internal debate on whether using autodoc and inline docstrings detracts from its beauty and makes it harder to read because it reduces the amount of code you can see on the screen (see Steve Yegge's rant on this http://steve-yegge.blogspot.com/2008/02/portrait-of-n00b.html http://steve-yegge.blogspot.com/2008/02/portrait-of-n00b.htm... from a few years back).
If you use Sphinx to document a method's description, params, param types, and return type, then it can easily turn a three-line method into a 12 line method, and then you can only see ~5 methods on the screen at a time.
So if the code is already readable, would it not be better to put the docstring comments in an external file to keep the code density?
Django does this, and I'm starting to think it's the right balance.
- mekoka 15y agoDocstrings should already be easy to detect by editors, so it would be trivial to add a show/hide functionality. Incidentally, one could also use Sphinx to create a plugin for that.
- odiroot 15y agoI just noticed Sublime Text 2 has an ability to fold multiline docstrings. If there only was a way to do this automatically.
- espeed 15y agoBut not all editors have this, nor is it widely used in editors like Emacs. And GitHub doesn't have it so it can make it harder to get a big-picture view and see the structure of a module when evaluating different libraries online.
- abecedarius 15y agoI generally write docstrings like "Return the n-fold frobulation around the center (x,y)." That's one line that way and about a half dozen in Javadoc style, without the latter adding much to pay its freight. What would be worth putting inline but with auto-folding, to me, would be examples.
- zem 15y agoone man's "glyph noise" is another man's "taking advantage of the symbol characters to add expressive power". of course, the end of that road is APL, but i'd argue that for instance /foo/ is more readable in code than regexp("foo") because it interrupts the flow of the line a lot less.