<div dir="ltr"><br><div class="gmail_extra"><br><br><div class="gmail_quote">On Thu, Jun 27, 2013 at 10:20 AM, Guido van Rossum <span dir="ltr"><<a href="mailto:guido@python.org" target="_blank">guido@python.org</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div class="im">On Thu, Jun 27, 2013 at 1:21 AM, Antoine Pitrou <<a href="mailto:solipsis@pitrou.net">solipsis@pitrou.net</a>> wrote:<br>
> I don't always find it easy to summarize a function in one line.<br>
<br>
</div>Neither do I. But I always manage to do it anyway.</blockquote><div><br></div><div>+1</div><div><br></div><div style>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.</div>
<div style><br></div><div style>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.</div><div style><br></div><div style><div class="" style="background-color:rgb(240,240,240);font-family:monospace;white-space:pre;padding:1px 4px;font-size:12px;color:rgb(0,0,0)">
</div><div class="" style="font-family:monospace;white-space:pre;padding:1px 4px;font-size:12px;color:rgb(0,0,0)"><a href="http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/suite.py#l250" id="l250" style="text-decoration:none;color:rgb(153,153,153);font-size:smaller"> 250</a> <span class="" style="color:rgb(0,128,0);font-weight:bold">class</span> <span class="" style="color:rgb(0,0,255);font-weight:bold">_ErrorHolder</span><span class="">(</span><span class="" style="color:rgb(0,128,0)">object</span><span class="">):</span></div>
<div class="" style="background-color:rgb(240,240,240);font-family:monospace;white-space:pre;padding:1px 4px;font-size:12px;color:rgb(0,0,0)"><a href="http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/suite.py#l251" id="l251" style="text-decoration:none;color:rgb(153,153,153);font-size:smaller"> 251</a> <span class="" style="color:rgb(186,33,33);font-style:italic">"""</span></div>
<div class="" style="font-family:monospace;white-space:pre;padding:1px 4px;font-size:12px;color:rgb(0,0,0)"><a href="http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/suite.py#l252" id="l252" style="text-decoration:none;color:rgb(153,153,153);font-size:smaller"> 252</a> <span class="" style="color:rgb(186,33,33);font-style:italic"> Placeholder for a TestCase inside a result. As far as a TestResult</span></div>
<div class="" style="background-color:rgb(240,240,240);font-family:monospace;white-space:pre;padding:1px 4px;font-size:12px;color:rgb(0,0,0)"><a href="http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/suite.py#l253" id="l253" style="text-decoration:none;color:rgb(153,153,153);font-size:smaller"> 253</a> <span class="" style="color:rgb(186,33,33);font-style:italic"> is concerned, this looks exactly like a unit test. Used to insert</span></div>
<div class="" style="font-family:monospace;white-space:pre;padding:1px 4px;font-size:12px;color:rgb(0,0,0)"><a href="http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/suite.py#l254" id="l254" style="text-decoration:none;color:rgb(153,153,153);font-size:smaller"> 254</a> <span class="" style="color:rgb(186,33,33);font-style:italic"> arbitrary errors into a test suite run.</span></div>
<div class="" style="background-color:rgb(240,240,240);font-family:monospace;white-space:pre;padding:1px 4px;font-size:12px;color:rgb(0,0,0)"><a href="http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/suite.py#l255" id="l255" style="text-decoration:none;color:rgb(153,153,153);font-size:smaller"> 255</a> <span class="" style="color:rgb(186,33,33);font-style:italic"> """</span></div>
<div class="" style="background-color:rgb(240,240,240);padding:1px 4px"><span class=""><font color="#ba2121" face="monospace"><span style="font-size:12px;white-space:pre"><i><a href="http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/suite.py#l250">http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/suite.py#l250</a></i></span></font><br>
</span></div><div class="" style="background-color:rgb(240,240,240);padding:1px 4px"><span class=""><div class="" style="font-family:monospace;white-space:pre;padding:1px 4px;font-size:12px;color:rgb(0,0,0)"><a href="http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/main.py#l81" id="l81" style="text-decoration:none;color:rgb(153,153,153);font-size:smaller"><br class="">
81</a> <span class="" style="color:rgb(0,128,0);font-weight:bold">class</span> <span class="" style="color:rgb(0,0,255);font-weight:bold">TestProgram</span><span class="">(</span><span class="" style="color:rgb(0,128,0)">object</span><span class="">):</span></div>
<div class="" style="background-color:white;font-family:monospace;white-space:pre;padding:1px 4px;font-size:12px;color:rgb(0,0,0)"><a href="http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/main.py#l82" id="l82" style="text-decoration:none;color:rgb(153,153,153);font-size:smaller"> 82</a> <span class="" style="color:rgb(186,33,33);font-style:italic">"""A command-line program that runs a set of tests; this is primarily</span></div>
<div class="" style="font-family:monospace;white-space:pre;padding:1px 4px;font-size:12px;color:rgb(0,0,0)"><a href="http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/main.py#l83" id="l83" style="text-decoration:none;color:rgb(153,153,153);font-size:smaller"> 83</a> <span class="" style="color:rgb(186,33,33);font-style:italic"> for making test modules conveniently executable.</span></div>
<div class="" style="background-color:white;font-family:monospace;white-space:pre;padding:1px 4px;font-size:12px;color:rgb(0,0,0)"><a href="http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/main.py#l84" id="l84" style="text-decoration:none;color:rgb(153,153,153);font-size:smaller"> 84</a> <span class="" style="color:rgb(186,33,33);font-style:italic"> """</span></div>
<div class="" style="background-color:white;padding:1px 4px"><span class=""><font color="#ba2121" face="monospace"><span style="font-size:12px;white-space:pre"><i><a href="http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/main.py#l81">http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/main.py#l81</a></i></span></font><br>
</span></div><div class="" style="background-color:white;padding:1px 4px"><span class=""><div class="" style="background-color:rgb(240,240,240);font-family:monospace;white-space:pre;padding:1px 4px;font-size:12px;color:rgb(0,0,0)">
<a href="http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/result.py#l109" id="l109" style="text-decoration:none;color:rgb(153,153,153);font-size:smaller"><br class=""> 109</a> <span class="" style="color:rgb(170,34,255)">@failfast</span></div>
<div class="" style="font-family:monospace;white-space:pre;padding:1px 4px;font-size:12px;color:rgb(0,0,0)"><a href="http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/result.py#l110" id="l110" style="text-decoration:none;color:rgb(153,153,153);font-size:smaller"> 110</a> <span class="" style="color:rgb(0,128,0);font-weight:bold">def</span> <span class="" style="color:rgb(0,0,255)">addError</span><span class="">(</span><span class="" style="color:rgb(0,128,0)">self</span><span class="">,</span> <span class="">test</span><span class="">,</span> <span class="">err</span><span class="">):</span></div>
<div class="" style="background-color:rgb(240,240,240);font-family:monospace;white-space:pre;padding:1px 4px;font-size:12px;color:rgb(0,0,0)"><a href="http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/result.py#l111" id="l111" style="text-decoration:none;color:rgb(153,153,153);font-size:smaller"> 111</a> <span class="" style="color:rgb(186,33,33);font-style:italic">"""Called when an error has occurred. 'err' is a tuple of values as</span></div>
<div class="" style="font-family:monospace;white-space:pre;padding:1px 4px;font-size:12px;color:rgb(0,0,0)"><a href="http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/result.py#l112" id="l112" style="text-decoration:none;color:rgb(153,153,153);font-size:smaller"> 112</a> <span class="" style="color:rgb(186,33,33);font-style:italic"> returned by sys.exc_info().</span></div>
<div class="" style="background-color:rgb(240,240,240);font-family:monospace;white-space:pre;padding:1px 4px;font-size:12px;color:rgb(0,0,0)"><a href="http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/result.py#l113" id="l113" style="text-decoration:none;color:rgb(153,153,153);font-size:smaller"> 113</a> <span class="" style="color:rgb(186,33,33);font-style:italic"> """</span></div>
<div class="" style="font-family:monospace;white-space:pre;padding:1px 4px;font-size:12px;color:rgb(0,0,0)"><a href="http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/result.py#l114" id="l114" style="text-decoration:none;color:rgb(153,153,153);font-size:smaller"> 114</a> <span class="" style="color:rgb(0,128,0)">self</span><span class="" style="color:rgb(102,102,102)">.</span><span class="">errors</span><span class="" style="color:rgb(102,102,102)">.</span><span class="">append</span><span class="">((</span><span class="">test</span><span class="">,</span> <span class="" style="color:rgb(0,128,0)">self</span><span class="" style="color:rgb(102,102,102)">.</span><span class="">_exc_info_to_string</span><span class="">(</span><span class="">err</span><span class="">,</span> <span class="">test</span><span class="">)))</span></div>
<div class="" style="background-color:rgb(240,240,240);font-family:monospace;white-space:pre;padding:1px 4px;font-size:12px;color:rgb(0,0,0)"><a href="http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/result.py#l115" id="l115" style="text-decoration:none;color:rgb(153,153,153);font-size:smaller"> 115</a> <span class="" style="color:rgb(0,128,0)">self</span><span class="" style="color:rgb(102,102,102)">.</span><span class="">_mirrorOutput</span> <span class="" style="color:rgb(102,102,102)">=</span> <span class="" style="color:rgb(0,128,0)">True</span></div>
<div class="" style="font-family:monospace;white-space:pre;padding:1px 4px;font-size:12px;color:rgb(0,0,0)"><a href="http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/result.py#l116" id="l116" style="text-decoration:none;color:rgb(153,153,153);font-size:smaller"> 116</a> </div>
<div class="" style="background-color:rgb(240,240,240);font-family:monospace;white-space:pre;padding:1px 4px;font-size:12px;color:rgb(0,0,0)"><a href="http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/result.py#l117" id="l117" style="text-decoration:none;color:rgb(153,153,153);font-size:smaller"> 117</a> <span class="" style="color:rgb(170,34,255)">@failfast</span></div>
<div class="" style="font-family:monospace;white-space:pre;padding:1px 4px;font-size:12px;color:rgb(0,0,0)"><a href="http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/result.py#l118" id="l118" style="text-decoration:none;color:rgb(153,153,153);font-size:smaller"> 118</a> <span class="" style="color:rgb(0,128,0);font-weight:bold">def</span> <span class="" style="color:rgb(0,0,255)">addFailure</span><span class="">(</span><span class="" style="color:rgb(0,128,0)">self</span><span class="">,</span> <span class="">test</span><span class="">,</span> <span class="">err</span><span class="">):</span></div>
<div class="" style="background-color:rgb(240,240,240);font-family:monospace;white-space:pre;padding:1px 4px;font-size:12px;color:rgb(0,0,0)"><a href="http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/result.py#l119" id="l119" style="text-decoration:none;color:rgb(153,153,153);font-size:smaller"> 119</a> <span class="" style="color:rgb(186,33,33);font-style:italic">"""Called when an error has occurred. 'err' is a tuple of values as</span></div>
<div class="" style="font-family:monospace;white-space:pre;padding:1px 4px;font-size:12px;color:rgb(0,0,0)"><a href="http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/result.py#l120" id="l120" style="text-decoration:none;color:rgb(153,153,153);font-size:smaller"> 120</a> <span class="" style="color:rgb(186,33,33);font-style:italic"> returned by sys.exc_info()."""</span></div>
<div class="" style="background-color:rgb(240,240,240);font-family:monospace;white-space:pre;padding:1px 4px;font-size:12px;color:rgb(0,0,0)"><a href="http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/result.py#l121" id="l121" style="text-decoration:none;color:rgb(153,153,153);font-size:smaller"> 121</a> <span class="" style="color:rgb(0,128,0)">self</span><span class="" style="color:rgb(102,102,102)">.</span><span class="">failures</span><span class="" style="color:rgb(102,102,102)">.</span><span class="">append</span><span class="">((</span><span class="">test</span><span class="">,</span> <span class="" style="color:rgb(0,128,0)">self</span><span class="" style="color:rgb(102,102,102)">.</span><span class="">_exc_info_to_string</span><span class="">(</span><span class="">err</span><span class="">,</span> <span class="">test</span><span class="">)))</span></div>
<div class="" style="font-family:monospace;white-space:pre;padding:1px 4px;font-size:12px;color:rgb(0,0,0)"><a href="http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/result.py#l122" id="l122" style="text-decoration:none;color:rgb(153,153,153);font-size:smaller"> 122</a> <span class="" style="color:rgb(0,128,0)">self</span><span class="" style="color:rgb(102,102,102)">.</span><span class="">_mirrorOutput</span> <span class="" style="color:rgb(102,102,102)">=</span> <span class="" style="color:rgb(0,128,0)">True</span></div>
<div class="" style="background-color:rgb(240,240,240);font-family:monospace;white-space:pre;padding:1px 4px;font-size:12px;color:rgb(0,0,0)"><a href="http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/result.py#l123" id="l123" style="text-decoration:none;color:rgb(153,153,153);font-size:smaller"> 123</a> </div>
<div class="" style="font-family:monospace;white-space:pre;padding:1px 4px;font-size:12px;color:rgb(0,0,0)"><a href="http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/result.py#l124" id="l124" style="text-decoration:none;color:rgb(153,153,153);font-size:smaller"> 124</a> <span class="" style="color:rgb(170,34,255)">@failfast</span></div>
<div class="" style="background-color:rgb(240,240,240);font-family:monospace;white-space:pre;padding:1px 4px;font-size:12px;color:rgb(0,0,0)"><a href="http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/result.py#l125" id="l125" style="text-decoration:none;color:rgb(153,153,153);font-size:smaller"> 125</a> <span class="" style="color:rgb(0,128,0);font-weight:bold">def</span> <span class="" style="color:rgb(0,0,255)">addSubTest</span><span class="">(</span><span class="" style="color:rgb(0,128,0)">self</span><span class="">,</span> <span class="">test</span><span class="">,</span> <span class="">subtest</span><span class="">,</span> <span class="">err</span><span class="">):</span></div>
<div class="" style="font-family:monospace;white-space:pre;padding:1px 4px;font-size:12px;color:rgb(0,0,0)"><a href="http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/result.py#l126" id="l126" style="text-decoration:none;color:rgb(153,153,153);font-size:smaller"> 126</a> <span class="" style="color:rgb(186,33,33);font-style:italic">"""Called at the end of a subtest.</span></div>
<div class="" style="background-color:rgb(240,240,240);font-family:monospace;white-space:pre;padding:1px 4px;font-size:12px;color:rgb(0,0,0)"><a href="http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/result.py#l127" id="l127" style="text-decoration:none;color:rgb(153,153,153);font-size:smaller"> 127</a> <span class="" style="color:rgb(186,33,33);font-style:italic"> 'err' is None if the subtest ended successfully, otherwise it's a</span></div>
<div class="" style="font-family:monospace;white-space:pre;padding:1px 4px;font-size:12px;color:rgb(0,0,0)"><a href="http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/result.py#l128" id="l128" style="text-decoration:none;color:rgb(153,153,153);font-size:smaller"> 128</a> <span class="" style="color:rgb(186,33,33);font-style:italic"> tuple of values as returned by sys.exc_info().</span></div>
<div class="" style="background-color:rgb(240,240,240);font-family:monospace;white-space:pre;padding:1px 4px;font-size:12px;color:rgb(0,0,0)"><a href="http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/result.py#l129" id="l129" style="text-decoration:none;color:rgb(153,153,153);font-size:smaller"> 129</a> <span class="" style="color:rgb(186,33,33);font-style:italic"> """</span></div>
<div class="" style="background-color:rgb(240,240,240);padding:1px 4px"><span class=""><font color="#ba2121" face="monospace"><span style="font-size:12px;white-space:pre"><i><a href="http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/result.py#l109">http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/result.py#l109</a></i></span></font><br>
</span></div><div class="" style="background-color:rgb(240,240,240);padding:1px 4px"><span class=""><font color="#ba2121" face="monospace"><span style="font-size:12px;white-space:pre"><i><br></i></span></font></span></div>
<div class="" style="background-color:rgb(240,240,240);padding:1px 4px"><span class=""><div class="" style="font-family:monospace;white-space:pre;padding:1px 4px;font-size:12px;color:rgb(0,0,0)"><a href="http://hg.python.org/cpython/file/44f455e6163d/Lib/pdb.py#l589" id="l589" style="text-decoration:none;color:rgb(153,153,153);font-size:smaller"> 589</a> <span class="" style="color:rgb(0,128,0);font-weight:bold">def</span> <span class="" style="color:rgb(0,0,255)">do_break</span><span class="">(</span><span class="" style="color:rgb(0,128,0)">self</span><span class="">,</span> <span class="">arg</span><span class="">,</span> <span class="">temporary</span> <span class="" style="color:rgb(102,102,102)">=</span> <span class="" style="color:rgb(102,102,102)">0</span><span class="">):</span></div>
<div class="" style="background-color:white;font-family:monospace;white-space:pre;padding:1px 4px;font-size:12px;color:rgb(0,0,0)"><a href="http://hg.python.org/cpython/file/44f455e6163d/Lib/pdb.py#l590" id="l590" style="text-decoration:none;color:rgb(153,153,153);font-size:smaller"> 590</a> <span class="" style="color:rgb(186,33,33);font-style:italic">"""b(reak) [ ([filename:]lineno | function) [, condition] ]</span></div>
<div class="" style="font-family:monospace;white-space:pre;padding:1px 4px;font-size:12px;color:rgb(0,0,0)"><a href="http://hg.python.org/cpython/file/44f455e6163d/Lib/pdb.py#l591" id="l591" style="text-decoration:none;color:rgb(153,153,153);font-size:smaller"> 591</a> <span class="" style="color:rgb(186,33,33);font-style:italic"> Without argument, list all breaks.</span></div>
<div class="" style="padding:1px 4px"><span class=""><font color="#ba2121" face="monospace"><span style="font-size:12px;white-space:pre"><i><a href="http://hg.python.org/cpython/file/44f455e6163d/Lib/pdb.py#l589">http://hg.python.org/cpython/file/44f455e6163d/Lib/pdb.py#l589</a></i></span></font><br>
</span></div></span></div></span></div></span></div></div></div></div></div>