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