1SENSE(1)              User Contributed Perl Documentation             SENSE(1)
2
3
4

NAME

6       common::sense - save a tree AND a kitten, use common::sense!
7

SYNOPSIS

9          use common::sense;
10
11          # Supposed to be mostly the same, with much lower memory usage, as:
12
13          # 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

DESCRIPTION

26          XNothing is more fairly distributed than common sense: no one thinks
27          he needs more of it than he already has.X
28
29          X Rene Descartes
30
31       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
39       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
44       Two typical examples of how this philosophy is applied in practise is
45       the handling of uninitialised and malloc warnings:
46
47       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
52       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
58       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
64       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

RATIONALE

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
77           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
81       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
87              @{ $var->[0] }
88
89           Must be written like this (or similarly), when "use strict 'refs'"
90           is in scope, and $var can legally be "undef":
91
92              @{ $var->[0] || [] }
93
94           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
98              @{ defined $var->[0] ? $var->[0] : [] }
99
100           ... which nobody with a bit of common sense would consider writing:
101           clear code is clearly something else.
102
103           Curiously enough, sometimes perl is not so strict, as this works
104           even with "use strict" in scope:
105
106              for (@{ $var->[0] }) { ...
107
108           If that isn't hypocrisy! And all that from a mere program!
109
110       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
117           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
122           If your code isn't alive, it's dead, Jim - be an active maintainer.
123
124           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
130           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
136           "unicode_eval" doesn't add a new feature, it breaks an existing
137           function.
138
139       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
145           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
149           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
155           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
160           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
164           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
169           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
174           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
178           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
183              $fmt =~ s/([^\s\[]*)\[( [^\]]* )\]/\x0$1\x1$2\x0/xgo;
184
185           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
189       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
195           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
200           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
205       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
213           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
217           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

THERE IS NO 'no common::sense'!!!! !!!! !!

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

STABILITY AND FUTURE VERSIONS

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
233       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

WHAT OTHER PEOPLE HAD TO SAY ABOUT THIS MODULE

240       apeiron
241
242          "... wow"
243          "I hope common::sense is a joke."
244
245       crab
246
247          "i wonder how it would be if joerg schilling wrote perl modules."
248
249       Adam Kennedy
250
251          "Very interesting, efficient, and potentially something I'd use all the time."
252          [...]
253          "So no common::sense for me, alas."
254
255       H.Merijn Brand
256
257          "Just one more reason to drop JSON::XS from my distribution list"
258
259       Pista Palo
260
261          "Something in short supply these days..."
262
263       Steffen Schwigon
264
265          "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
270       BKB
271
272          "[Deleted - thanks to Steffen Schwigon for pointing out this review was
273          in error.]"
274
275       Somni
276
277          "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
281       Anonymous Monk
282
283          "You just gotta love this thing, its got META.json!!!"
284
285       dngor
286
287          "Heh.  '"<elmex at ta-sa.org>"'  The quotes are semantic
288          distancing from that e-mail address."
289
290       Jerad Pierce
291
292          "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
296       acme
297
298          "THERE IS NO 'no common::sense'!!!! !!!! !!"
299
300       apeiron (meta-comment about us commenting^Wquoting his comment)
301
302          "How about quoting this: get a clue, you fucktarded amoeba."
303
304       quanth
305
306          "common sense is beautiful, json::xs is fast, Anyevent, EV are fast and
307          furious. I love mlehmannware ;)"
308
309       apeiron
310
311          "... 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
315       apeiron (another meta-comment)
316
317          "apeiron wonders if his little informant is here to steal more quotes"
318
319       ew73
320
321          "... I never got past the SYNOPSIS before calling it shit."
322          [...]
323          How come no one ever quotes me. :("
324
325       chip (not willing to explain his cryptic questions about links in
326       Changes files)
327
328          "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

FREQUENTLY ASKED QUESTIONS

333       Or frequently-come-up confusions.
334
335       Is this module meant to be serious?
336           Yes, we would have put it under the "Acme::" namespace otherwise.
337
338       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
344           This was a failure.
345
346           But we hope the manpage still is somewhat entertaining even though
347           it explains boring rationale.
348
349       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
355           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
359       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
364       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
374           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
379           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
386       But many modules "use strict" or "use warnings", so the memory savings
387       do not apply?
388           I suddenly feel sad...
389
390           But yes, that's true. Fortunately "common::sense" still uses only a
391           miniscule amount of RAM.
392
393       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
399       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
404           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
408       But! But!
409           Yeah, we know.
410

AUTHOR

412        Marc Lehmann <schmorp@schmorp.de>
413        http://home.schmorp.de/
414
415        Robin Redeker, "<elmex at ta-sa.org>".
416
417
418
419perl v5.30.1                      2020-01-30                          SENSE(1)
Impressum