[Python-Dev] Reminder: an oft-forgotten rule about docstring formatting (PEP 257) (original) (raw)

Alexander Belopolsky alexander.belopolsky at gmail.com
Thu Jun 27 23:51:44 CEST 2013

On Thu, Jun 27, 2013 at 10:20 AM, Guido van Rossum <guido at python.org> wrote:

On Thu, Jun 27, 2013 at 1:21 AM, Antoine Pitrou <solipsis at pitrou.net> wrote: > I don't always find it easy to summarize a function in one line.

Neither do I. But I always manage to do it anyway.

+1

If you cannot summarize what your function does in one line, chances are it is time to split your function, not the summary line. Ideally, the name of the function should already give a good idea of what it does. A summary line can just rephrase the same in a complete sentence.

I took a quick look at the stdlib and in many cases a summary line is already there. It is just the issue of formatting.

250<http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/suite.py#l250> class _ErrorHolder(object): 251<http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/suite.py#l251> """ 252<http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/suite.py#l252> Placeholder for a TestCase inside a result. As far as a TestResult 253<http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/suite.py#l253> is concerned, this looks exactly like a unit test. Used to insert 254<http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/suite.py#l254> arbitrary errors into a test suite run. 255<http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/suite.py#l255> """ *http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/suite.py#l250*

81 <http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/main.py#l81> class TestProgram(object): 82 <http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/main.py#l82> """A command-line program that runs a set of tests; this is primarily 83 <http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/main.py#l83> for making test modules conveniently executable. 84 <http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/main.py#l84> """ *http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/main.py#l81*

109<http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/result.py#l109> @failfast 110<http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/result.py#l110> def addError(self, test, err): 111<http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/result.py#l111> """Called when an error has occurred. 'err' is a tuple of values as 112<http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/result.py#l112> returned by sys.exc_info(). 113<http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/result.py#l113> """ 114<http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/result.py#l114> self.errors.append((test, self._exc_info_to_string(err, test))) 115<http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/result.py#l115> self._mirrorOutput = True 116<http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/result.py#l116> 117<http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/result.py#l117> @failfast 118<http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/result.py#l118> def addFailure(self, test, err): 119<http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/result.py#l119> """Called when an error has occurred. 'err' is a tuple of values as 120<http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/result.py#l120> returned by sys.exc_info().""" 121<http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/result.py#l121> self.failures.append((test, self._exc_info_to_string(err, test))) 122<http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/result.py#l122> self._mirrorOutput = True 123<http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/result.py#l123> 124<http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/result.py#l124> @failfast 125<http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/result.py#l125> def addSubTest(self, test, subtest, err): 126<http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/result.py#l126> """Called at the end of a subtest. 127<http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/result.py#l127> 'err' is None if the subtest ended successfully, otherwise it's a 128<http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/result.py#l128> tuple of values as returned by sys.exc_info(). 129<http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/result.py#l129> """ *http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/result.py#l109* * * 589 <http://hg.python.org/cpython/file/44f455e6163d/Lib/pdb.py#l589> def do_break(self, arg, temporary = 0): 590 <http://hg.python.org/cpython/file/44f455e6163d/Lib/pdb.py#l590> """b(reak) [ ([filename:]lineno | function) [, condition] ] 591 <http://hg.python.org/cpython/file/44f455e6163d/Lib/pdb.py#l591> Without argument, list all breaks. *http://hg.python.org/cpython/file/44f455e6163d/Lib/pdb.py#l589* -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://mail.python.org/pipermail/python-dev/attachments/20130627/e14af801/attachment-0001.html>

More information about the Python-Dev mailing list