Left: | ||
Right: |
OLD | NEW |
---|---|
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 47 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... | |
58 <h2 id="python">{{s19 Python}}</h2> | 58 <h2 id="python">{{s19 Python}}</h2> |
59 <ul> | 59 <ul> |
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:}} | |
69 <ol> | |
juliandoucette
2018/04/11 13:41:43
NIT/FWIW: I prefer the one option (the second) ins
Vasily Kuznetsov
2018/04/11 14:51:39
If I understand you correctly, you would prefer us
juliandoucette
2018/04/11 15:06:49
Acknowledged.
| |
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}} | |
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
Vasily Kuznetsov
2018/04/11 14:51:39
I wanted to make preceding text and these two list
Vasily Kuznetsov
2018/04/11 14:51:39
I'm not sure what you mean here. How would this li
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.
| |
71 (<a onclick="getElementById('python-multiline-a1-example').style.displ ay = 'block';">{{python-multiline-a1-example example}}</a>), or | |
juliandoucette
2018/04/11 13:41:43
NIT/Suggest: this.nextSibling.classList.toggle('sh
Vasily Kuznetsov
2018/04/11 14:51:39
This is nifty! I'd like to change it to this. Shou
juliandoucette
2018/04/11 15:06:49
main.css... It's unbelievable that this class does
Vasily Kuznetsov
2018/04/12 12:50:25
`this.nextSibling` doesn't seem to work for me and
juliandoucette
2018/04/13 12:12:54
No worries. I may refactor this separately as show
| |
72 <pre style="display: none" id="python-multiline-a1-example"> | |
73 long_object_name.long_method_name(argument1, argument2, | |
74 keyword_argument=value) | |
75 | |
76 very_long_variable = ['a list of', 'strings that does not', | |
77 'fit into', 'one line'] | |
78 </pre> | |
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} } | |
81 (<a onclick="getElementById('python-multiline-a2-example').style.displ ay = 'block';">{{python-multiline-a2-example example}}</a>). | |
82 <pre style="display: none" id="python-multiline-a2-example"> | |
83 long_object_name.long_method_name( | |
84 argument1, | |
85 argument2, | |
86 keyword_argument=value, | |
87 ) | |
88 | |
89 very_long_variable = [ | |
90 'a list of', | |
91 'strings that does not', | |
92 'fit into', | |
93 'one line', | |
94 ] | |
95 </pre> | |
96 </li> | |
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.}} | |
99 </li> | |
68 <li>{{python-regexp Use <a href="https://docs.python.org/2/library/re.html#re. search"><code><fix>re.search()</fix></code></a> instead of <code><fix>re.match() </fix></code> to avoid <a href="https://docs.python.org/2/library/re.html#search -vs-match">confusion</a> about implied beginning of the string but not the endin g.}}</li> | 100 <li>{{python-regexp Use <a href="https://docs.python.org/2/library/re.html#re. search"><code><fix>re.search()</fix></code></a> instead of <code><fix>re.match() </fix></code> to avoid <a href="https://docs.python.org/2/library/re.html#search -vs-match">confusion</a> about implied beginning of the string but not the endin g.}}</li> |
69 <li> | 101 <li> |
70 {{python-flake8 Run <a href="https://pypi.python.org/pypi/flake8"><fix>flake 8</fix></a> with following extensions and fix all reported errors:}} | 102 {{python-flake8 Run <a href="https://pypi.python.org/pypi/flake8"><fix>flake 8</fix></a> with following extensions and fix all reported errors:}} |
71 <ul> | 103 <ul> |
72 <li><a href="https://hg.adblockplus.org/codingtools/file/tip/flake8-eyeo"> flake8-eyeo</a></li> | 104 <li><a href="https://hg.adblockplus.org/codingtools/file/tip/flake8-eyeo"> flake8-eyeo</a></li> |
73 <li><a href="https://pypi.python.org/pypi/flake8-docstrings">flake8-docstr ings</a> ({{python-flake8-docstring-exception with <code><fix>D1</fix></code> ig nored}})</li> | 105 <li><a href="https://pypi.python.org/pypi/flake8-docstrings">flake8-docstr ings</a> ({{python-flake8-docstring-exception with <code><fix>D1</fix></code> ig nored}})</li> |
74 <li><a href="https://pypi.python.org/pypi/pep8-naming">pep8-naming</a></li > | 106 <li><a href="https://pypi.python.org/pypi/pep8-naming">pep8-naming</a></li > |
75 </ul> | 107 </ul> |
76 </li> | 108 </li> |
77 <li>{{python-tests Write tests and have them run along <fix>flake8</fix> using <a href="https://pypi.python.org/pypi/tox"><fix>tox</fix></a>.}}</li> | 109 <li>{{python-tests Write tests and have them run along <fix>flake8</fix> using <a href="https://pypi.python.org/pypi/tox"><fix>tox</fix></a>.}}</li> |
(...skipping 18 matching lines...) Expand all Loading... | |
96 <ul> | 128 <ul> |
97 <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> |
98 </ul> | 130 </ul> |
99 | 131 |
100 <h2 id="puppet">{{s31 Puppet}}</h2> | 132 <h2 id="puppet">{{s31 Puppet}}</h2> |
101 <ul> | 133 <ul> |
102 <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> |
103 <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> |
104 <li>{{s34 Arrows should not be aligned.}}</li> | 136 <li>{{s34 Arrows should not be aligned.}}</li> |
105 </ul> | 137 </ul> |
OLD | NEW |