1NAME
2 common::sense - save a tree AND a kitten, use common::sense!
3
4SYNOPSIS
5 use common::sense;
6
7 # Supposed to be mostly the same, with much lower memory usage, as:
8
9 # use utf8;
10 # use strict qw(vars subs);
11 # use feature qw(say state switch);
12 # use feature qw(unicode_strings unicode_eval current_sub fc evalbytes);
13 # no feature qw(array_base);
14 # no warnings;
15 # use warnings qw(FATAL closed threads internal debugging pack
16 # portable prototype inplace io pipe unpack malloc
17 # deprecated glob digit printf layer
18 # reserved taint closure semicolon);
19 # no warnings qw(exec newline unopened);
20
21DESCRIPTION
22 “Nothing is more fairly distributed than common sense: no one thinks
23 he needs more of it than he already has.”
24
25 – René Descartes
26
27 This module implements some sane defaults for Perl programs, as defined
28 by two typical (or not so typical - use your common sense) specimens of
29 Perl coders. In fact, after working out details on which warnings and
30 strict modes to enable and make fatal, we found that we (and our code
31 written so far, and others) fully agree on every option, even though we
32 never used warnings before, so it seems this module indeed reflects a
33 "common" sense among some long-time Perl coders.
34
35 The basic philosophy behind the choices made in common::sense can be
36 summarised as: "enforcing strict policies to catch as many bugs as
37 possible, while at the same time, not limiting the expressive power
38 available to the programmer".
39
40 Two typical examples of how this philosophy is applied in practise is
41 the handling of uninitialised and malloc warnings:
42
43 *uninitialised*
44 "undef" is a well-defined feature of perl, and enabling warnings for
45 using it rarely catches any bugs, but considerably limits you in
46 what you can do, so uninitialised warnings are disabled.
47
48 *malloc*
49 Freeing something twice on the C level is a serious bug, usually
50 causing memory corruption. It often leads to side effects much later
51 in the program and there are no advantages to not reporting this, so
52 malloc warnings are fatal by default.
53
54 Unfortunately, there is no fine-grained warning control in perl, so
55 often whole groups of useful warnings had to be excluded because of a
56 single useless warning (for example, perl puts an arbitrary limit on the
57 length of text you can match with some regexes before emitting a
58 warning, making the whole "regexp" category useless).
59
60 What follows is a more thorough discussion of what this module does, and
61 why it does it, and what the advantages (and disadvantages) of this
62 approach are.
63
64RATIONALE
65 use utf8
66 While it's not common sense to write your programs in UTF-8, it's
67 quickly becoming the most common encoding, is the designated future
68 default encoding for perl sources, and the most convenient encoding
69 available (you can do really nice quoting tricks...). Experience has
70 shown that our programs were either all pure ascii or utf-8, both of
71 which will stay the same.
72
73 There are few drawbacks to enabling UTF-8 source code by default
74 (mainly some speed hits due to bugs in older versions of perl), so
75 this module enables UTF-8 source code encoding by default.
76
77 use strict qw(subs vars)
78 Using "use strict" is definitely common sense, but "use strict
79 'refs'" definitely overshoots its usefulness. After almost two
80 decades of Perl hacking, we decided that it does more harm than
81 being useful. Specifically, constructs like these:
82
83 @{ $var->[0] }
84
85 Must be written like this (or similarly), when "use strict 'refs'"
86 is in scope, and $var can legally be "undef":
87
88 @{ $var->[0] || [] }
89
90 This is annoying, and doesn't shield against obvious mistakes such
91 as using "", so one would even have to write (at least for the time
92 being):
93
94 @{ defined $var->[0] ? $var->[0] : [] }
95
96 ... which nobody with a bit of common sense would consider writing:
97 clear code is clearly something else.
98
99 Curiously enough, sometimes perl is not so strict, as this works
100 even with "use strict" in scope:
101
102 for (@{ $var->[0] }) { ...
103
104 If that isn't hypocrisy! And all that from a mere program!
105
106 use feature qw(say state given ...)
107 We found it annoying that we always have to enable extra features.
108 If something breaks because it didn't anticipate future changes, so
109 be it. 5.10 broke almost all our XS modules and nobody cared either
110 (or at least I know of nobody who really complained about gratuitous
111 changes - as opposed to bugs).
112
113 Few modules that are not actively maintained work with newer
114 versions of Perl, regardless of use feature or not, so a new major
115 perl release means changes to many modules - new keywords are just
116 the tip of the iceberg.
117
118 If your code isn't alive, it's dead, Jim - be an active maintainer.
119
120 But nobody forces you to use those extra features in modules meant
121 for older versions of perl - common::sense of course works there as
122 well. There is also an important other mode where having additional
123 features by default is useful: commandline hacks and internal use
124 scripts: See "much reduced typing", below.
125
126 There is one notable exception: "unicode_eval" is not enabled by
127 default. In our opinion, "use feature" had one main effect - newer
128 perl versions don't value backwards compatibility and the ability to
129 write modules for multiple perl versions much, after all, you can
130 use feature.
131
132 "unicode_eval" doesn't add a new feature, it breaks an existing
133 function.
134
135 no warnings, but a lot of new errors
136 Ah, the dreaded warnings. Even worse, the horribly dreaded "-w"
137 switch: Even though we don't care if other people use warnings (and
138 certainly there are useful ones), a lot of warnings simply go
139 against the spirit of Perl.
140
141 Most prominently, the warnings related to "undef". There is nothing
142 wrong with "undef": it has well-defined semantics, it is useful, and
143 spitting out warnings you never asked for is just evil.
144
145 The result was that every one of our modules did "no warnings" in
146 the past, to avoid somebody accidentally using and forcing his bad
147 standards on our code. Of course, this switched off all warnings,
148 even the useful ones. Not a good situation. Really, the "-w" switch
149 should only enable warnings for the main program only.
150
151 Funnily enough, perllexwarn explicitly mentions "-w" (and not in a
152 favourable way, calling it outright "wrong"), but standard
153 utilities, such as prove, or MakeMaker when running "make test",
154 still enable them blindly.
155
156 For version 2 of common::sense, we finally sat down a few hours and
157 went through *every single warning message*, identifiying -
158 according to common sense - all the useful ones.
159
160 This resulted in the rather impressive list in the SYNOPSIS. When we
161 weren't sure, we didn't include the warning, so the list might grow
162 in the future (we might have made a mistake, too, so the list might
163 shrink as well).
164
165 Note the presence of "FATAL" in the list: we do not think that the
166 conditions caught by these warnings are worthy of a warning, we
167 *insist* that they are worthy of *stopping* your program,
168 *instantly*. They are *bugs*!
169
170 Therefore we consider "common::sense" to be much stricter than "use
171 warnings", which is good if you are into strict things (we are not,
172 actually, but these things tend to be subjective).
173
174 After deciding on the list, we ran the module against all of our
175 code that uses "common::sense" (that is almost all of our code), and
176 found only one occurence where one of them caused a problem: one of
177 elmex's (unreleased) modules contained:
178
179 $fmt =~ s/([^\s\[]*)\[( [^\]]* )\]/\x0$1\x1$2\x0/xgo;
180
181 We quickly agreed that indeed the code should be changed, even
182 though it happened to do the right thing when the warning was
183 switched off.
184
185 much reduced typing
186 Especially with version 2.0 of common::sense, the amount of
187 boilerplate code you need to add to gte *this* policy is daunting.
188 Nobody would write this out in throwaway scripts, commandline hacks
189 or in quick internal-use scripts.
190
191 By using common::sense you get a defined set of policies (ours, but
192 maybe yours, too, if you accept them), and they are easy to apply to
193 your scripts: typing "use common::sense;" is even shorter than "use
194 warnings; use strict; use feature ...".
195
196 And you can immediately use the features of your installed perl,
197 which is more difficult in code you release, but not usually an
198 issue for internal-use code (downgrades of your production perl
199 should be rare, right?).
200
201 mucho reduced memory usage
202 Just using all those pragmas mentioned in the SYNOPSIS together
203 wastes <blink>*776 kilobytes*</blink> of precious memory in my perl,
204 for *every single perl process using our code*, which on our
205 machines, is a lot. In comparison, this module only uses *four*
206 kilobytes (I even had to write it out so it looks like more) of
207 memory on the same platform.
208
209 The money/time/effort/electricity invested in these gigabytes
210 (probably petabytes globally!) of wasted memory could easily save 42
211 trees, and a kitten!
212
213 Unfortunately, until everybods applies more common sense, there will
214 still often be modules that pull in the monster pragmas. But one can
215 hope...
216
217THERE IS NO 'no common::sense'!!!! !!!! !!
218 This module doesn't offer an unimport. First of all, it wastes even more
219 memory, second, and more importantly, who with even a bit of common
220 sense would want no common sense?
221
222STABILITY AND FUTURE VERSIONS
223 Future versions might change just about everything in this module. We
224 might test our modules and upload new ones working with newer versions
225 of this module, and leave you standing in the rain because we didn't
226 tell you. In fact, we did so when switching from 1.0 to 2.0, which
227 enabled gobs of warnings, and made them FATAL on top.
228
229 Maybe we will load some nifty modules that try to emulate "say" or so
230 with perls older than 5.10 (this module, of course, should work with
231 older perl versions - supporting 5.8 for example is just common sense at
232 this time. Maybe not in the future, but of course you can trust our
233 common sense to be consistent with, uhm, our opinion).
234
235WHAT OTHER PEOPLE HAD TO SAY ABOUT THIS MODULE
236 apeiron
237
238 "... wow"
239 "I hope common::sense is a joke."
240
241 crab
242
243 "i wonder how it would be if joerg schilling wrote perl modules."
244
245 Adam Kennedy
246
247 "Very interesting, efficient, and potentially something I'd use all the time."
248 [...]
249 "So no common::sense for me, alas."
250
251 H.Merijn Brand
252
253 "Just one more reason to drop JSON::XS from my distribution list"
254
255 Pista Palo
256
257 "Something in short supply these days..."
258
259 Steffen Schwigon
260
261 "This module is quite for sure *not* just a repetition of all the other
262 'use strict, use warnings'-approaches, and it's also not the opposite.
263 [...] And for its chosen middle-way it's also not the worst name ever.
264 And everything is documented."
265
266 BKB
267
268 "[Deleted - thanks to Steffen Schwigon for pointing out this review was
269 in error.]"
270
271 Somni
272
273 "the arrogance of the guy"
274 "I swear he tacked somenoe else's name onto the module
275 just so he could use the royal 'we' in the documentation"
276
277 Anonymous Monk
278
279 "You just gotta love this thing, its got META.json!!!"
280
281 dngor
282
283 "Heh. '"<elmex at ta-sa.org>"' The quotes are semantic
284 distancing from that e-mail address."
285
286 Jerad Pierce
287
288 "Awful name (not a proper pragma), and the SYNOPSIS doesn't tell you
289 anything either. Nor is it clear what features have to do with "common
290 sense" or discipline."
291
292 acme
293
294 "THERE IS NO 'no common::sense'!!!! !!!! !!"
295
296 apeiron (meta-comment about us commenting^Wquoting his comment)
297
298 "How about quoting this: get a clue, you fucktarded amoeba."
299
300 quanth
301
302 "common sense is beautiful, json::xs is fast, Anyevent, EV are fast and
303 furious. I love mlehmannware ;)"
304
305 apeiron
306
307 "... it's mlehmann's view of what common sense is. His view of common
308 sense is certainly uncommon, insofar as anyone with a clue disagrees
309 with him."
310
311 apeiron (another meta-comment)
312
313 "apeiron wonders if his little informant is here to steal more quotes"
314
315 ew73
316
317 "... I never got past the SYNOPSIS before calling it shit."
318 [...]
319 How come no one ever quotes me. :("
320
321 chip (not willing to explain his cryptic questions about links in
322 Changes files)
323
324 "I'm willing to ask the question I've asked. I'm not willing to go
325 through the whole dance you apparently have choreographed. Either
326 answer the completely obvious question, or tell me to fuck off again."
327
328FREQUENTLY ASKED QUESTIONS
329 Or frequently-come-up confusions.
330
331 Is this module meant to be serious?
332 Yes, we would have put it under the "Acme::" namespace otherwise.
333
334 But the manpage is written in a funny/stupid/... way?
335 This was meant to make it clear that our common sense is a
336 subjective thing and other people can use their own notions, taking
337 the steam out of anybody who might be offended (as some people are
338 always offended no matter what you do).
339
340 This was a failure.
341
342 But we hope the manpage still is somewhat entertaining even though
343 it explains boring rationale.
344
345 Why do you impose your conventions on my code?
346 For some reason people keep thinking that "common::sense" imposes
347 process-wide limits, even though the SYNOPSIS makes it clear that it
348 works like other similar modules - i.e. only within the scope that
349 "use"s them.
350
351 So, no, we don't - nobody is forced to use this module, and using a
352 module that relies on common::sense does not impose anything on you.
353
354 Why do you think only your notion of common::sense is valid?
355 Well, we don't, and have clearly written this in the documentation
356 to every single release. We were just faster than anybody else
357 w.r.t. to grabbing the namespace.
358
359 But everybody knows that you have to use strict and use warnings, why do
360 you disable them?
361 Well, we don't do this either - we selectively disagree with the
362 usefulness of some warnings over others. This module is aimed at
363 experienced Perl programmers, not people migrating from other
364 languages who might be surprised about stuff such as "undef". On the
365 other hand, this does not exclude the usefulness of this module for
366 total newbies, due to its strictness in enforcing policy, while at
367 the same time not limiting the expressive power of perl.
368
369 This module is considerably *more* strict than the canonical "use
370 strict; use warnings", as it makes all its warnings fatal in nature,
371 so you can not get away with as many things as with the canonical
372 approach.
373
374 This was not implemented in version 1.0 because of the daunting
375 number of warning categories and the difficulty in getting exactly
376 the set of warnings you wish (i.e. look at the SYNOPSIS in how
377 complicated it is to get a specific set of warnings - it is not
378 reasonable to put this into every module, the maintenance effort
379 would be enourmous).
380
381 But many modules "use strict" or "use warnings", so the memory savings
382 do not apply?
383 I suddenly feel sad...
384
385 But yes, that's true. Fortunately "common::sense" still uses only a
386 miniscule amount of RAM.
387
388 But it adds another dependency to your modules!
389 It's a fact, yeah. But it's trivial to install, most popular modules
390 have many more dependencies and we consider dependencies a good
391 thing - it leads to better APIs, more thought about interworking of
392 modules and so on.
393
394 Why do you use JSON and not YAML for your META.yml?
395 This is not true - YAML supports a large subset of JSON, and this
396 subset is what META.yml is written in, so it would be correct to say
397 "the META.yml is written in a common subset of YAML and JSON".
398
399 The META.yml follows the YAML, JSON and META.yml specifications, and
400 is correctly parsed by CPAN, so if you have trouble with it, the
401 problem is likely on your side.
402
403 But! But!
404 Yeah, we know.
405
406AUTHOR
407 Marc Lehmann <schmorp@schmorp.de>
408 http://home.schmorp.de/
409
410 Robin Redeker, "<elmex at ta-sa.org>".
411
412