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          #                 prototype inplace io pipe unpack malloc glob
21          #                 digit printf layer reserved taint closure semicolon);
22          # no warnings qw(exec newline unopened);
23

DESCRIPTION

25          “Nothing is more fairly distributed than common sense: no one thinks
26          he needs more of it than he already has.”
27
28          – René Descartes
29
30       This module implements some sane defaults for Perl programs, as defined
31       by two typical (or not so typical - use your common sense) specimens of
32       Perl coders. In fact, after working out details on which warnings and
33       strict modes to enable and make fatal, we found that we (and our code
34       written so far, and others) fully agree on every option, even though we
35       never used warnings before, so it seems this module indeed reflects a
36       "common" sense among some long-time Perl coders.
37
38       The basic philosophy behind the choices made in common::sense can be
39       summarised as: "enforcing strict policies to catch as many bugs as
40       possible, while at the same time, not limiting the expressive power
41       available to the programmer".
42
43       Two typical examples of how this philosophy is applied in practise is
44       the handling of uninitialised and malloc warnings:
45
46       uninitialised
47           "undef" is a well-defined feature of perl, and enabling warnings
48           for using it rarely catches any bugs, but considerably limits you
49           in what you can do, so uninitialised warnings are disabled.
50
51       malloc
52           Freeing something twice on the C level is a serious bug, usually
53           causing memory corruption. It often leads to side effects much
54           later in the program and there are no advantages to not reporting
55           this, so malloc warnings are fatal by default.
56
57       Unfortunately, there is no fine-grained warning control in perl, so
58       often whole groups of useful warnings had to be excluded because of a
59       single useless warning (for example, perl puts an arbitrary limit on
60       the length of text you can match with some regexes before emitting a
61       warning, making the whole "regexp" category useless).
62
63       What follows is a more thorough discussion of what this module does,
64       and why it does it, and what the advantages (and disadvantages) of this
65       approach are.
66

RATIONALE

