[Webware-devel] Re: line wrapping compromise --> end this debate

[Tavis R. <ta...@ca...>]

On Sunday 09 December 2001 12:21, Chuck Esterbrook wrote:
> On Sunday 09 December 2001 01:11 pm, Tavis Rudd wrote:
> > Chuck,
> > I'd be happy to go with 90, or even 100, as a standard maximum
> > line width for Webware so we can end this debate and get back to
> > more productive things.  Either would be better than the
> > no-wrapping situation in the current codebase.
> > Tavis
>
> Well at least we kept it on -devel. In the pre-devel days we would
> have lost half our -discuss members.  :-)

Very true!

> In any case, I agree, but what I had in mind as the most productive
> next step was the doc string issues.

ok.

> But this has to be discussed as well because I have some questions:
>
> Off the top of my head I remember you mentioning:
>
> 	def foo(self):
>
> 		'''Returns a bar.'''
>
> 		return self

Geoff's comments and Ian's made me rethink the extra lines argument 
for short docstrings that aren't likely to need rewrapping:

def foo(self):
    """Returns a bar."""
    return self

For longer docstrings that have a lot in them, and must be updated to 
reflect code changes, I still think it's best to politely ask authors 
to include the extra lines.  Though, it's no big deal if they forget.

> My problem is that multi-paragraph strings look strange because the
> first is indented but the others aren't.
> 	def foo(self):
>
> 		'''Returns a bar.
>
> 		Override to customize the baz.'''
>
> 		return self

If we follow the convention of using the first line as a short 
synopsis, there's no problem here.  Besides the docstring tools are 
smart enough to figure out the indentation.  Pydoc works fine with 
either style.

BTW, we should ask that people follow convention of using the first 
line as synopsis, followed by a blank line if there is more to the 
docstring.

> I like this because the delimiters, paragraphs and code all line up
> and look neat (as in 'clean'). Obviously, both use the same # of
> lines.

I prefer including the blank lines, but I'm fine with either so long 
as we use """. 

> Questions:
>
> - You mentioned it is easier to word wrap the first style. Did you
> mean for the editor or when you wrap it by hand or what? What does
> that mean? (Sorry if I missed a clarification; I'm still catching
> up on messages.)

Emacs and a few other editors have an auto-wrapping feature that will 
inteligently rewrap a block of continuous text to match your 
preferred line wrapping.  When reformatting docstrings I edit the 
docstring, make sure there are blank lines between it and surrounding 
code and then hit alt-q to rewrap.  It deals with indentation 
gracefully.  Without the blank lines it will rewrap the code as well.

> - How well does pydoc work with these styles?
> 	- when spewing HTML
> 	- when browsing via a terminal
Both styles are fine.

> - How would the emacs developers react to a request to fully
> support syntax highlight of Python strings?
> 	- If the reaction is negative, we'll switch to """

I'm certain this has been proposed to the appropriate people before 
and the answer was that it's too much effort for something they're 
not concerned about. I can't remember where I read that, but I did 
some research last time we discussed this.

Cheers,
Tavis