docstrings
Gary Wilson
am posting this to the list so that we can get an official stance on the
matter. I also suggest we add the decision to the "Coding style"
section of the "Contributing" documentation for consistency of future
patches, since AFAIK the subject is not mentioned in PEP 8 [3] or PEP
257 [4].
Adrian seems to favor "action words", whereas Guido mentions the
following in his Python Style Guide [3]:
The doc string is a phrase ending in a period. It prescribes the
function's effect as a command ("Do this", "Return that"), not as a
description: e.g. don't write "Returns the pathname ...".
Adrian, which BDFL do we follow :)
[1] http://code.djangoproject.com/changeset/5756
[2] http://code.djangoproject.com/changeset/5758
[3] http://www.python.org/dev/peps/pep-0008/
[4] http://www.python.org/dev/peps/pep-0257/
[5] http://www.python.org/doc/essays/styleguide.html
Gary
Duc Nguyen
On a somewhat related note, is it just me or does no django core developer
follow the "no line longer than 79 characters" note. I like using emacs
and I have my frame width set at 80 and it bothers me to no end to have
to scroll to see every line. Turning on line wrapping makes things even
harder to read!
Nicola Larosa
> On a somewhat related note, is it just me or does no django core developer
> follow the "no line longer than 79 characters" note. I like using emacs
> and I have my frame width set at 80 and it bothers me to no end to have
> to scroll to see every line. Turning on line wrapping makes things even
> harder to read!
+1
This somewhat bothers me too.
--
Nicola Larosa - http://www.tekNico.net/
Our criticisms of WS-* are specific and have to do with issues of process
and stability and technical quality and a demonstrated lack of interoper-
ability. It is badly-engineered technology, using it will increase the
likelihood that your project fails, and it is not suitable for use
by conscientious IT professionals. -- Tim Bray, February 2007
Tom Tobin
I'm +1 to Adrian's style (descriptive, rather than prescriptive); it
feels more natural to have the docstring be a description of the given
code rather than a direct "English translation". The code itself is
right there, and it's something of a given that a Python programmer
can do an imperative translation for herself if she wants.
Tom Tobin
>
> On a somewhat related note, is it just me or does no django core developer
> follow the "no line longer than 79 characters" note. I like using emacs
> and I have my frame width set at 80 and it bothers me to no end to have
> to scroll to see every line. Turning on line wrapping makes things even
> harder to read!
I'm starting to seriously wonder if the 80-character line width has
outlived its usefulness. There are various naturally occurring bits
of code that just don't fit onto a single 80-character line, and the
options for chopping it up are all sub-optimal; increasing the minimum
width would decrease the number of occasions on which one might need
to deal with this frustration. Docstrings and comments also find
themselves cramped for space after a few indentation levels.
I find it hard to imagine a programmer these days who is so starved
for screen real estate that they couldn't handle a width of, say, 120
characters; I code in Aquamacs Emacs on a 13" Macbook and a 15"
Macbook Pro, and I come nowhere *near* using all of my screen real
estate in the horizontal dimension — and no, I'm not using tiny fonts.
The same thing applies to any terminal inside of a GUI.
Tom Tobin
> ... increasing the minimum width would ...
Err, *maximum* width, rather. ^_^
Amit Upadhyay
I'm starting to seriously wonder if the 80-character line width has
outlived its usefulness. There are various naturally occurring bits
of code that just don't fit onto a single 80-character line, and the
options for chopping it up are all sub-optimal; increasing the minimum
width would decrease the number of occasions on which one might need
to deal with this frustration. Docstrings and comments also find
themselves cramped for space after a few indentation levels.
I like to differ on this. Take your email for example, why is it wrapped at 80 chars? Because its easier to read.
In source code this fosters better coding practice, if indentation level is too deep, you are doing something wrong.
--
Amit Upadhyay
http://www.amitu.com/blog/
+91-9820-295-512
Andrey Khavryuchenko
"Tom Tobin" <kor...@korpios.com> wrote:
TT> I find it hard to imagine a programmer these days who is so starved
TT> for screen real estate that they couldn't handle a width of, say, 120
TT> characters; I code in Aquamacs Emacs on a 13" Macbook and a 15"
TT> Macbook Pro, and I come nowhere *near* using all of my screen real
TT> estate in the horizontal dimension -- and no, I'm not using tiny fonts.
TT> The same thing applies to any terminal inside of a GUI.
Well, I'm on my 14" Thinkpad can fit two 80-column emacs windows
side-by-side... This increases productivity susbtatially and makes me
dislike lines more than 79 char :)
--
Andrey V Khavryuchenko
Django NewGate - http://www.kds.com.ua/djiggit/
Development - http://www.kds.com.ua
Call akhavr1975 on www.gizmoproject.com
Tom Tobin
> On 7/26/07, Tom Tobin <kor...@korpios.com> wrote:
> > I'm starting to seriously wonder if the 80-character line width has
> > outlived its usefulness. There are various naturally occurring bits
> > of code that just don't fit onto a single 80-character line, and the
> > options for chopping it up are all sub-optimal; increasing the minimum
> > width would decrease the number of occasions on which one might need
> > to deal with this frustration. Docstrings and comments also find
> > themselves cramped for space after a few indentation levels.
>
> I like to differ on this. Take your email for example, why is it wrapped at
> 80 chars? Because its easier to read.
It's wrapped because that's what Gmail wrapped it at. And I agree
that somewhat-narrow line widths are good for *prose*; code isn't read
the same way.
> In source code this fosters better coding practice, if indentation level is
> too deep, you are doing something wrong.
You can run into these problems at two, one, or even *no* indentation
levels deep.
Carlo C8E Miron
> Well, I'm on my 14" Thinkpad can fit two 80-column emacs windows
> side-by-side... This increases productivity susbtatially and makes me
> dislike lines more than 79 char :)
The same here after:
s/14"/15"/
s/emacs/vim/
;-)
(c)
--
Carlo C8E Miron
Eighty Columns Solution Architect™
Tom Tobin
> TT> I find it hard to imagine a programmer these days who is so starved
> TT> for screen real estate that they couldn't handle a width of, say, 120
> TT> characters; I code in Aquamacs Emacs on a 13" Macbook and a 15"
> TT> Macbook Pro, and I come nowhere *near* using all of my screen real
> TT> estate in the horizontal dimension -- and no, I'm not using tiny fonts.
> TT> The same thing applies to any terminal inside of a GUI.
>
> Well, I'm on my 14" Thinkpad can fit two 80-column emacs windows
> side-by-side... This increases productivity susbtatially and makes me
> dislike lines more than 79 char :)
Meh. I'd say that expecting to run two editors side-by-side on a
small notebook screen is asking a bit much; you could always get by
with soft wrapping. ;-)
Malcolm Tredinnick
> On 7/25/07, Duc Nguyen <d...@nuggien.com> wrote:
> >
> > On a somewhat related note, is it just me or does no django core developer
> > follow the "no line longer than 79 characters" note. I like using emacs
> > and I have my frame width set at 80 and it bothers me to no end to have
> > to scroll to see every line. Turning on line wrapping makes things even
> > harder to read!
>
> I'm starting to seriously wonder if the 80-character line width has
> outlived its usefulness. There are various naturally occurring bits
> of code that just don't fit onto a single 80-character line, and the
> options for chopping it up are all sub-optimal; increasing the minimum
> width would decrease the number of occasions on which one might need
> to deal with this frustration. Docstrings and comments also find
> themselves cramped for space after a few indentation levels.
>
> I find it hard to imagine a programmer these days who is so starved
> for screen real estate that they couldn't handle a width of, say, 120
> characters;
Try to imagine a bit harder then. I'm in that position, for example,
even on my desktop. It's much more effective to be able to view more
than one window at a time (e.g. the bug report or details in the web
window and the terminal next to it), so 80 columns is the right sort of
width for that. It's the same reason people have web browser windows at
less than 1024 columns sometimes, despite big screens existing. Having
to flick back and forth between partially obscured windows is slower.
This workflow doesn't work on my laptop, since the screen isn't large
enough, but that's a problem with smaller screens.
That being said, whilst I strongly prefer 80 character limits, I can
handle lines being longer in circumstances, too, for all the normal
reasons (some lines just don't break).
People seem to forget that one of the key rules in any coding guidelines
is "do what the existing code does" (see, e.g., the second section of
PEP 8). Thus, our current standards are in not in conflict with PEP 8 or
PEP 257.
Regards,
Malcolm
Nicola Larosa
> I'm starting to seriously wonder if the 80-character line width has
> outlived its usefulness.
It has not, and it never will, until human beings stay the same: it's not a
technological limitation.
> There are various naturally occurring bits
> of code that just don't fit onto a single 80-character line, and the
> options for chopping it up are all sub-optimal;
Those options do not decrease readability, once you get accustomed to them:
it's just an initial phase. Remember your first hours staring at Python
code? ;-)
Moreover, if a line is so long, maybe it's doing too many things, and
should be decomposed logically, before recurring to splitting it.
Anyway, parentheses are your friend (even with long strings), but drop the
backslash.
> Docstrings and comments also find
> themselves cramped for space after a few indentation levels.
Docstrings are never indented that much; comments should be concise anyway.
> I find it hard to imagine a programmer these days who is so starved
> for screen real estate that they couldn't handle a width of, say, 120
> characters; I code in Aquamacs Emacs on a 13" Macbook and a 15"
> Macbook Pro, and I come nowhere *near* using all of my screen real
> estate in the horizontal dimension -- and no, I'm not using tiny fonts.
> The same thing applies to any terminal inside of a GUI.
Displaying the source code on a large screen is only one of its many uses:
the keyword here is *interoperability*.
You want to print the code on paper.
You want other non-overlapping windows open at the same time.
You want to make manual three-way merges, with three files shown side by side.
You want to include code snippets in emails, web pages and other documents.
You want to display the code on smaller screens of small devices.
You want readability, which is impaired by larger column widths.
Old good RFC 678 has not been obsoleted in 33 years, and won't be in the
future, near and not so near. It doesn't matter how many DPI (Dots Per
Inch) displays gain, your eyes still need no more than 10 characters per
inch. Your hands still need a Letter, or A4, sheet of paper.
It's not casual that most programming guidelines still follow this convention.
A couple of pages on this matter:
Column Width: What is the One True Way?
http://bluebones.net/2006/12/column-width-what-is-the-one-true-way/
Wrapping code at 80 columns?
http://discuss.fogcreek.com/joelonsoftware4/default.asp?cmd=show&ixPost=128655
--
Nicola Larosa - http://www.tekNico.net/
Right now we have two wildly advanced platforms: the desktop operating
system and the Internet. That leaves users with a frustrating choice.
[...] We don't believe people should have to make that choice.
-- Blake Ross about Parakey, November 2006
Adrian Holovaty
> am posting this to the list so that we can get an official stance on the
> matter. I also suggest we add the decision to the "Coding style"
> section of the "Contributing" documentation for consistency of future
> patches, since AFAIK the subject is not mentioned in PEP 8 [3] or PEP
> 257 [4].
>
> Adrian seems to favor "action words", whereas Guido mentions the
> following in his Python Style Guide [3]:
Thanks for bringing this up, Gary. The official stance is "action
words," and I've updated the contributing.txt documentation to point
this out.
Adrian
--
Adrian Holovaty
holovaty.com | djangoproject.com
Nicola Larosa
> That being said, whilst I strongly prefer 80 character limits, I can
> handle lines being longer in circumstances, too, for all the normal
> reasons (some lines just don't break).
All lines break, and most break gracefully, unless there's an assignment
left side longer than 70 chars: but then there are bigger style problems. :-)
> People seem to forget that one of the key rules in any coding guidelines
> is "do what the existing code does" (see, e.g., the second section of
> PEP 8). Thus, our current standards are in not in conflict with PEP 8 or
> PEP 257.
Are Django committers willing to accept patches that reformat lines within
80 characters?
--
Nicola Larosa - http://www.tekNico.net/
If web applications liberated us from the domination of a single company
on the desktop, why would we be eager to be dominated by a different
company on the web? [...] I’m not eager to go from being beholden
to Microsoft to being beholden to Adobe. -- Ted Leung, March 2007
Duc Nguyen
has some great
arguments in support of the 80 char limit :)
Nicola Larosa wrote
Brian Harring
> > People seem to forget that one of the key rules in any coding guidelines
> > is "do what the existing code does" (see, e.g., the second section of
> > PEP 8). Thus, our current standards are in not in conflict with PEP 8 or
> > PEP 257.
>
> Are Django committers willing to accept patches that reformat lines within
> 80 characters?
Would personally be somewhat opposed to such patches; while I agree
with 80 lines, reformatting code has a nasty nack of making it a
serious pita to deal with patches from before the reformat point.
Why not just correct as we go? In other words, if I'm already
modifying this spot, do the reformat for the sections being modified?
Yes, slightly extra noise on the patch, but at least the patch has a
chance in hell of applying- after unicode, already have gone through a
pretty heavy set of updates, not particularly looking forward to
another couple of hours correcting for bitrot :)
~harring
oggie rob
> 80 characters?
>
> --
> Nicola Larosa -http://www.tekNico.net/
I was curious - being a 80+ line writer myself - how many lines in
trunk were currently longer than 80 chars, so I wrote a short script.
Here's what I got (just looking at .py files):
Long lines: 2517
All lines : 43930
Proportion: 5.73%
That seems like a pretty low proportion of longer lines, but probably
more than would be worth retro-fitting (unless you were making other
changes).
HTML is a bit different (as you might expect):
Long lines: 220
All lines : 1539
Proportion: 14.29%
(Personally I don't think HTML should be regulated as much - there are
several reasons for why you would want longer lines. I just add this
for perspective).
-rob
Tom Tobin
> > I find it hard to imagine a programmer these days who is so starved
> > for screen real estate that they couldn't handle a width of, say, 120
> > characters;
>
> Try to imagine a bit harder then. I'm in that position, for example,
> even on my desktop. It's much more effective to be able to view more
> than one window at a time (e.g. the bug report or details in the web
> window and the terminal next to it), so 80 columns is the right sort of
> width for that. It's the same reason people have web browser windows at
> less than 1024 columns sometimes, despite big screens existing. Having
> to flick back and forth between partially obscured windows is slower.
> This workflow doesn't work on my laptop, since the screen isn't large
> enough, but that's a problem with smaller screens.
I'll accept that I'm an outlier, then; I'm also the only one at work
who can't stand working with multiple and/or large monitors, and the
only one who prefers quickly flipping between maximized windows for
most apps rather than having multiple apps side-by-side. (Yeah, I
guess that cements me as a weirdo.) ;-)
Nicola Larosa
> I'll accept that I'm an outlier, then; I'm also the only one at work
> who can't stand working with multiple and/or large monitors, and the
> only one who prefers quickly flipping between maximized windows for
> most apps rather than having multiple apps side-by-side. (Yeah, I
> guess that cements me as a weirdo.) ;-)
Not so fast: I work exactly that way too, on a laptop's 15" display, wide
format. But then, I've been labeled a weirdo myself more than once, so I
cannot really disprove your notion. ;-)
Tom Tobin
>
> Tom Tobin wrote:
> > I'm starting to seriously wonder if the 80-character line width has
> > outlived its usefulness.
>
> It has not, and it never will, until human beings stay the same: it's not a
> technological limitation.
I'm guessing that should have been "until human beings change"?
It certainly seems to have *started* as a technological limitation,
even if programmers profess other reasons for retaining it these days.
> > There are various naturally occurring bits
> > of code that just don't fit onto a single 80-character line, and the
> > options for chopping it up are all sub-optimal;
>
> Those options do not decrease readability, once you get accustomed to them:
> it's just an initial phase. Remember your first hours staring at Python
> code? ;-)
I've been coding Python for many years; I doubt my feelings are part
of an "initial phase". :P
> Moreover, if a line is so long, maybe it's doing too many things, and
> should be decomposed logically, before recurring to splitting it.
In some cases, yes, this would be the correct thing to do. In other
cases, the line really does make the most sense as one logical unit,
and splitting to get under 80 lines in some of these cases *decreases*
readability.
> > Docstrings and comments also find
> > themselves cramped for space after a few indentation levels.
>
> Docstrings are never indented that much; comments should be concise anyway.
Docstrings for methods still get that much less room (8 characters)
than module-wide docstrings; in certain odd cases (e.g., functions
within functions), this can be reduced further.
Multi-line comments *do* sometimes make sense.
> Displaying the source code on a large screen is only one of its many uses:
> the keyword here is *interoperability*.
>
> You want to print the code on paper.
Adjust your font a bit. :P Regardless, that shouldn't be something
the coder should worry about.
> You want other non-overlapping windows open at the same time.
Get a larger monitor. :P
> You want to make manual three-way merges, with three files shown side by side.
Ditto.
> You want to include code snippets in emails, web pages and other documents.
>
> You want to display the code on smaller screens of small devices.
Again, not the coder's problem IMHO.
> You want readability, which is impaired by larger column widths.
I'm making this (apparently quixotic, which I accept) argument in
*favor* of readability. I'm certainly not recommending that anyone
make lines any longer than they have to be!
I'll also take a moment here to state that the number I tossed out
initially, 120, was probably a bit much; 100 is more realistic. I do
apologize for not thinking before I selected my example.
Tom Tobin
> outlived its usefulness. There are various naturally occurring bits
> of code that just don't fit onto a single 80-character line, and the
> options for chopping it up are all sub-optimal; increasing the minimum
> width would decrease the number of occasions on which one might need
> to deal with this frustration. Docstrings and comments also find
> themselves cramped for space after a few indentation levels.
Being a dope and replying to myself here ... while it certainly
doesn't address all of the objections raised, I realized that my chief
problem is with the *absolute* 80-character margin rather than
80-characters-per-line (i.e., what you'd get for line widths with
[len(x.strip()) for x in somefile.readlines()] ). It seems fairly
reasonable to expect most lines to constrain themselves to 80
characters *if* you don't account for indentation.
Again, I know many of the objections would stand regardless (e.g.,
side-by-side windows), but I think this does clarify my thinking a bit
(to myself, and hopefully to others, too).