68       use utf8
69           While it's not common sense to write your programs in UTF-8, it's
70           quickly becoming the most common encoding, is the designated future
71           default encoding for perl sources, and the most convenient encoding
72           available (you can do really nice quoting tricks...). Experience
73           has shown that our programs were either all pure ascii or utf-8,
74           both of which will stay the same.
75
76           There are few drawbacks to enabling UTF-8 source code by default
77           (mainly some speed hits due to bugs in older versions of perl), so
78           this module enables UTF-8 source code encoding by default.
79
80       use strict qw(subs vars)
81           Using "use strict" is definitely common sense, but use strict
82           'refs' definitely overshoots its usefulness. After almost two
83           decades of Perl hacking, we decided that it does more harm than
84           being useful. Specifically, constructs like these:
85
86              @{ $var->[0] }
87
88           Must be written like this (or similarly), when "use strict 'refs'"
89           is in scope, and $var can legally be "undef":
90
91              @{ $var->[0] || [] }
92
93           This is annoying, and doesn't shield against obvious mistakes such
94           as using "", so one would even have to write (at least for the time
95           being):
96
97              @{ defined $var->[0] ? $var->[0] : [] }
98
99           ... which nobody with a bit of common sense would consider writing:
100           clear code is clearly something else.
101
102           Curiously enough, sometimes perl is not so strict, as this works
103           even with "use strict" in scope:
104
105              for (@{ $var->[0] }) { ...
106
107           If that isn't hypocrisy! And all that from a mere program!
108
109       use feature qw(say state given ...)
110           We found it annoying that we always have to enable extra features.
111           If something breaks because it didn't anticipate future changes, so
112           be it. 5.10 broke almost all our XS modules and nobody cared either
113           (or at least I know of nobody who really complained about
114           gratuitous changes - as opposed to bugs).
115
116           Few modules that are not actively maintained work with newer
117           versions of Perl, regardless of use feature or not, so a new major
118           perl release means changes to many modules - new keywords are just
119           the tip of the iceberg.
120
121           If your code isn't alive, it's dead, Jim - be an active maintainer.
122
123           But nobody forces you to use those extra features in modules meant
124           for older versions of perl - common::sense of course works there as
125           well.  There is also an important other mode where having
126           additional features by default is useful: commandline hacks and
127           internal use scripts: See "much reduced typing", below.
128
129           There is one notable exception: "unicode_eval" is not enabled by
130           default. In our opinion, "use feature" had one main effect - newer
131           perl versions don't value backwards compatibility and the ability
132           to write modules for multiple perl versions much, after all, you
133           can use feature.
134
135           "unicode_eval" doesn't add a new feature, it breaks an existing
136           function.
137
138       no warnings, but a lot of new errors
139           Ah, the dreaded warnings. Even worse, the horribly dreaded "-w"
140           switch: Even though we don't care if other people use warnings (and
141           certainly there are useful ones), a lot of warnings simply go
142           against the spirit of Perl.
143
144           Most prominently, the warnings related to "undef". There is nothing
145           wrong with "undef": it has well-defined semantics, it is useful,
146           and spitting out warnings you never asked for is just evil.
147
148           The result was that every one of our modules did "no warnings" in
149           the past, to avoid somebody accidentally using and forcing his bad
150           standards on our code. Of course, this switched off all warnings,
151           even the useful ones. Not a good situation. Really, the "-w" switch
152           should only enable warnings for the main program only.
153
154           Funnily enough, perllexwarn explicitly mentions "-w" (and not in a
155           favourable way, calling it outright "wrong"), but standard
156           utilities, such as prove, or MakeMaker when running "make test",
157           still enable them blindly.
158
159           For version 2 of common::sense, we finally sat down a few hours and
160           went through every single warning message, identifying - according
161           to common sense - all the useful ones.
162
163           This resulted in the rather impressive list in the SYNOPSIS. When
164           we weren't sure, we didn't include the warning, so the list might
165           grow in the future (we might have made a mistake, too, so the list
166           might shrink as well).
167
168           Note the presence of "FATAL" in the list: we do not think that the
169           conditions caught by these warnings are worthy of a warning, we
170           insist that they are worthy of stopping your program, instantly.
171           They are bugs!
172
173           Therefore we consider "common::sense" to be much stricter than "use
174           warnings", which is good if you are into strict things (we are not,
175           actually, but these things tend to be subjective).
176
177           After deciding on the list, we ran the module against all of our
178           code that uses "common::sense" (that is almost all of our code),
179           and found only one occurrence where one of them caused a problem:
180           one of elmex's (unreleased) modules contained:
181
182              $fmt =~ s/([^\s\[]*)\[( [^\]]* )\]/\x0$1\x1$2\x0/xgo;
183
184           We quickly agreed that indeed the code should be changed, even
185           though it happened to do the right thing when the warning was
186           switched off.
187
188       much reduced typing
189           Especially with version 2.0 of common::sense, the amount of
190           boilerplate code you need to add to get this policy is daunting.
191           Nobody would write this out in throwaway scripts, commandline hacks
192           or in quick internal-use scripts.
193
194           By using common::sense you get a defined set of policies (ours, but
195           maybe yours, too, if you accept them), and they are easy to apply
196           to your scripts: typing "use common::sense;" is even shorter than
197           "use warnings; use strict; use feature ...".
198
199           And you can immediately use the features of your installed perl,
200           which is more difficult in code you release, but not usually an
201           issue for internal-use code (downgrades of your production perl
202           should be rare, right?).
203
204       mucho reduced memory usage
205           Just using all those pragmas mentioned in the SYNOPSIS together
206           wastes <blink>776 kilobytes</blink> of precious memory in my perl,
207           for every single perl process using our code, which on our
208           machines, is a lot. In comparison, this module only uses four
209           kilobytes (I even had to write it out so it looks like more) of
210           memory on the same platform.
211
212           The money/time/effort/electricity invested in these gigabytes
213           (probably petabytes globally!) of wasted memory could easily save
214           42 trees, and a kitten!
215
216           Unfortunately, until everybody applies more common sense, there
217           will still often be modules that pull in the monster pragmas. But
218           one can hope...
219

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

221       This module doesn't offer an unimport. First of all, it wastes even
222       more memory, second, and more importantly, who with even a bit of
223       common sense would want no common sense?
224

STABILITY AND FUTURE VERSIONS

226       Future versions might change just about everything in this module. We
227       might test our modules and upload new ones working with newer versions
228       of this module, and leave you standing in the rain because we didn't
229       tell you. In fact, we did so when switching from 1.0 to 2.0, which
230       enabled gobs of warnings, and made them FATAL on top.
231
232       Maybe we will load some nifty modules that try to emulate "say" or so
233       with perls older than 5.10 (this module, of course, should work with
234       older perl versions - supporting 5.8 for example is just common sense
235       at this time. Maybe not in the future, but of course you can trust our
236       common sense to be consistent with, uhm, our opinion).
237

WHAT OTHER PEOPLE HAD TO SAY ABOUT THIS MODULE

