Noissue - Document best practice for formatting multiline statements in Python

pages/coding-style.html

 title=Coding Style
 
 
 <h2 id="precedence">{{s1 Precedence}}</h2>
 
 <p>{{s2 The Adblock Plus coding style is based on others. Our rules (both general and language specific) always overrule referenced style guides. The language specific sections overrule the general section.}}</p>
 
 <h2 id="consistency">{{s3 Consistency}}</h2>
 
 <p>{{s4 Consistency is most important: Be consistent within functions, files, modules 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 project at once.}}</p>
@@ skipping 48 matching lines @@
 <ul>
   <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>
   <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/pyporting.html">this guide</a>). Use <a href="https://docs.python.org/2/library/__future__.html"><fix>__future__</fix> imports</a> to address syntactic differences but avoid <a href="https://pythonhosted.org/six/"><fix>six</fix></a>, <a href="http://python-future.org/compatible_idioms.html"><fix>python-future</fix></a>, etc. to not introduce additional dependencies.}}</li>
   <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>ascii()</fix></code></a>, i.e. use single quotes except to avoid escaping of embedded quotes and use <code><fix>\u</fix></code> escapes for non-ascii characters but 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>
   <li>{{python-prefix In modules, prefix private functions and variables with a single underscore.}}</li>
   <li>{{python-concatenation Use the <code><fix>+</fix></code> operator when concatenating exactly two strings, use the <a href="https://docs.python.org/2/library/stdtypes.html#str.format"><code><fix>format()</fix></code> method</a> for more 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 concatenating pre-existing sequences.}}</li>
   <li>{{python-tuple-vs-list Use tuples for data that have structure, use lists for data that have order.}}</li>
   <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 code as well.}}</li>
   <li>{{python-map-filter Use list comprehensions or generator expressions instead of calling <code><fix>map()</fix></code> or <code><fix>filter()</fix></code> with a lambda function.}}</li>
   <li>{{python-multiline The preferred way of wrapping long lines is by using Python's implied line continuation inside parentheses, brackets and braces. Long lines can be broken over multiple lines by wrapping expressions in parentheses:}}
     <ol>

[juliandoucette, 2018/04/11 13:41:43]

NIT/FWIW: I prefer the one option (the second) instead of two (code style wise).

[Vasily Kuznetsov, 2018/04/11 14:51:39]

If I understand you correctly, you would prefer us to mandate the second style
as the only style. This would make things more consistent, but there are a
couple of arguments against it:

- We already use first style a lot and it seems like everyone likes it,
- In some cases the second style takes too many lines while the first style is
perfectly good and readable.

It does make the style guide more complicated, but in this case I think it's
worth it. In any case, I'm open to changing this if many Python developers would
agree with Julian.

[juliandoucette, 2018/04/11 15:06:49]

Acknowledged.

-      <li>{{python-multiline-a1 aligning follow up lines with the opening parentheses and putting the closing parentheses at the end of the last line}}

[juliandoucette, 2018/04/11 13:41:43]

NIT: Missing capital?

[juliandoucette, 2018/04/11 13:41:44]

NIT: We like to put "list item" as the context of list item strings

[Vasily Kuznetsov, 2018/04/11 14:51:39]

I wanted to make preceding text and these two list items to read as one sentence
together. If you think that it doesn't really work so well as one sentence, I
can also capitalize the first letters and adjust the punctuation.

[Vasily Kuznetsov, 2018/04/11 14:51:39]

I'm not sure what you mean here. How would this line change if I put "list item"
as the context of the string?

[juliandoucette, 2018/04/11 15:06:49]

{{ id[context] content }}

[juliandoucette, 2018/04/11 15:06:49]

Acknowledged.

[Vasily Kuznetsov, 2018/04/12 12:50:25]

Done.

[Vasily Kuznetsov, 2018/04/12 12:50:25]

Done.

-          (<a onclick="getElementById('python-multiline-a1-example').style.display = 'block';">{{python-multiline-a1-example example}}</a>), or

[juliandoucette, 2018/04/11 13:41:43]

NIT/Suggest: this.nextSibling.classList.toggle('show') where
.show{display:block;} (or similar)

[Vasily Kuznetsov, 2018/04/11 14:51:39]

This is nifty! I'd like to change it to this. Should I add .show class to local
embedded CSS or to global CSS for the website?

Note: it might make more sense to have .hide class instead, since <pre> has
{display: block;} by default.

[juliandoucette, 2018/04/11 15:06:49]

main.css... It's unbelievable that this class doesn't already exist :D.
Good thinking :)

[Vasily Kuznetsov, 2018/04/12 12:50:25]

`this.nextSibling` doesn't seem to work for me and it seems that just
referencing the <pre> tag by id will be more robust to possibly future changes,
so I left that part as it was. I incorporated the rest of your suggestion
though, thanks for the suggestion.

[juliandoucette, 2018/04/13 12:12:54]

No worries. I may refactor this separately as show/hiding a section onclick is
pretty generic and could be handled globally.

-        <pre style="display: none" id="python-multiline-a1-example">
+      <li>{{python-multiline-a1[list item] aligning follow up lines with the opening parentheses and putting the closing parentheses at the end of the last line}}
+          (<a onclick="getElementById('python-multiline-a1-example').classList.toggle('hide');">{{python-multiline-a1-example example}}</a>), or
+        <pre class="hide" id="python-multiline-a1-example">
     long_object_name.long_method_name(argument1, argument2,
                                       keyword_argument=value)
 
     very_long_variable = ['a list of', 'strings that does not',
                           'fit into', 'one line']
         </pre>
       </li>
-      <li>{{python-multiline-a2 breaking the line at the opening parentheses, indenting follow up lines by 4 spaces, and placing the closing parentheses on a separate line that is aligned with the line that contains the opening parentheses}}
-          (<a onclick="getElementById('python-multiline-a2-example').style.display = 'block';">{{python-multiline-a2-example example}}</a>).
-        <pre style="display: none" id="python-multiline-a2-example">
+      <li>{{python-multiline-a2[list item] breaking the line at the opening parentheses, indenting follow up lines by 4 spaces, and placing the closing parentheses on a separate line that is aligned with the line that contains the opening parentheses}}
+          (<a onclick="getElementById('python-multiline-a2-example').classList.toggle('hide');">{{python-multiline-a2-example example}}</a>).
+        <pre class="hide" id="python-multiline-a2-example">
     long_object_name.long_method_name(
         argument1,
         argument2,
         keyword_argument=value,
     )
 
     very_long_variable = [
         'a list of',
         'strings that does not',
         'fit into',
@@ skipping 35 matching lines @@
 <ul>
   <li>{{objc-conventions Follow Apple's <a href="https://developer.apple.com/library/ios/documentation/Cocoa/Conceptual/ProgrammingWithObjectiveC/Conventions/Conventions.html">conventions</a>}}.</li>
 </ul>
 
 <h2 id="puppet">{{s31 Puppet}}</h2>
 <ul>
   <li>{{s32 Follow the <a href="http://docs.puppetlabs.com/guides/style_guide.html">Puppet Style Guide</a>.}}</li>
   <li>{{s33 Opening braces don't go on their own line.}}</li>
   <li>{{s34 Arrows should not be aligned.}}</li>
 </ul>