Rietveld Code Review Tool
Help | Bug tracker | Discussion group | Source code

Delta Between Two Patch Sets: pages/coding-style.html

Issue 29747647: Noissue - Document best practice for formatting multiline statements in Python (Closed)
Left Patch Set: Created April 9, 2018, 7:12 p.m.
Right Patch Set: Incorporate Julian's suggestions Created April 12, 2018, 12:38 p.m.
Left:
Right:
Use n/p to move between diff chunks; N/P to move between comments.
Jump to:
Left: Side by side diff | Download
Right: Side by side diff | Download
« no previous file with change/comment | « no previous file | static/css/main.css » ('j') | static/css/main.css » ('J')
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
LEFTRIGHT
1 title=Coding Style 1 title=Coding Style
2 2
3 3
4 <h2 id="precedence">{{s1 Precedence}}</h2> 4 <h2 id="precedence">{{s1 Precedence}}</h2>
5 5
6 <p>{{s2 The Adblock Plus coding style is based on others. Our rules (both genera l and language specific) always overrule referenced style guides. The language s pecific sections overrule the general section.}}</p> 6 <p>{{s2 The Adblock Plus coding style is based on others. Our rules (both genera l and language specific) always overrule referenced style guides. The language s pecific sections overrule the general section.}}</p>
7 7
8 <h2 id="consistency">{{s3 Consistency}}</h2> 8 <h2 id="consistency">{{s3 Consistency}}</h2>
9 9
10 <p>{{s4 Consistency is most important: Be consistent within functions, files, mo dules and projects. Making existing code conform with this style guide is fine, but it should happen in dedicated commits, preferably for a whole module or proj ect at once.}}</p> 10 <p>{{s4 Consistency is most important: Be consistent within functions, files, mo dules and projects. Making existing code conform with this style guide is fine, but it should happen in dedicated commits, preferably for a whole module or proj ect at once.}}</p>
(...skipping 49 matching lines...) Expand 10 before | Expand all | Expand 10 after
60 <li>{{python-general Follow <a href="https://www.python.org/dev/peps/pep-0008/ "><fix>PEP-8</fix></a> and the recommendations in the offical <fix>Python</fix> documentation.}}</li> 60 <li>{{python-general Follow <a href="https://www.python.org/dev/peps/pep-0008/ "><fix>PEP-8</fix></a> and the recommendations in the offical <fix>Python</fix> documentation.}}</li>
61 <li>{{python-version Make the code compatible with both <fix>Python 2.7</fix> and <fix>Python 3.5+</fix> (see <a href="https://docs.python.org/dev/howto/pypor ting.html">this guide</a>). Use <a href="https://docs.python.org/2/library/__fut ure__.html"><fix>__future__</fix> imports</a> to address syntactic differences b ut avoid <a href="https://pythonhosted.org/six/"><fix>six</fix></a>, <a href="ht tp://python-future.org/compatible_idioms.html"><fix>python-future</fix></a>, etc . to not introduce additional dependencies.}}</li> 61 <li>{{python-version Make the code compatible with both <fix>Python 2.7</fix> and <fix>Python 3.5+</fix> (see <a href="https://docs.python.org/dev/howto/pypor ting.html">this guide</a>). Use <a href="https://docs.python.org/2/library/__fut ure__.html"><fix>__future__</fix> imports</a> to address syntactic differences b ut avoid <a href="https://pythonhosted.org/six/"><fix>six</fix></a>, <a href="ht tp://python-future.org/compatible_idioms.html"><fix>python-future</fix></a>, etc . to not introduce additional dependencies.}}</li>
62 <li>{{python-strings Write string literals so that they match the behaviour of <a href="https://docs.python.org/3/library/functions.html#ascii"><code><fix>asc ii()</fix></code></a>, i.e. use single quotes except to avoid escaping of embedd ed quotes and use <code><fix>\u</fix></code> escapes for non-ascii characters bu t don't prefix strings with <code><fix>u</fix></code>. For docstrings, however, follow <a href="https://www.python.org/dev/peps/pep-0257/">PEP-257</a>.}}</li> 62 <li>{{python-strings Write string literals so that they match the behaviour of <a href="https://docs.python.org/3/library/functions.html#ascii"><code><fix>asc ii()</fix></code></a>, i.e. use single quotes except to avoid escaping of embedd ed quotes and use <code><fix>\u</fix></code> escapes for non-ascii characters bu t don't prefix strings with <code><fix>u</fix></code>. For docstrings, however, follow <a href="https://www.python.org/dev/peps/pep-0257/">PEP-257</a>.}}</li>
63 <li>{{python-prefix In modules, prefix private functions and variables with a single underscore.}}</li> 63 <li>{{python-prefix In modules, prefix private functions and variables with a single underscore.}}</li>
64 <li>{{python-concatenation Use the <code><fix>+</fix></code> operator when con catenating exactly two strings, use the <a href="https://docs.python.org/2/libra ry/stdtypes.html#str.format"><code><fix>format()</fix></code> method</a> for mor e complex string formatting, use the <a href="https://docs.python.org/2/library/ stdtypes.html#str.join"><code><fix>join()</fix></code> method</a> when concatena ting pre-existing sequences.}}</li> 64 <li>{{python-concatenation Use the <code><fix>+</fix></code> operator when con catenating exactly two strings, use the <a href="https://docs.python.org/2/libra ry/stdtypes.html#str.format"><code><fix>format()</fix></code> method</a> for mor e complex string formatting, use the <a href="https://docs.python.org/2/library/ stdtypes.html#str.join"><code><fix>join()</fix></code> method</a> when concatena ting pre-existing sequences.}}</li>
65 <li>{{python-tuple-vs-list Use tuples for data that have structure, use lists for data that have order.}}</li> 65 <li>{{python-tuple-vs-list Use tuples for data that have structure, use lists for data that have order.}}</li>
66 <li>{{python-builtins Don't override builtins except for <a href="https://docs .python.org/2/library/functions.html#non-essential-built-in-funcs">non-essential builtins</a> and <code><fix>file</fix></code> which is superfluos in modern cod e as well.}}</li> 66 <li>{{python-builtins Don't override builtins except for <a href="https://docs .python.org/2/library/functions.html#non-essential-built-in-funcs">non-essential builtins</a> and <code><fix>file</fix></code> which is superfluos in modern cod e as well.}}</li>
67 <li>{{python-map-filter Use list comprehensions or generator expressions inste ad of calling <code><fix>map()</fix></code> or <code><fix>filter()</fix></code> with a lambda function.}}</li> 67 <li>{{python-map-filter Use list comprehensions or generator expressions inste ad of calling <code><fix>map()</fix></code> or <code><fix>filter()</fix></code> with a lambda function.}}</li>
68 <li>{{python-multiline The preferred way of wrapping long lines is by using Py thon's implied line continuation inside parentheses, brackets and braces. Long l ines can be broken over multiple lines by wrapping expressions in parentheses:}} 68 <li>{{python-multiline The preferred way of wrapping long lines is by using Py thon's implied line continuation inside parentheses, brackets and braces. Long l ines can be broken over multiple lines by wrapping expressions in parentheses:}}
69 <ol> 69 <ol>
70 <li>{{python-multiline-a1 aligning follow up lines with the opening parent heses and putting the closing parentheses at the end of the last line}} 70 <li>{{python-multiline-a1[list item] aligning follow up lines with the ope ning parentheses and putting the closing parentheses at the end of the last line }}
71 (<a onclick="getElementById('python-multiline-a1-example').style.displ ay = 'block';">{{python-multiline-a1-example example}}</a>), or 71 (<a onclick="getElementById('python-multiline-a1-example').classList.t oggle('hide');">{{python-multiline-a1-example example}}</a>), or
72 <pre style="display: none" id="python-multiline-a1-example"> 72 <pre class="hide" id="python-multiline-a1-example">
73 longObjectName.longMethodName(argument1, argument2, 73 long_object_name.long_method_name(argument1, argument2,
74 keyword_argument=value) 74 keyword_argument=value)
75 75
76 veryLongVariableName = ['a list of', 'strings that does not', 76 very_long_variable = ['a list of', 'strings that does not',
77 'fit into', 'one line'] 77 'fit into', 'one line']
78 </pre> 78 </pre>
79 </li> 79 </li>
80 <li>{{python-multiline-a2 breaking the line at the opening parentheses, in denting follow up lines by 4 spaces, and placing the closing parentheses on a se parate line that is aligned with the line that contains the opening parentheses} } 80 <li>{{python-multiline-a2[list item] breaking the line at the opening pare ntheses, indenting follow up lines by 4 spaces, and placing the closing parenthe ses on a separate line that is aligned with the line that contains the opening p arentheses}}
81 (<a onclick="getElementById('python-multiline-a2-example').style.displ ay = 'block';">{{python-multiline-a2-example example}}</a>). 81 (<a onclick="getElementById('python-multiline-a2-example').classList.t oggle('hide');">{{python-multiline-a2-example example}}</a>).
82 <pre style="display: none" id="python-multiline-a2-example"> 82 <pre class="hide" id="python-multiline-a2-example">
83 longObjectName.longMethodName( 83 long_object_name.long_method_name(
84 argument1, 84 argument1,
85 argument2, 85 argument2,
86 keyword_argument=value, 86 keyword_argument=value,
87 ) 87 )
88 88
89 veryLongVariableName = [ 89 very_long_variable = [
90 'a list of', 90 'a list of',
91 'strings that does not', 91 'strings that does not',
92 'fit into', 92 'fit into',
93 'one line', 93 'one line',
94 ] 94 ]
95 </pre> 95 </pre>
96 </li> 96 </li>
97 </ol> 97 </ol>
98 {{python-multiline-commas When breaking lists of items separated by commas ( e.g. lists, dicts, argument lists) using the second approach add a comma after t he last element. This allows adding and rearranging items without touching unrel ated lines.}} 98 {{python-multiline-commas When breaking lists of items separated by commas ( e.g. lists, dicts, argument lists) using the second approach add a comma after t he last element. This allows adding and rearranging items without touching unrel ated lines.}}
99 </li> 99 </li>
(...skipping 28 matching lines...) Expand all
128 <ul> 128 <ul>
129 <li>{{objc-conventions Follow Apple's <a href="https://developer.apple.com/lib rary/ios/documentation/Cocoa/Conceptual/ProgrammingWithObjectiveC/Conventions/Co nventions.html">conventions</a>}}.</li> 129 <li>{{objc-conventions Follow Apple's <a href="https://developer.apple.com/lib rary/ios/documentation/Cocoa/Conceptual/ProgrammingWithObjectiveC/Conventions/Co nventions.html">conventions</a>}}.</li>
130 </ul> 130 </ul>
131 131
132 <h2 id="puppet">{{s31 Puppet}}</h2> 132 <h2 id="puppet">{{s31 Puppet}}</h2>
133 <ul> 133 <ul>
134 <li>{{s32 Follow the <a href="http://docs.puppetlabs.com/guides/style_guide.ht ml">Puppet Style Guide</a>.}}</li> 134 <li>{{s32 Follow the <a href="http://docs.puppetlabs.com/guides/style_guide.ht ml">Puppet Style Guide</a>.}}</li>
135 <li>{{s33 Opening braces don't go on their own line.}}</li> 135 <li>{{s33 Opening braces don't go on their own line.}}</li>
136 <li>{{s34 Arrows should not be aligned.}}</li> 136 <li>{{s34 Arrows should not be aligned.}}</li>
137 </ul> 137 </ul>
LEFTRIGHT

Powered by Google App Engine
This is Rietveld