-
Notifications
You must be signed in to change notification settings - Fork 1
Expand file tree
/
Copy pathCoding_style_guide.html
More file actions
235 lines (194 loc) · 7.86 KB
/
Coding_style_guide.html
File metadata and controls
235 lines (194 loc) · 7.86 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
<!DOCTYPE html>
<html lang="en">
<head>
<base href=".">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Coding Style Guide</title>
<link rel="stylesheet" href="assets/css/dark-frontend.css" type="text/css" title="dark">
<link rel="alternate stylesheet" href="assets/css/light-frontend.css" type="text/css" title="light">
<link rel="stylesheet" href="assets/css/bootstrap-toc.min.css" type="text/css">
<link rel="stylesheet" href="assets/css/jquery.mCustomScrollbar.min.css">
<link rel="stylesheet" href="assets/js/search/enable_search.css" type="text/css">
<link rel="stylesheet" href="assets/css/prism-tomorrow.css" type="text/css" title="dark">
<link rel="alternate stylesheet" href="assets/css/prism.css" type="text/css" title="light">
<script src="assets/js/mustache.min.js"></script>
<script src="assets/js/jquery.js"></script>
<script src="assets/js/bootstrap.js"></script>
<script src="assets/js/scrollspy.js"></script>
<script src="assets/js/typeahead.jquery.min.js"></script>
<script src="assets/js/search.js"></script>
<script src="assets/js/compare-versions.js"></script>
<script src="assets/js/jquery.mCustomScrollbar.concat.min.js"></script>
<script src="assets/js/bootstrap-toc.min.js"></script>
<script src="assets/js/jquery.touchSwipe.min.js"></script>
<script src="assets/js/anchor.min.js"></script>
<script src="assets/js/tag_filtering.js"></script>
<script src="assets/js/language_switching.js"></script>
<script src="assets/js/styleswitcher.js"></script>
<script src="assets/js/lines_around_headings.js"></script>
<script src="assets/js/prism-core.js"></script>
<script src="assets/js/prism-autoloader.js"></script>
<script src="assets/js/prism_autoloader_path_override.js"></script>
<script src="assets/js/trie.js"></script>
<link rel="shortcut icon" href="assets/images/favicon.png">
</head>
<body class="no-script
">
<script>
$('body').removeClass('no-script');
</script>
<nav class="navbar navbar-fixed-top navbar-default" id="topnav">
<div class="container-fluid">
<div class="navbar-right">
<a id="toc-toggle">
<span class="glyphicon glyphicon-menu-right"></span>
<span class="glyphicon glyphicon-menu-left"></span>
</a>
<button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#navbar-wrapper" aria-expanded="false">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<span title="light mode switch" class="glyphicon glyphicon-sunglasses pull-right" id="lightmode-icon"></span>
<form class="navbar-form pull-right" id="navbar-search-form">
<div class="form-group has-feedback">
<input type="text" class="form-control input-sm" name="search" id="sidenav-lookup-field" placeholder="search" disabled>
<span class="glyphicon glyphicon-search form-control-feedback" id="search-mgn-glass"></span>
</div>
</form>
</div>
<div class="navbar-header">
<a id="sidenav-toggle">
<span class="glyphicon glyphicon-menu-right"></span>
<span class="glyphicon glyphicon-menu-left"></span>
</a>
<a id="home-link" href="index.html" class="hotdoc-navbar-brand">
<img src="assets/images/pitivi.svg" alt="Home">
</a>
</div>
<div class="navbar-collapse collapse" id="navbar-wrapper">
<ul class="nav navbar-nav" id="menu">
</ul>
<div class="hidden-xs hidden-sm navbar-text navbar-center">
<p><b>The Pitivi Developer Documentation</b></p>
</div>
</div>
</div>
</nav>
<main>
<div data-extension="core" data-hotdoc-in-toplevel="True" data-hotdoc-project="Pitivi" data-hotdoc-ref="Coding_style_guide.html" class="page_container" id="page-wrapper">
<script src="assets/js/utils.js"></script>
<div class="panel panel-collapse oc-collapsed" id="sidenav" data-hotdoc-role="navigation">
<script src="assets/js/full-width.js"></script>
<div id="sitenav-wrapper">
<iframe src="hotdoc-sitemap.html" id="sitenav-frame"></iframe>
</div>
</div>
<div id="body">
<div id="main">
<div id="page-description" data-hotdoc-role="main">
<h1 id="coding-style-guide">Coding Style Guide</h1>
<p>The code must be easy to understand, so it should look consistent.</p>
<p>When entering the development environment, a <a href="https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks">git pre-commit
hook</a> is set
up on your local repo. When you create a commit, the
<a href="https://gitlab.gnome.org/GNOME/pitivi/blob/master/pre-commit.hook">hook</a>
runs the <code>pre-commit</code> tool which:</p>
<ul>
<li>
<p>performs some <a href="https://gitlab.gnome.org/GNOME/pitivi/blob/master/.pre-commit-config.yaml">lightweight
checks</a></p>
</li>
<li>
<p>runs <a href="https://gitlab.com/pycqa/flake8">flake8</a> to check the code style</p>
</li>
<li>
<p>runs
<a href="https://gitlab.gnome.org/GNOME/pitivi/blob/master/pylint.rc">pylint</a> in
the sandbox to check for all kinds of errors.</p>
</li>
</ul>
<p>We rely on the <a href="https://www.python.org/dev/peps/pep-0008/">Python Style Guide PEP-8</a></p>
<h2 id="line-length">Line length</h2>
<p>When deciding whether or not you should split your line when it exceeds
79 characters, ask yourself: "Does it truly improve legibility?"</p>
<p>What this translates to is:</p>
<ul>
<li>
<p>Avoid having very long lines.</p>
</li>
<li>
<p>When the contents only slightly exceeds the 80 chars limit,
consider keeping it on one line. Otherwise it just hurts legibility and
gives a weird "shape" to the code.</p>
</li>
</ul>
<h2 id="names">Names</h2>
<p>The function names, method names and other class attributes should be
small_caps_with_underscore. For example:</p>
<pre><code class="language-python">def some_function():
return ""
class MyClass:
def a_really_important_method(self):
self.do_something()
@property
def water_level(self):
"""The level of the water in meters."""
return self.__water_level
</code></pre>
<p>To illustrate how private a method or other class field is, prepend
one or two underscores:</p>
<pre><code class="language-python"> class MyClass:
def public_method(self):
...
def _protected_method(self):
...
def __private_method(self):
...
</code></pre>
<p>Unused arguments in methods should be prefixed with <code>unused_</code>.
The most common place where this would happen is in callbacks from
gobject signals. For example, below we don't use the second argument,
but we do use <code>pad</code>.</p>
<pre><code class="language-python"> def __pad_added_cb(self, unused_element, pad):
self.do_something_with(pad)
</code></pre>
<p>The name of a callback method should:</p>
<ul>
<li>be prepended with two underscores since it's private</li>
<li>be appended with <code>cb</code>
</li>
</ul>
<pre><code class="language-python"> class MyClass:
def some_method(self):
self.someobject.connect("event", self.__some_object_event_cb)
def __some_object_event_cb(self, object, arg):
print "our callback was called"
</code></pre>
<h2 id="docstrings">Docstrings</h2>
<p>We follow the <a href="https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings">Google Python Style Guide</a>
for docstrings.</p>
</div>
</div>
<div id="search_results">
<p>The results of the search are</p>
</div>
<div id="footer">
</div>
</div>
<div id="toc-column">
<div class="edit-button">
<a href="https://gitlab.gnome.org/GNOME/pitivi/edit/master/docs/Coding_style_guide.md" data-hotdoc-role="edit-button">Edit on GitLab</a>
</div>
<div id="toc-wrapper">
<nav id="toc"></nav>
</div>
</div>
</div>
</main>
<script src="assets/js/navbar_offset_scroller.js"></script>
</body>
</html>