Changeset 4772 for anuga_core/documentation/coding_standards/style_guide_for_python_code_GA_version.htm
- Timestamp:
- Oct 30, 2007, 6:28:37 PM (16 years ago)
- File:
-
- 1 edited
Legend:
- Unmodified
- Added
- Removed
-
anuga_core/documentation/coding_standards/style_guide_for_python_code_GA_version.htm
r3831 r4772 401 401 <h3 style="">Comments</h3> 402 402 403 <pre><span style=""> </span>Comments that contradict the code are worse than no comments.</pre><pre><span style=""> </span>Always make a priority of keeping the comments up-to-date when the</pre><pre><span style=""> </span><span class="GramE">code</span> changes!</pre><pre><o:p> </o:p></pre><pre><span style=""> </span>Comments should be complete sentences.<span style=""> </span>If a comment is a phrase</pre><pre><span style=""> </span><span class="GramE">or</span> sentence, its first word should be capitalized, unless it is an</pre><pre><span style=""> </span><span class="GramE">identifier</span> that begins with a lower case letter (never alter the</pre><pre><span style=""> </span><span class="GramE">case</span> of identifiers!).</pre><pre><o:p> </o:p></pre><pre><span style=""> </span>If a comment is short, the period at the end is best omitted.</pre><pre><span style=""> </span>Block comments generally consist of one or more paragraphs built</pre><pre><span style=""> </span><span class="GramE">out</span> of complete sentences, and each sentence should end in a</pre><pre><span style=""> </span><span class="GramE">period</span>.</pre><pre><o:p> </o:p></pre><pre><span style=""> </span>You should use two spaces after a sentence-ending period, since it</pre><pre><span style=""> </span><span class="GramE">makes</span> Emacs wrapping and filling work <span class="SpellE">consistenty</span>.</pre><pre><o:p> </o:p></pre><pre><span style=""> </span>When writing English, <span class="SpellE">Strunk</span> and White apply.</pre><pre><o:p> </o:p></pre><pre><span style=""> </span>Python coders from non-English speaking countries: please write</pre><pre><span style=""> </span><span class="GramE">your</span> comments in English, unless you are 120% sure that the code</pre><pre><span style=""> </span><span class="GramE">will</span> never be read by people who don't speak your language.</pre><pre><o:p> </o:p></pre><pre><o:p> </o:p></pre><pre><span style=""> </span>Block Comments</pre><pre><o:p> </o:p></pre><pre><span style=""> </span>Block comments generally apply to some (or all) code that follows</pre><pre><span style=""> </span><span class="GramE">them</span>, and are indented to the same level as that code.<span style=""> </span>Each line</pre><pre><span style=""> </span><span class="GramE">of</span> a block comment starts with a # and a single space (unless it</pre><pre><span style=""> </span><span class="GramE">is</span> indented text inside the comment).<span style=""> </span>Paragraphs inside a block</pre><pre><span style=""> </span><span class="GramE">comment</span> are separated by a line containing a single #.<span style=""> </span>Block</pre><pre><span style=""> </span><span class="GramE">comments</span> are best surrounded by a blank line above and below them</pre><pre><span style=""> </span>(<span class="GramE">or</span> two lines above and a single line below for a block comment at</pre><pre><span style=""> </span><span class="GramE">the</span> start of a <span class="SpellE">a</span> new section of function definitions <i style=""><span style="color: blue;">or to delimit <o:p></o:p></span></i></pre><pre><i style=""><span style="color: blue;"><span style=""> </span><span class="GramE">logical</span> sections</span></i>).</pre><pre><o:p> </o:p></pre><pre><span style=""> </span>Inline Comments</pre><pre><o:p> </o:p></pre><pre><span style=""> </span>An inline comment is a comment on the same line as a statement.</pre><pre><span style=""> </span>Inline comments should be used sparingly.<span style=""> </span>Inline comments should</pre><pre><span style=""> </span><span class="GramE">be</span> separated by at least two spaces from the statement.<span style=""> </span>They</pre><pre><span style=""> </span><span class="GramE">should</span> start with a # and a single space.</pre><pre><o:p> </o:p></pre><pre><span style=""> </span>Inline comments are unnecessary and in fact distracting if they state</pre><pre><span style=""> </span><span class="GramE">the</span> obvious.<span style=""> </span>Don't do this:</pre><pre><o:p> </o:p></pre><pre><span style=""> </span>x = x+1<span style=""> </span># Increment x</pre><pre><o:p> </o:p></pre><pre><span style=""> </span>But sometimes, this is useful:</pre><pre><o:p> </o:p></pre><pre><span style=""> </span>x = x+1<span style=""> </span># Compensate for border</pre><pre><o:p> </o:p></pre><pre><span style=""> </span>Developer Comments</pre><pre><o:p> </o:p></pre><pre><span style=""> </span>If software is being created in a multi-developer environment, it is often</pre><pre><span style=""> </span><span class="GramE">useful</span> to comment the code to indicate those sections which require updating </pre><pre><span style=""> </span><span class="GramE">or</span> refining. They should start with # FIXME followed by the name of the </pre><pre><span style=""> </span><span class="GramE">developer</span> in standard brackets. The name should be consistent amongst the</pre><pre><span style=""> </span><span class="GramE">group</span>; either full initials, first name or surname. For example, if </pre><pre><span style=""> </span>Duncan S Gray found an issue, he could insert in the code:</pre><pre><o:p> </o:p></pre><pre style="margin: 0cm 12pt 0.0001pt;"><span style=""> </span>#FIXME (DSG): Should check that function returns something sensible and</pre><pre><span style=""> </span>#<span class="GramE">raise</span> a meaningful exception if it returns None for example</pre><pre><o:p> </o:p></pre><pre><span style=""> </span>This allows other developers to identify areas which require attention with </pre><pre><span style=""> </span><span class="GramE">the</span> added bonus of knowing who logged the issue.</pre><pre><o:p> </o:p></pre>403 <pre><span style=""> </span>Comments that contradict the code are worse than no comments.</pre><pre><span style=""> </span>Always make a priority of keeping the comments up-to-date when the</pre><pre><span style=""> </span><span class="GramE">code</span> changes!</pre><pre><o:p> </o:p></pre><pre><span style=""> </span>Comments should be complete sentences.<span style=""> </span>If a comment is a phrase</pre><pre><span style=""> </span><span class="GramE">or</span> sentence, its first word should be capitalized, unless it is an</pre><pre><span style=""> </span><span class="GramE">identifier</span> that begins with a lower case letter (never alter the</pre><pre><span style=""> </span><span class="GramE">case</span> of identifiers!).</pre><pre><o:p> </o:p></pre><pre><span style=""> </span>If a comment is short, the period at the end is best omitted.</pre><pre><span style=""> </span>Block comments generally consist of one or more paragraphs built</pre><pre><span style=""> </span><span class="GramE">out</span> of complete sentences, and each sentence should end in a</pre><pre><span style=""> </span><span class="GramE">period</span>.</pre><pre><o:p> </o:p></pre><pre><span style=""> </span>You should use two spaces after a sentence-ending period, since it</pre><pre><span style=""> </span><span class="GramE">makes</span> Emacs wrapping and filling work <span class="SpellE">consistenty</span>.</pre><pre><o:p> </o:p></pre><pre><span style=""> </span>When writing English, <span class="SpellE">Strunk</span> and White apply.</pre><pre><o:p> </o:p></pre><pre><span style=""> </span>Python coders from non-English speaking countries: please write</pre><pre><span style=""> </span><span class="GramE">your</span> comments in English, unless you are 120% sure that the code</pre><pre><span style=""> </span><span class="GramE">will</span> never be read by people who don't speak your language.</pre><pre><o:p> </o:p></pre><pre><o:p> </o:p></pre><pre><span style=""> </span>Block Comments</pre><pre><o:p> </o:p></pre><pre><span style=""> </span>Block comments generally apply to some (or all) code that follows</pre><pre><span style=""> </span><span class="GramE">them</span>, and are indented to the same level as that code.<span style=""> </span>Each line</pre><pre><span style=""> </span><span class="GramE">of</span> a block comment starts with a # and a single space (unless it</pre><pre><span style=""> </span><span class="GramE">is</span> indented text inside the comment).<span style=""> </span>Paragraphs inside a block</pre><pre><span style=""> </span><span class="GramE">comment</span> are separated by a line containing a single #.<span style=""> </span>Block</pre><pre><span style=""> </span><span class="GramE">comments</span> are best surrounded by a blank line above and below them</pre><pre><span style=""> </span>(<span class="GramE">or</span> two lines above and a single line below for a block comment at</pre><pre><span style=""> </span><span class="GramE">the</span> start of a <span class="SpellE">a</span> new section of function definitions <i style=""><span style="color: blue;">or to delimit <o:p></o:p></span></i></pre><pre><i style=""><span style="color: blue;"><span style=""> </span><span class="GramE">logical</span> sections</span></i>).</pre><pre><o:p> </o:p></pre><pre><span style=""> </span>Inline Comments</pre><pre><o:p> </o:p></pre><pre><span style=""> </span>An inline comment is a comment on the same line as a statement.</pre><pre><span style=""> </span>Inline comments should be used sparingly.<span style=""> </span>Inline comments should</pre><pre><span style=""> </span><span class="GramE">be</span> separated by at least two spaces from the statement.<span style=""> </span>They</pre><pre><span style=""> </span><span class="GramE">should</span> start with a # and a single space.</pre><pre><o:p> </o:p></pre><pre><span style=""> </span>Inline comments are unnecessary and in fact distracting if they state</pre><pre><span style=""> </span><span class="GramE">the</span> obvious.<span style=""> </span>Don't do this:</pre><pre><o:p> </o:p></pre><pre><span style=""> </span>x = x+1<span style=""> </span># Increment x</pre><pre><o:p> </o:p></pre><pre><span style=""> </span>But sometimes, this is useful:</pre><pre><o:p> </o:p></pre><pre><span style=""> </span>x = x+1<span style=""> </span># Compensate for border</pre><pre><o:p> </o:p></pre><pre><span style=""> </span>Developer Comments</pre><pre><o:p> </o:p></pre><pre><span style=""> </span>If software is being created in a multi-developer environment, it is often</pre><pre><span style=""> </span><span class="GramE">useful</span> to comment the code to indicate those sections which require updating </pre><pre><span style=""> </span><span class="GramE">or</span> refining. They should start with # FIXME followed by the name of the </pre><pre><span style=""> </span><span class="GramE">developer</span> in standard brackets. The name should be consistent amongst the</pre><pre><span style=""> </span><span class="GramE">group</span>; either full initials, first name or surname. For example, if </pre><pre><span style=""> </span>Duncan S Gray found an issue, he could insert in the code:</pre><pre><o:p> </o:p></pre><pre style="margin: 0cm 12pt 0.0001pt;"><span style=""> </span># FIXME (DSG): Should check that function returns something sensible and</pre><pre><span style=""> </span># <span class="GramE">raise</span> a meaningful exception if it returns None for example</pre><pre><o:p> </o:p></pre><pre><span style=""> </span>This allows other developers to identify areas which require attention with </pre><pre><span style=""> </span><span class="GramE">the</span> added bonus of knowing who logged the issue.</pre><pre><o:p> </o:p></pre> 404 404 405 405 <h3 style="">Documentation
Note: See TracChangeset
for help on using the changeset viewer.
