- Timestamp:
- Aug 4, 2006, 11:49:36 AM (19 years ago)
- File:
-
- 1 edited
Legend:
- Unmodified
- Added
- Removed
-
documentation/coding_standards/Style Guide for Python Code, GA version.htm
r2419 r3449 34 34 <o:DocumentProperties> 35 35 <o:Author>nielsen ole</o:Author> 36 <o:LastAuthor> sexton jane</o:LastAuthor>37 <o:Revision> 3</o:Revision>38 <o:TotalTime> 45</o:TotalTime>36 <o:LastAuthor>gray duncan</o:LastAuthor> 37 <o:Revision>6</o:Revision> 38 <o:TotalTime>51</o:TotalTime> 39 39 <o:Created>2006-02-16T06:00:00Z</o:Created> 40 <o:LastSaved>2006-0 2-16T06:02:00Z</o:LastSaved>41 <o:Pages> 1</o:Pages>42 <o:Words>40 06</o:Words>43 <o:Characters>228 39</o:Characters>40 <o:LastSaved>2006-08-04T01:38:00Z</o:LastSaved> 41 <o:Pages>2</o:Pages> 42 <o:Words>4017</o:Words> 43 <o:Characters>22898</o:Characters> 44 44 <o:Company>Geoscience Australia</o:Company> 45 45 <o:Lines>190</o:Lines> 46 46 <o:Paragraphs>53</o:Paragraphs> 47 <o:CharactersWithSpaces>26 792</o:CharactersWithSpaces>47 <o:CharactersWithSpaces>26862</o:CharactersWithSpaces> 48 48 <o:Version>10.6626</o:Version> 49 49 </o:DocumentProperties> … … 52 52 <w:SpellingState>Clean</w:SpellingState> 53 53 <w:GrammarState>Clean</w:GrammarState> 54 <w:Compatibility> 55 <w:UseFELayout/> 56 </w:Compatibility> 54 57 <w:BrowserLevel>MicrosoftInternetExplorer4</w:BrowserLevel> 55 58 </w:WordDocument> … … 64 67 <style> 65 68 <!-- 69 /* Font Definitions */ 70 @font-face 71 {font-family:"MS Mincho"; 72 panose-1:2 2 6 9 4 2 5 8 3 4; 73 mso-font-alt:"\FF2D\FF33 \660E\671D"; 74 mso-font-charset:128; 75 mso-generic-font-family:modern; 76 mso-font-pitch:fixed; 77 mso-font-signature:-1610612033 1757936891 16 0 131231 0;} 78 @font-face 79 {font-family:"\@MS Mincho"; 80 panose-1:2 2 6 9 4 2 5 8 3 4; 81 mso-font-charset:128; 82 mso-generic-font-family:modern; 83 mso-font-pitch:fixed; 84 mso-font-signature:-1610612033 1757936891 16 0 131231 0;} 66 85 /* Style Definitions */ 67 86 p.MsoNormal, li.MsoNormal, div.MsoNormal … … 72 91 font-size:12.0pt; 73 92 font-family:"Times New Roman"; 74 mso-fareast-font-family:"Times New Roman";} 93 mso-fareast-font-family:"Times New Roman"; 94 mso-bidi-font-family:"Times New Roman";} 75 95 h3 76 96 {mso-margin-top-alt:auto; … … 95 115 font-size:10.0pt; 96 116 font-family:"Courier New"; 97 mso-fareast-font-family:"Times New Roman";} 117 mso-fareast-font-family:"Times New Roman"; 118 mso-bidi-font-family:"Courier New";} 98 119 p.navigation, li.navigation, div.navigation 99 120 {mso-style-name:navigation; … … 105 126 font-size:12.0pt; 106 127 font-family:"Times New Roman"; 107 mso-fareast-font-family:"Times New Roman";} 128 mso-fareast-font-family:"Times New Roman"; 129 mso-bidi-font-family:"Times New Roman";} 108 130 p.header, li.header, div.header 109 131 {mso-style-name:header; … … 112 134 font-size:12.0pt; 113 135 font-family:"Times New Roman"; 114 mso-fareast-font-family:"Times New Roman";} 136 mso-fareast-font-family:"Times New Roman"; 137 mso-bidi-font-family:"Times New Roman";} 115 138 p.content, li.content, div.content 116 139 {mso-style-name:content; … … 120 143 font-size:12.0pt; 121 144 font-family:"Times New Roman"; 122 mso-fareast-font-family:"Times New Roman";} 145 mso-fareast-font-family:"Times New Roman"; 146 mso-bidi-font-family:"Times New Roman";} 123 147 p.navicon, li.navicon, div.navicon 124 148 {mso-style-name:navicon; … … 131 155 font-size:12.0pt; 132 156 font-family:"Times New Roman"; 133 mso-fareast-font-family:"Times New Roman";} 157 mso-fareast-font-family:"Times New Roman"; 158 mso-bidi-font-family:"Times New Roman";} 134 159 p.textlinks, li.textlinks, div.textlinks 135 160 {mso-style-name:textlinks; … … 142 167 font-size:12.0pt; 143 168 font-family:"Times New Roman"; 144 mso-fareast-font-family:"Times New Roman";} 169 mso-fareast-font-family:"Times New Roman"; 170 mso-bidi-font-family:"Times New Roman";} 145 171 p.navicon1, li.navicon1, div.navicon1 146 172 {mso-style-name:navicon1; … … 153 179 font-size:12.0pt; 154 180 font-family:"Times New Roman"; 155 mso-fareast-font-family:"Times New Roman";} 181 mso-fareast-font-family:"Times New Roman"; 182 mso-bidi-font-family:"Times New Roman";} 156 183 p.textlinks1, li.textlinks1, div.textlinks1 157 184 {mso-style-name:textlinks1; … … 164 191 font-size:12.0pt; 165 192 font-family:"Times New Roman"; 166 mso-fareast-font-family:"Times New Roman";} 193 mso-fareast-font-family:"Times New Roman"; 194 mso-bidi-font-family:"Times New Roman";} 167 195 span.SpellE 168 196 {mso-style-name:""; … … 255 283 to templates. DO NOT USE THIS HTML FILE AS YOUR TEMPLATE! 256 284 --><!--[if gte mso 9]><xml> 257 <o:shapedefaults v:ext="edit" spidmax=" 8194"/>285 <o:shapedefaults v:ext="edit" spidmax="9218"/> 258 286 </xml><![endif]--><!--[if gte mso 9]><xml> 259 287 <o:shapelayout v:ext="edit"> … … 353 381 </td> 354 382 <td style='padding:.75pt .75pt .75pt .75pt'> 355 <p class=MsoNormal><st1:date Year="2001" Day="5" Month="7">05-Jul-2001</st1:date></p>383 <p class=MsoNormal><st1:date Month="7" Day="5" Year="2001">05-Jul-2001</st1:date></p> 356 384 </td> 357 385 </tr> … … 363 391 <td style='padding:.75pt .75pt .75pt .75pt'> 364 392 <p class=MsoNormal>Modified slightly by Ole Nielsen <<span class=SpellE>Ole.Nielsen</span> 365 at <span class=SpellE>ga.gov.au</span>> and Duncan Gray <<span366 class=SpellE>Duncan.gray</span> at <span class=SpellE>ga.gov.au</span>></p>393 at ga.gov.au> and Duncan Gray <<span class=SpellE>Duncan.gray</span> at 394 ga.gov.au></p> 367 395 <p class=MsoNormal>Geoscience Australia 2005. </p> 368 396 <p class=MsoNormal>The GA modifications are clearly flagged using blue … … 386 414 <pre><span style='mso-spacerun:yes'> </span>This document gives coding conventions for the Python code</pre><pre><span style='mso-spacerun:yes'> </span><span 387 415 class=GramE>comprising</span> the standard library for the main Python distribution.</pre><pre><span style='mso-spacerun:yes'> </span>Please see the companion informational PEP describing style</pre><pre><span style='mso-spacerun:yes'> </span><span 388 class=GramE>guidelines</span> for the C code in the C implementation of Python[1].</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>This document was adapted from Guido's original Python Style</pre><pre><span style='mso-spacerun:yes'> </span><span style='mso-spacerun:yes'></span>Guide <span416 class=GramE>guidelines</span> for the C code in the C implementation of Python[1].</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>This document was adapted from Guido's original Python Style</pre><pre><span style='mso-spacerun:yes'> </span>Guide <span 389 417 class=GramE>essay[</span>2], with some additions from Barry's style guide[5].</pre><pre><span style='mso-spacerun:yes'> </span>Where there's conflict, Guido's style rules for the purposes of</pre><pre><span style='mso-spacerun:yes'> </span><span 390 418 class=GramE>this</span> PEP.<span style='mso-spacerun:yes'> </span>This PEP may still be incomplete (in fact, it may never</pre><pre><span style='mso-spacerun:yes'> </span><span … … 399 427 class=GramE>the</span> style guide just doesn't apply.<span style='mso-spacerun:yes'> </span>When in doubt, use your best</pre><pre><span style='mso-spacerun:yes'> </span><span 400 428 class=GramE>judgement</span>.<span style='mso-spacerun:yes'> </span>Look at other examples and decide what looks best.</pre><pre><span style='mso-spacerun:yes'> </span>And don't hesitate to ask!</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>Two good reasons to break a particular rule:</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>(1) When applying the rule would make the code less readable, even</pre><pre><span style='mso-spacerun:yes'> </span><span 401 class=GramE>for</span> someone who is used to reading code that follows the rules.</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>(2) To be consistent with surrounding code that also breaks it</pre><pre><span style='mso-spacerun:yes'> </span><span style='mso-spacerun:yes'></span>(<span429 class=GramE>for</span> someone who is used to reading code that follows the rules.</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>(2) To be consistent with surrounding code that also breaks it</pre><pre><span style='mso-spacerun:yes'> </span>(<span 402 430 class=GramE>maybe</span> for historic reasons) -- <span class=GramE>although</span> this is also an</pre><pre><span style='mso-spacerun:yes'> </span><span 403 431 class=GramE>opportunity</span> to clean up someone else's mess (in true XP style).</pre><pre><o:p> </o:p></pre><pre><o:p> </o:p></pre> … … 405 433 <h3>Code lay-out</h3> 406 434 407 <pre><span style='mso-spacerun:yes'> </span>Indentation</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>Use the default of <span 408 class=SpellE>Emacs</span>' Python-mode: 4 spaces for one</pre><pre><span style='mso-spacerun:yes'> </span><span 435 <pre><span style='mso-spacerun:yes'> </span>Indentation</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>Use the default of Emacs' Python-mode: 4 spaces for one</pre><pre><span style='mso-spacerun:yes'> </span><span 409 436 class=GramE>indentation</span> level.<span style='mso-spacerun:yes'> </span>For really old code that you don't want to</pre><pre><span style='mso-spacerun:yes'> </span><span 410 class=GramE>mess</span> up, you can continue to use 8-space tabs.<span style='mso-spacerun:yes'> </span><span 411 class=SpellE>Emacs</span> Python-mode</pre><pre><span style='mso-spacerun:yes'> </span><span 437 class=GramE>mess</span> up, you can continue to use 8-space tabs.<span style='mso-spacerun:yes'> </span>Emacs Python-mode</pre><pre><span style='mso-spacerun:yes'> </span><span 412 438 class=GramE>auto-</span>detects the prevailing indentation level used in a file and</pre><pre><span style='mso-spacerun:yes'> </span><span 413 439 class=GramE>sets</span> its indentation parameters accordingly.</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span><span 414 440 class=GramE>Tabs or Spaces?</span></pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>Never mix tabs and spaces.<span style='mso-spacerun:yes'> </span>The most popular way of indenting</pre><pre><span style='mso-spacerun:yes'> </span>Python is with spaces only.<span style='mso-spacerun:yes'> </span>The second-most popular way is with</pre><pre><span style='mso-spacerun:yes'> </span><span 415 441 class=GramE>tabs</span> only.<span style='mso-spacerun:yes'> </span>Code indented with a mixture of tabs and spaces should</pre><pre><span style='mso-spacerun:yes'> </span><span 416 class=GramE>be</span> converted to using spaces exclusively.<span style='mso-spacerun:yes'> </span>(In <span 417 class=SpellE>Emacs</span>, select the</pre><pre><span style='mso-spacerun:yes'> </span><span 442 class=GramE>be</span> converted to using spaces exclusively.<span style='mso-spacerun:yes'> </span>(In Emacs, select the</pre><pre><span style='mso-spacerun:yes'> </span><span 418 443 class=GramE>whole</span> buffer and hit ESC-x <span class=SpellE>untabify</span>.)<span style='mso-spacerun:yes'> </span>When invoking the python</pre><pre><span style='mso-spacerun:yes'> </span><span 419 444 class=GramE>command</span> line interpreter with the -t option, it issues warnings</pre><pre><span style='mso-spacerun:yes'> </span><span … … 421 446 class=SpellE>tt</span></pre><pre><span style='mso-spacerun:yes'> </span><span 422 447 class=GramE>these</span> warnings become errors.<span style='mso-spacerun:yes'> </span>These options are highly</pre><pre><span style='mso-spacerun:yes'> </span><span 423 class=GramE>recommended</span>!</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>For new projects, spaces-only are strongly recommended over tabs.</pre><pre><span style='mso-spacerun:yes'> </span>Most editors have features that make this easy to do.<span style='mso-spacerun:yes'> </span>(In <span 424 class=SpellE>Emacs</span>,</pre><pre><span style='mso-spacerun:yes'> </span><span 448 class=GramE>recommended</span>!</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>For new projects, spaces-only are strongly recommended over tabs.</pre><pre><span style='mso-spacerun:yes'> </span>Most editors have features that make this easy to do.<span style='mso-spacerun:yes'> </span>(In Emacs,</pre><pre><span style='mso-spacerun:yes'> </span><span 425 449 class=GramE>make</span> sure indent-tabs-mode is nil).</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>Maximum Line Length</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>There are still many devices around that are limited to 80</pre><pre><span style='mso-spacerun:yes'> </span><span 426 450 class=GramE>character</span> lines; plus, limiting windows to 80 characters makes it</pre><pre><span style='mso-spacerun:yes'> </span><span 427 451 class=GramE>possible</span> to have several windows side-by-side.<span style='mso-spacerun:yes'> </span>The default</pre><pre><span style='mso-spacerun:yes'> </span><span 428 452 class=GramE>wrapping</span> on such devices looks ugly.<span style='mso-spacerun:yes'> </span>Therefore, please limit all</pre><pre><span style='mso-spacerun:yes'> </span><span 429 class=GramE>lines</span> to a maximum of 79 characters ( <span class=SpellE>Emacs</span>wraps lines that are</pre><pre><span style='mso-spacerun:yes'> </span><span453 class=GramE>lines</span> to a maximum of 79 characters (Emacs wraps lines that are</pre><pre><span style='mso-spacerun:yes'> </span><span 430 454 class=GramE>exactly</span> 80 characters long).<span style='mso-spacerun:yes'> </span>For flowing long blocks of text</pre><pre><span style='mso-spacerun:yes'> </span>(<span 431 455 class=SpellE>docstrings</span> or comments), limiting the length to 72 characters is</pre><pre><span style='mso-spacerun:yes'> </span><span … … 433 457 class=GramE>implied</span> line continuation inside parentheses, brackets and braces.</pre><pre><span style='mso-spacerun:yes'> </span>If necessary, you can add an extra pair of parentheses around an</pre><pre><span style='mso-spacerun:yes'> </span><span 434 458 class=GramE>expression</span>, but sometimes using a backslash looks better.<span style='mso-spacerun:yes'> </span>Make</pre><pre><span style='mso-spacerun:yes'> </span><span 435 class=GramE>sure</span> to indent the continued line appropriately.<span style='mso-spacerun:yes'> </span><span 436 class=SpellE>Emacs</span></pre><pre><span style='mso-spacerun:yes'> </span>Python-mode does this right.<span style='mso-spacerun:yes'> </span>Some examples:</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span><span 459 class=GramE>sure</span> to indent the continued line appropriately.<span style='mso-spacerun:yes'> </span>Emacs</pre><pre><span style='mso-spacerun:yes'> </span>Python-mode does this right.<span style='mso-spacerun:yes'> </span>Some examples:</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span><span 437 460 class=GramE>class</span> Rectangle(Blob):</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span><span 438 461 class=GramE>def</span> __init__(self, width, height,</pre><pre><span style='mso-spacerun:yes'> </span><span … … 442 465 class=GramE>highlight</span> > 100:</pre><pre><span style='mso-spacerun:yes'> </span><span 443 466 class=GramE>raise</span> <span class=SpellE>ValueError</span>("sorry, you lose")</pre><pre><span style='mso-spacerun:yes'> </span><span 444 class=GramE>if</span> width == 0 and height == 0 and (<span class=SpellE>color</span> == 'red' or</pre><pre><span style='mso-spacerun:yes'> 467 class=GramE>if</span> width == 0 and height == 0 and (<span class=SpellE>color</span> == 'red' or</pre><pre><span style='mso-spacerun:yes'> </span><span style='mso-spacerun:yes'> </span><span 445 468 class=GramE>emphasis</span> is None):</pre><pre><span style='mso-spacerun:yes'> </span><span 446 469 class=GramE>raise</span> <span class=SpellE>ValueError</span>("I don't think so")</pre><pre><span style='mso-spacerun:yes'> </span><span … … 454 477 class=GramE>implementations</span>).</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>When blank lines are used to separate method definitions, there is</pre><pre><span style='mso-spacerun:yes'> </span><span 455 478 class=GramE>also</span> a blank line between the `class' line and the first method</pre><pre><span style='mso-spacerun:yes'> </span><span 456 class=GramE>definition</span>.</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span><span style='mso-spacerun:yes'></span>Use blank lines in functions, <s>sparingly</s> <i479 class=GramE>definition</span>.</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>Use blank lines in functions, <s>sparingly</s> <i 457 480 style='mso-bidi-font-style:normal'><span style='color:blue'>liberally</span></i>, to indicate logical</pre><pre><span style='mso-spacerun:yes'> </span><span 458 481 class=GramE>sections</span>.</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>Python accepts the control-L (i.e. ^L) form feed character as</pre><pre><span style='mso-spacerun:yes'> </span><span 459 class=SpellE>whitespace</span>; <span class=SpellE>Emacs</span>(and some printing tools) treat these</pre><pre><span style='mso-spacerun:yes'> </span><span482 class=SpellE>whitespace</span>; Emacs (and some printing tools) treat these</pre><pre><span style='mso-spacerun:yes'> </span><span 460 483 class=GramE>characters</span> as page separators, so you may use them to separate</pre><pre><span style='mso-spacerun:yes'> </span><span 461 484 class=GramE>pages</span> of related sections of your file.</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>Encodings (<a … … 490 513 class=GramE>and</span> before module <span class=SpellE>globals</span> and constants.<span style='mso-spacerun:yes'> </span>Imports should be grouped, </pre><pre 491 514 style='margin-left:24.0pt'><span style='mso-spacerun:yes'> </span><span 492 class=GramE>with</span> the order being</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> 515 class=GramE>with</span> the order being</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span><span style='mso-spacerun:yes'> </span>1. <span 493 516 class=GramE>standard</span> library imports</pre><pre><span style='mso-spacerun:yes'> </span>2. <span 494 517 class=GramE>related</span> major package imports (i.e. all email package imports next)</pre><pre><span style='mso-spacerun:yes'> </span>3. <span … … 522 545 class=SpellE>whitespace</span> in the following places:</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>- Immediately inside parentheses, brackets or braces, as in:</pre><pre><span style='mso-spacerun:yes'> </span>"<span 523 546 class=GramE>spam(</span> ham[ 1 ], { eggs: 2 } )".<span style='mso-spacerun:yes'> </span>Always write this as</pre><pre><span style='mso-spacerun:yes'> </span>"<span 524 class=GramE>spam(</span>ham[1], {eggs: 2})".</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>- Immediately before a comma, semicolon, or colon, as in:</pre><pre><span style='mso-spacerun:yes'> </span>"<span 525 class=GramE>if</span> x == 4 : print x , y ; x , y = y , x".<span style='mso-spacerun:yes'> </span>Always write this as</pre><pre><span style='mso-spacerun:yes'> </span>"<span 526 class=GramE>if</span> x == 4: print x, y; x, y = y, x".</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>- Immediately before the open parenthesis that starts the argument</pre><pre><span style='mso-spacerun:yes'> </span><span 547 class=GramE>spam(</span>ham[1], {eggs: 2})".</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>- Immediately before a comma, semicolon, or colon, as in:</pre><pre><span style='mso-spacerun:yes'> </span><span 548 lang=ES style='mso-ansi-language:ES'>"<span class=SpellE>if</span> x == <span 549 class=GramE>4 :</span> <span class=SpellE>print</span> x , y ; x , y = y , x".<span style='mso-spacerun:yes'> </span></span>Always write this as</pre><pre><span style='mso-spacerun:yes'> </span><span 550 lang=ES style='mso-ansi-language:ES'>"<span class=SpellE>if</span> x == 4: <span 551 class=SpellE>print</span> x, y; x, y = y, x".<o:p></o:p></span></pre><pre><span 552 lang=ES style='mso-ansi-language:ES'><o:p> </o:p></span></pre><pre><span 553 lang=ES style='mso-ansi-language:ES'><span style='mso-spacerun:yes'> </span></span>- Immediately before the open parenthesis that starts the argument</pre><pre><span style='mso-spacerun:yes'> </span><span 527 554 class=GramE>list</span> of a function call, as in "spam (1)".<span style='mso-spacerun:yes'> </span>Always write</pre><pre><span style='mso-spacerun:yes'> </span><span 528 555 class=GramE>this</span> as "spam(1)".</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>- Immediately before the open parenthesis that starts an indexing or</pre><pre><span style='mso-spacerun:yes'> </span><span 529 556 class=GramE>slicing</span>, as in: "<span class=SpellE>dict</span> ['key'] = list [index]".<span style='mso-spacerun:yes'> </span>Always</pre><pre><span style='mso-spacerun:yes'> </span><span 530 557 class=GramE>write</span> this as "<span class=SpellE>dict</span>['key'] = list[index]".</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>- More than one space around an assignment (or other) operator to</pre><pre><span style='mso-spacerun:yes'> </span><span 531 class=GramE>align</span> it with another, as in:</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>x<span style='mso-spacerun:yes'> </span>= 1</pre><pre><span style='mso-spacerun:yes'> </span>y<span style='mso-spacerun:yes'> </span>= 2</pre><pre> <span style='mso-spacerun:yes'></span><span532 class=SpellE>long_variable</span> = 3</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>Always write this as</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span><span style='mso-spacerun:yes'></span>x = 1</pre><pre><span style='mso-spacerun:yes'> </span>y = 2</pre><pre><span style='mso-spacerun:yes'> </span><span558 class=GramE>align</span> it with another, as in:</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>x<span style='mso-spacerun:yes'> </span>= 1</pre><pre><span style='mso-spacerun:yes'> </span>y<span style='mso-spacerun:yes'> </span>= 2</pre><pre> <span style='mso-spacerun:yes'> </span><span 559 class=SpellE>long_variable</span> = 3</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>Always write this as</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>x = 1</pre><pre><span style='mso-spacerun:yes'> </span>y = 2</pre><pre><span style='mso-spacerun:yes'> </span><span 533 560 class=SpellE>long_variable</span> = 3</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>(Don't bother to argue with him on any of the above -- Guido's</pre><pre><span style='mso-spacerun:yes'> </span><span 534 561 class=GramE>grown</span> accustomed to this style over 20 years.)</pre><pre><o:p> </o:p></pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>Other Recommendations</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>- Always surround these binary operators with a single space on</pre><pre><span style='mso-spacerun:yes'> </span><span … … 538 565 class=GramE>either</span> side of a binary operator.<span style='mso-spacerun:yes'> </span>Some examples:</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span><span 539 566 class=SpellE>i</span> = i+1</pre><pre><span style='mso-spacerun:yes'> </span><span 540 class=GramE>submitted</span> = submitted + 1</pre><pre><span style='mso-spacerun:yes'> </span>x = x*2 - 1</pre><pre><span style='mso-spacerun:yes'> </span>hypot2 = x*x + y*y</pre><pre><span style='mso-spacerun:yes'> </span>c = (<span 541 class=SpellE>a+b</span>) * (a-b)</pre><pre><span style='mso-spacerun:yes'> </span>c = (a + b) * (a - b)</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>- Don't use spaces around the '=' sign when used to indicate a</pre><pre><span style='mso-spacerun:yes'> </span><span 567 class=GramE>submitted</span> = submitted + 1</pre><pre><span style='mso-spacerun:yes'> </span>x = x*2 - 1</pre><pre><span style='mso-spacerun:yes'> </span><span 568 lang=ES style='mso-ansi-language:ES'>hypot2 = <span class=SpellE>x*x</span> + <span 569 class=SpellE>y*y</span><o:p></o:p></span></pre><pre><span lang=ES 570 style='mso-ansi-language:ES'><span style='mso-spacerun:yes'> </span>c = (<span 571 class=SpellE>a+b</span>) * (a-b)<o:p></o:p></span></pre><pre><span lang=ES 572 style='mso-ansi-language:ES'><span style='mso-spacerun:yes'> </span></span>c = (a + b) * (a - b)</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>- Don't use spaces around the '=' sign when used to indicate a</pre><pre><span style='mso-spacerun:yes'> </span><span 542 573 class=GramE>keyword</span> argument or a default parameter value.<span style='mso-spacerun:yes'> </span>For instance:</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span><span 543 class=GramE>def</span> complex(real, <span class=SpellE>imag</span>=0.0):</pre><pre><span style='mso-spacerun:yes'> 574 class=GramE>def</span> complex(real, <span class=SpellE>imag</span>=0.0):</pre><pre><span style='mso-spacerun:yes'> </span><span style='mso-spacerun:yes'> </span><span 544 575 class=GramE>return</span> magic(r=real, <span class=SpellE>i</span>=<span 545 576 class=SpellE>imag</span>)</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>- Compound statements (multiple statements on the same line) are</pre><pre><span style='mso-spacerun:yes'> </span><span … … 548 579 class=GramE>thing</span></span><span class=GramE>()</span></pre><pre><span style='mso-spacerun:yes'> </span>Yes: if <span 549 580 class=SpellE>foo</span> == 'blah':</pre><pre><span style='mso-spacerun:yes'> </span><span 550 class=SpellE>do_blah_<span class=GramE>thing</span></span><span class=GramE>()</span></pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> 581 class=SpellE>do_blah_<span class=GramE>thing</span></span><span class=GramE>()</span></pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span><span style='mso-spacerun:yes'> </span>No:<span style='mso-spacerun:yes'> </span><span 551 582 class=SpellE>do_<span class=GramE>one</span></span><span class=GramE>(</span>); <span 552 583 class=SpellE>do_two</span>(); <span class=SpellE>do_three</span>()</pre><pre><span style='mso-spacerun:yes'> </span>Yes: <span … … 564 595 class=GramE>out</span> of complete sentences, and each sentence should end in a</pre><pre><span style='mso-spacerun:yes'> </span><span 565 596 class=GramE>period</span>.</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>You should use two spaces after a sentence-ending period, since it</pre><pre><span style='mso-spacerun:yes'> </span><span 566 class=GramE>makes</span> <span class=SpellE>Emacs</span> wrapping and filling work <span 567 class=SpellE>consistenty</span>.</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>When writing English, <span 597 class=GramE>makes</span> Emacs wrapping and filling work <span class=SpellE>consistenty</span>.</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>When writing English, <span 568 598 class=SpellE>Strunk</span> and White apply.</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>Python coders from non-English speaking countries: please write</pre><pre><span style='mso-spacerun:yes'> </span><span 569 599 class=GramE>your</span> comments in English, unless you are 120% sure that the code</pre><pre><span style='mso-spacerun:yes'> </span><span … … 587 617 class=GramE>group</span>; either full initials, first name or surname. For example, if </pre><pre><span style='mso-spacerun:yes'> </span>Duncan S Gray found an issue, he could insert in the code:</pre><pre><o:p> </o:p></pre><pre 588 618 style='margin-top:0cm;margin-right:12.0pt;margin-bottom:0cm;margin-left:12.0pt; 589 margin-bottom:.0001pt'><span style='mso-spacerun:yes'> </span>#FIXME (DSG): Should check that function returns something sensible and< o:p></o:p></pre><pre> <span style='mso-spacerun:yes'></span>#<span619 margin-bottom:.0001pt'><span style='mso-spacerun:yes'> </span>#FIXME (DSG): Should check that function returns something sensible and</pre><pre><span style='mso-spacerun:yes'> </span>#<span 590 620 class=GramE>raise</span> a meaningful exception if it returns None for example</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>This allows other developers to identify areas which require attention with </pre><pre><span style='mso-spacerun:yes'> </span><span 591 621 class=GramE>the</span> added bonus of knowing who logged the issue.</pre><pre><o:p> </o:p></pre> … … 605 635 style='color:blue'>Ideally, all modules, functions, classes, and methods should have <o:p></o:p></span></i></pre><pre><i 606 636 style='mso-bidi-font-style:normal'><span style='color:blue'><span style='mso-spacerun:yes'> </span><span 607 class=GramE>a</span> <span class=SpellE>docstring</span>.<o:p></o:p></span></i></pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>- <a 637 class=GramE>a</span> <span class=SpellE>docstring</span>.<o:p></o:p></span></i></pre><pre><i 638 style='mso-bidi-font-style:normal'><span style='color:blue'> <span style='mso-spacerun:yes'> </span>- For test methods #s are preferred, over <span 639 class=SpellE>docstrings</span>.<span style='mso-spacerun:yes'> </span><span 640 class=SpellE>Docstrings</span> dont <o:p></o:p></span></i></pre><pre><i 641 style='mso-bidi-font-style:normal'><span style='color:blue'><span 642 style='mso-tab-count:1'> </span>work well with verbose=2. <o:p></o:p></span></i></pre><pre><i 643 style='mso-bidi-font-style:normal'><span style='color:blue'><o:p> </o:p></span></i></pre><pre><i 644 style='mso-bidi-font-style:normal'><span style='color:blue'><o:p> </o:p></span></i></pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>- <a 608 645 href="http://www.python.org/peps/pep-0257.html">PEP 257</a> describes good <span 609 646 class=SpellE>docstring</span> conventions.<span style='mso-spacerun:yes'> </span>Note that most</pre><pre><span style='mso-spacerun:yes'> </span><span … … 613 650 class=SpellE>foobang</span></pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>Optional <span 614 651 class=SpellE>plotz</span> says to <span class=SpellE>frobnicate</span> the <span 615 class=SpellE>bizbaz</span> first.</pre><pre><span style='mso-spacerun:yes'> </span><span style='mso-spacerun:yes'></span>"""</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>- For one liner <span652 class=SpellE>bizbaz</span> first.</pre><pre><span style='mso-spacerun:yes'> </span>"""</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>- For one liner <span 616 653 class=SpellE>docstrings</span>, it's okay to keep the closing """ on</pre><pre><span style='mso-spacerun:yes'> </span><span 617 654 class=GramE>the</span> same line.</pre><pre><o:p> </o:p></pre><pre><o:p> </o:p></pre> … … 647 684 class=GramE>character</span>!)</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>- <span 648 685 class=SpellE>Capitalized_Words_With_Underscores</span> (ugly!)</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>There's also the style of using a short unique prefix to group</pre><pre><span style='mso-spacerun:yes'> </span><span 649 class=GramE>related</span> names together.<span style='mso-spacerun:yes'> </span>This is not used much in Python, but it</pre><pre><span style='mso-spacerun:yes'> </span><span style='mso-spacerun:yes'></span><span686 class=GramE>related</span> names together.<span style='mso-spacerun:yes'> </span>This is not used much in Python, but it</pre><pre><span style='mso-spacerun:yes'> </span><span 650 687 class=GramE>is</span> mentioned for completeness.<span style='mso-spacerun:yes'> </span>For example, the <span 651 688 class=SpellE><span class=GramE>os.stat</span></span><span class=GramE>()</span></pre><pre><span style='mso-spacerun:yes'> </span><span … … 697 734 class=GramE>(e.g. _socket).</span></pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>Python packages should have short, all-lowercase names, <s>without</s> </pre><pre><span style='mso-spacerun:yes'> </span><span 698 735 class=GramE><i style='mso-bidi-font-style:normal'><span style='color:blue'>possibly</span></i></span><i 699 style='mso-bidi-font-style:normal'><span style='color:blue'> with</span></i> underscores.</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>Class Names</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span><span style='mso-spacerun:yes'></span>Almost without exception, class names use the <span736 style='mso-bidi-font-style:normal'><span style='color:blue'> with</span></i> underscores.</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>Class Names</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>Almost without exception, class names use the <span 700 737 class=SpellE>CapWords</span> convention.</pre><pre><span style='mso-spacerun:yes'> </span>Classes for internal use have a leading underscore in addition.</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>Exception Names</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>If a module defines a single exception raised for all sorts of</pre><pre><span style='mso-spacerun:yes'> </span><span 701 738 class=GramE>conditions</span>, it is generally called "error" or "Error".<span style='mso-spacerun:yes'> </span>It seems</pre><pre><span style='mso-spacerun:yes'> </span><span … … 769 806 class=GramE>really</span> mean "if x is not None" -- e.g. when testing whether a</pre><pre><span style='mso-spacerun:yes'> </span><span 770 807 class=GramE>variable</span> or argument that defaults to None was set to some other</pre><pre><span style='mso-spacerun:yes'> </span><span 771 class=GramE>value</span>.<span style='mso-spacerun:yes'> </span>The other value might be a value that's false in a</pre><pre><span style='mso-spacerun:yes'> </span>Boolean context!</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>- Class-based exceptions are always preferred over string-based</pre><pre> <span style='mso-spacerun:yes'></span><span808 class=GramE>value</span>.<span style='mso-spacerun:yes'> </span>The other value might be a value that's false in a</pre><pre><span style='mso-spacerun:yes'> </span>Boolean context!</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>- Class-based exceptions are always preferred over string-based</pre><pre> <span style='mso-spacerun:yes'> </span><span 772 809 class=GramE>exceptions</span>.<span style='mso-spacerun:yes'> </span>Modules or packages should define their own</pre><pre><span style='mso-spacerun:yes'> </span><span 773 810 class=GramE>domain-specific</span> base exception class, which should be subclassed</pre><pre><span style='mso-spacerun:yes'> </span><span … … 806 843 class=GramE>from</span> types import <span class=SpellE>StringTypes</span></pre><pre><span style='mso-spacerun:yes'> </span><span 807 844 class=GramE>if</span> <span class=SpellE>isinstance</span>(obj, <span 808 class=SpellE>StringTypes</span>):</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span><span style='mso-spacerun:yes'></span>In Python 2.0 and 2.1, you should do:</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span><span845 class=SpellE>StringTypes</span>):</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>In Python 2.0 and 2.1, you should do:</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span><span 809 846 class=GramE>from</span> types import <span class=SpellE>StringType</span>, <span 810 847 class=SpellE>UnicodeType</span></pre><pre><span style='mso-spacerun:yes'> </span><span … … 842 879 class=SpellE>Docstring</span> Conventions, <span class=SpellE>Goodger</span>, <span 843 880 class=GramE>van</span> <span class=SpellE>Rossum</span></pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>[4] <a 844 href="http://www.wikipedia.com/wiki/CamelCase">http://www.wikipedia.com/wiki/CamelCase</a></pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>[5] Barry's GNU Mailman style guide</pre><pre><span style='mso-spacerun:yes'> 881 href="http://www.wikipedia.com/wiki/CamelCase">http://www.wikipedia.com/wiki/CamelCase</a></pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>[5] Barry's GNU Mailman style guide</pre><pre><span style='mso-spacerun:yes'> </span><span style='mso-spacerun:yes'> </span><a 845 882 href="http://barry.warsaw.us/software/STYLEGUIDE.txt">http://barry.warsaw.us/software/STYLEGUIDE.txt</a></pre><pre><o:p> </o:p></pre><pre><o:p> </o:p></pre> 846 883
Note: See TracChangeset
for help on using the changeset viewer.
