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