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