forked from GetmeUK/ContentTools
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathindex.html
More file actions
321 lines (265 loc) · 13.8 KB
/
Copy pathindex.html
File metadata and controls
321 lines (265 loc) · 13.8 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
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
<!DOCTYPE HTML>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>ContentTools sandbox</title>
<link rel="stylesheet" type="text/css" href="sandbox.css">
<link rel="stylesheet" type="text/css" href="../build/content-tools.min.css">
</head>
<body>
<article class="article">
<section class="article__content" >
<h1 data-fixture data-name="article-title">
5 rules for naming variables
</h1>
<div data-editable data-name="article">
<p class="article__by-line">
by <b>Anthony Blackshaw</b> · 18th January 2015
</p>
<blockquote>
Writing poor quality code will dramatically reduce the time
you get to spend doing things you love, if you’re lucky
enough to leave a project shortly after such a contribution
everyone who subsequently has to work with your code will
think you an arsehole.
</blockquote>
<img src="image.png" alt="Example of bad variable names">
<p class="article__caption">
<b>Above:</b> This example is code found in
a live and commercial project. Clearly the developer thought
<b>user.n5</b> would still clearly point to the 5th
character of a the user's name when used elsewhere.
</p>
<p>
The names we devise for folders, files, variables,
functions, classes and any other user definable construct
will (for the most part) determine how easily someone else
can read and understand what we have written.
</p>
<p>
To avoid repetition in the remainder of this section we use
the term variable to cover folders, files, variables,
functions, and classes.
</p>
<iframe
width="400"
height="300"
src="https://www.youtube.com/embed/I9jSKFk5Zp0"
frameborder="0"
></iframe>
<h2>Be descriptive and concise</h2>
<p>
It’s the most obvious naming rule of all but it’s also
perhaps the most difficult. In my younger years I would
often use very descriptive names, I pulled the following
doozy from the archives:
</p>
<pre class="example example--bad">design_inspiration_competition_promotion_code_list</pre>
<p>
At a whopping 50 characters it can hardly be described as
nondescript, however I’m sure anyone who came after would
have cursed me for using such a long name. A far better name
for my list of promotion codes would have been:
</p>
<pre class="example example--good">promotion_codes</pre>
<p>
Or possibly:
</p>
<pre class="example example--good">promo_codes</pre>
<p>
However care should be taken when using abbreviations or
acronyms. Only use an abbreviated term if it is well known
and/or its use is standard practice (e.g db, id, url, etc.)
If you’re not sure if an abbreviated form of a term is well
known err on the side of caution and don’t abbreviate:
</p>
<pre class="example example--bad">p_codes</pre>
<pre class="example example--bad">pcs</pre>
<p>
There is one exception to this rule - list or dictionary
comprehensions (if you’re not familiar with list
comprehension look it up). Using a single letter
abbreviation in this case is preferential to a more
descriptive name, for example:
</p>
<pre class="example example--bad">[employee.name for employee in employees \
if employee.role == “developer”]</pre>
<pre class="example example--good">[e.name for e in employees if e.role == “developers”]</pre>
<h2>Be conscious of scope</h2>
<p>
In the first rule we reduced a very descriptive term to a
more concise version promotion_codes. So why not reduce it
further (e.g codes) and why was it acceptable to reduce it
at all? The answer lies in scope.
</p>
<p>
The scope in which you declare a variable determines how
much information must be included in the name. For example a
variable declared in the settings module for a project will
infer little information from its scope and therefore needs
to be more descriptive.
</p>
<pre class="example example--bad">settings.username = 'foo'</pre>
<pre class="example example--good">settings.db_username = 'foo'</pre>
<p>
Now consider the scope when the same variable is used in a
function:
</p>
<pre class="example example--bad">def connect_to_db(db_username, db_password):</pre>
<pre class="example example--good">def connect_to_db(username, password):</pre>
<p>
The purpose of our function is to connect to the database
and therefore we can infer that the supplied username and
password are for this purpose and there’s no need to include
db in the variable names.
</p>
<p>
On occasion it may be necessary to use more descriptive
names to avoid a naming conflict within the same scope.
Consider our first example where we declared a username for
the database in the settings file, what if the project uses
multiple databases?
</p>
<pre class="example example--good">settings.redis_db_username = ‘foo’
...
settings.mysql_db_username = ‘bar’
...</pre>
<p>
Here the name of the database application is used to
namespace the variables and avoid any conflict whilst
keeping the names themselves as concise as possible.
</p>
<h2>Pluralize when naming collections</h2>
<p>
Harking back again to my youth there was a time where I
would have avoided using plurals at all costs, instead
opting to follow the convention of appending <i>_list</i> to
any variable associated with a collection of items. With the
benefit of time I’ve come to prefer variable names that
sound natural.
</p>
<pre class="example">for colour in colour_list:
...
for colour in colours:
...</pre>
<p>
I’ve refrained from marking either example as good or bad as
they are both acceptable in my eyes, however colours would
be the preferred term purely on the base it is the most
concise and natural sounding.
</p>
<p>
Advocates for using <i>_list</i> often argue that it reduces
common spelling mistakes with words like category/categories
and hero/heroes. I would counter that in the same way I will
grammar and spell check this document before asking you to
read it you should take the same pride in the code you
write.
</p>
<h2>Read your code out loud</h2>
<p>
If you can read a line of code and comprehend it in one
that’s a good indication that it’s well written using good
variable names. If on the other hand if jars or you find
yourself re-reading it multiple times before it makes sense
then there’s room for improvement.
</p>
<p>
Reading your code out loud (or in your head if you’re
attracting too much attention) is a sure fire way to spot
badly named variables.
</p>
<h2>Above all else be consistent</h2>
<p>
When you work with old or externally written code chances
are there will be difference in the rules the author(s) used
when coming up with variable names. Unless you’re going to
rewrite and maintain all the code in future do not break
from the existing naming conventions.
</p>
<p>
If they prefix numbers with num_ or append _list to lists
then follow suite, whilst conventional wisdom tells us two
wrongs don’t make a right, mixing styles within a project
will only make things worse.
</p>
<table>
<thead>
<tr>
<th>Position</th>
<th>Name</th>
</tr>
</thead>
<tbody>
<tr>
<td>Chair</td>
<td>Helen Troughton</td>
</tr>
<tr>
<td>Vice-chair</td>
<td>Sarah Stone</td>
</tr>
<tr>
<td>Secretary</td>
<td>Bridget Brickley</td>
</tr>
<tr>
<td>Treasurer</td>
<td>Sarahann Holmes</td>
</tr>
<tr>
<td>Publicity officer</td>
<td>Zillah Cimmock</td>
</tr>
</tbody>
</table>
<p>
If you have to work with code that has a mixture of styles
or no clear style at all then I refer you to my opening
statement.
</p>
<h2>Further reading...</h2>
<ul>
<li>
Code complete 2 <i>(by Steve McConnell)</i>
</li>
<li>
The Art of Computer Programming: Volumes 1-4a
<i>(by Donald E. Knuth)</i>
</li>
</ul>
</div>
</section>
<aside class="article__related">
<div
data-editable
data-name="author"
class="[ article__author ] [ author ] [ editable ]"
>
<h3 class="author__about">About the author</h3>
<img
src="author-pic.jpg"
alt="Anthony Blackshaw"
width="80"
class="[ author__pic ] [ align-right ]"
>
<p class="author__bio">
Anthony Blackshaw is a co-founder of Getme, an
employee owned company with a focus on web tech. He
enjoys writing and talking about tech, especially
code and the occasional Montecristo No.2s.
</p>
</div>
<div
data-editable
data-name="learn-more"
class="[ article__learn-more ] [ learn-more ] [ editable ]"
>
<h3 data-ce-tag="static">Want to learn more?</h3>
</div>
</aside>
</article>
<script type="text/javascript" src="../build/content-tools.js"></script>
<script type="text/javascript" src="sandbox.js"></script>
</body>
</html>