239       apeiron
240
241          "... wow"
242          "I hope common::sense is a joke."
243
244       crab
245
246          "i wonder how it would be if joerg schilling wrote perl modules."
247
248       Adam Kennedy
249
250          "Very interesting, efficient, and potentially something I'd use all the time."
251          [...]
252          "So no common::sense for me, alas."
253
254       H.Merijn Brand
255
256          "Just one more reason to drop JSON::XS from my distribution list"
257
258       Pista Palo
259
260          "Something in short supply these days..."
261
262       Steffen Schwigon
263
264          "This module is quite for sure *not* just a repetition of all the other
265          'use strict, use warnings'-approaches, and it's also not the opposite.
266          [...] And for its chosen middle-way it's also not the worst name ever.
267          And everything is documented."
268
269       BKB
270
271          "[Deleted - thanks to Steffen Schwigon for pointing out this review was
272          in error.]"
273
274       Somni
275
276          "the arrogance of the guy"
277          "I swear he tacked somenoe else's name onto the module
278          just so he could use the royal 'we' in the documentation"
279
280       Anonymous Monk
281
282          "You just gotta love this thing, its got META.json!!!"
283
284       dngor
285
286          "Heh.  '"<elmex at ta-sa.org>"'  The quotes are semantic
287          distancing from that e-mail address."
288
289       Jerad Pierce
290
291          "Awful name (not a proper pragma), and the SYNOPSIS doesn't tell you
292          anything either. Nor is it clear what features have to do with "common
293          sense" or discipline."
294
295       acme
296
297          "THERE IS NO 'no common::sense'!!!! !!!! !!"
298
299       apeiron (meta-comment about us commenting^Wquoting his comment)
300
301          "How about quoting this: get a clue, you fucktarded amoeba."
302
303       quanth
304
305          "common sense is beautiful, json::xs is fast, Anyevent, EV are fast and
306          furious. I love mlehmannware ;)"
307
308       apeiron
309
310          "... it's mlehmann's view of what common sense is. His view of common
311          sense is certainly uncommon, insofar as anyone with a clue disagrees
312          with him."
313
314       apeiron (another meta-comment)
315
316          "apeiron wonders if his little informant is here to steal more quotes"
317
318       ew73
319
320          "... I never got past the SYNOPSIS before calling it shit."
321          [...]
322          How come no one ever quotes me. :("
323
324       chip (not willing to explain his cryptic questions about links in
325       Changes files)
326
327          "I'm willing to ask the question I've asked. I'm not willing to go
328          through the whole dance you apparently have choreographed. Either
329          answer the completely obvious question, or tell me to fuck off again."
330

FREQUENTLY ASKED QUESTIONS

332       Or frequently-come-up confusions.
333
334       Is this module meant to be serious?
335           Yes, we would have put it under the "Acme::" namespace otherwise.
336
337       But the manpage is written in a funny/stupid/... way?
338           This was meant to make it clear that our common sense is a
339           subjective thing and other people can use their own notions, taking
340           the steam out of anybody who might be offended (as some people are
341           always offended no matter what you do).
342
343           This was a failure.
344
345           But we hope the manpage still is somewhat entertaining even though
346           it explains boring rationale.
347
348       Why do you impose your conventions on my code?
349           For some reason people keep thinking that "common::sense" imposes
350           process-wide limits, even though the SYNOPSIS makes it clear that
351           it works like other similar modules - i.e. only within the scope
352           that "use"s them.
353
354           So, no, we don't - nobody is forced to use this module, and using a
355           module that relies on common::sense does not impose anything on
356           you.
357
358       Why do you think only your notion of common::sense is valid?
359           Well, we don't, and have clearly written this in the documentation
360           to every single release. We were just faster than anybody else
361           w.r.t. to grabbing the namespace.
362
363       But everybody knows that you have to use strict and use warnings, why
364       do you disable them?
365           Well, we don't do this either - we selectively disagree with the
366           usefulness of some warnings over others. This module is aimed at
367           experienced Perl programmers, not people migrating from other
368           languages who might be surprised about stuff such as "undef". On
369           the other hand, this does not exclude the usefulness of this module
370           for total newbies, due to its strictness in enforcing policy, while
371           at the same time not limiting the expressive power of perl.
372
373           This module is considerably more strict than the canonical "use
374           strict; use warnings", as it makes all its warnings fatal in
375           nature, so you can not get away with as many things as with the
376           canonical approach.
377
378           This was not implemented in version 1.0 because of the daunting
379           number of warning categories and the difficulty in getting exactly
380           the set of warnings you wish (i.e. look at the SYNOPSIS in how
381           complicated it is to get a specific set of warnings - it is not
382           reasonable to put this into every module, the maintenance effort
383           would be enormous).
384
385       But many modules "use strict" or "use warnings", so the memory savings
386       do not apply?
387           I suddenly feel sad...
388
389           But yes, that's true. Fortunately "common::sense" still uses only a
390           miniscule amount of RAM.
391
392       But it adds another dependency to your modules!
393           It's a fact, yeah. But it's trivial to install, most popular
394           modules have many more dependencies. And we consider dependencies a
395           good thing - it leads to better APIs, more thought about
396           interworking of modules and so on.
397
398       Why do you use JSON and not YAML for your META.yml?
399           This is not true - YAML supports a large subset of JSON, and this
400           subset is what META.yml is written in, so it would be correct to
401           say "the META.yml is written in a common subset of YAML and JSON".
402
403           The META.yml follows the YAML, JSON and META.yml specifications,
404           and is correctly parsed by CPAN, so if you have trouble with it,
405           the problem is likely on your side.
406
407       But! But!
408           Yeah, we know.
409

AUTHOR

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