ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/common-sense/sense.pm
(Generate patch)

Comparing common-sense/sense.pm (file contents):
Revision 1.21 by root, Fri Oct 30 02:58:05 2009 UTC vs.
Revision 1.22 by root, Wed Nov 4 11:04:25 2009 UTC

… …
25modes to enable and make fatal, we found that we (and our code written so 25modes to enable and make fatal, we found that we (and our code written so
26far, and others) fully agree on every option, even though we never used 26far, and others) fully agree on every option, even though we never used
27warnings before, so it seems this module indeed reflects a "common" sense 27warnings before, so it seems this module indeed reflects a "common" sense
28among some long-time Perl coders. 28among some long-time Perl coders.
29 29
30The basic philosophy behind the choices made in common::sense can be
31summarised as: "enforcing strict policies to catch as many bugs as
32possible, while at the same time, not limiting the expressive power
33available to the programmer".
34
35Two typical examples of this philosophy are uninitialised and malloc
36warnings:
37
38C<undef> is a well-defined feature of perl, and enabling warnings for
39using it rarely catches any bugs, but considerably limits you in what you
40can do, so uninitialised warnings are disabled.
41
42Freeing something twice on the C level is a serious bug, usually causing
43memory corruption. It often leads to side effects much later in the
44program and there are no advantages to not reporting this, so malloc
45warnings are fatal by default.
46
47What follows is a more thorough discussion of what this module does,
48and why it does it, and what the advantages (and disadvantages) of this
49approach are.
50
30=over 4 51=over 4
31 52
32=item use strict qw(subs vars) 53=item use strict qw(subs vars)
33 54
34Using C<use strict> is definitely common sense, but C<use strict 55Using C<use strict> is definitely common sense, but C<use strict
… …
72Perl, regardless of use feature or not, so a new major perl release means 93Perl, regardless of use feature or not, so a new major perl release means
73changes to many modules - new keywords are just the tip of the iceberg. 94changes to many modules - new keywords are just the tip of the iceberg.
74 95
75If your code isn't alive, it's dead, Jim - be an active maintainer. 96If your code isn't alive, it's dead, Jim - be an active maintainer.
76 97
98But nobody forces you to use those extra features in modules meant for
99older versions of perl - common::sense of course works there as well.
100There is also an important other mode where having additional features by
101default is useful: commandline hacks and internal use scripts: See "much
102reduced typing", below.
103
77 104
78=item no warnings, but a lot of new errors 105=item no warnings, but a lot of new errors
79 106
80Ah, the dreaded warnings. Even worse, the horribly dreaded C<-w> 107Ah, the dreaded warnings. Even worse, the horribly dreaded C<-w>
81switch: Even though we don't care if other people use warnings (and 108switch: Even though we don't care if other people use warnings (and
… …
124 151
125We quickly agreed that indeed the code should be changed, even though it 152We quickly agreed that indeed the code should be changed, even though it
126happened to do the right thing when the warning was switched off. 153happened to do the right thing when the warning was switched off.
127 154
128 155
156=item much reduced typing
157
158Especially with version 2.0 of common::sense, the amount of boilerplate
159code you need to add to gte I<this> policy is daunting. Nobody would write
160this out in throwaway scripts, commandline hacks or in quick internal-use
161scripts.
162
163By using common::sense you get a defined set of policies (ours, but maybe
164yours, too, if you accept them), and they are easy to apply to your
165scripts: typing C<use common::sense;> is even shorter than C<use warnings;
166use strict; use feature ...>.
167
168And you can immediately use the features of your installed perl, which
169is more difficult in code you release, but not usually an issue for
170internal-use code (downgrades of your production perl should be rare,
171right?).
172
173
129=item mucho reduced memory usage 174=item mucho reduced memory usage
130 175
131Just using all those pragmas mentioned in the SYNOPSIS together wastes 176Just using all those pragmas mentioned in the SYNOPSIS together wastes
132<blink>I<< B<776> kilobytes >></blink> of precious memory in my perl, for 177<blink>I<< B<776> kilobytes >></blink> of precious memory in my perl, for
133I<every single perl process using our code>, which on our machines, is a 178I<every single perl process using our code>, which on our machines, is a
… …
143 188
144=cut 189=cut
145 190
146package common::sense; 191package common::sense;
147 192
148our $VERSION = '2.01'; 193our $VERSION = '2.02';
149 194
150# paste this into perl to find bitmask 195# paste this into perl to find bitmask
151 196
152# no warnings; 197# no warnings;
153# use warnings qw(FATAL closed threads internal debugging pack substr malloc unopened portable prototype 198# use warnings qw(FATAL closed threads internal debugging pack substr malloc unopened portable prototype
… …
303why do you disable them? 348why do you disable them?
304 349
305Well, we don't do this either - we selectively disagree with the 350Well, we don't do this either - we selectively disagree with the
306usefulness of some warnings over others. This module is aimed at 351usefulness of some warnings over others. This module is aimed at
307experienced Perl programmers, not people migrating from other languages 352experienced Perl programmers, not people migrating from other languages
308who might be surprised about stuff such as C<undef>. 353who might be surprised about stuff such as C<undef>. On the other hand,
354this does not exclude the usefulness of this module for total newbies, due
355to its strictness in enforcing policy, while at the same time not limiting
356the expresive power of perl.
309 357
310In fact, this module is considerably I<more> strict than the canonical 358This module is considerably I<more> strict than the canonical C<use
311C<use strict; use warnings>, as it makes all warnings fatal in nature, so 359strict; use warnings>, as it makes all its warnings fatal in nature, so
312you can get away with as many things as with the canonical approach. 360you can not get away with as many things as with the canonical approach.
313 361
314This was not implemented in version 1.0 because of the daunting number 362This was not implemented in version 1.0 because of the daunting number
315of warning categories and the difficulty in getting exactly the set of 363of warning categories and the difficulty in getting exactly the set of
316warnings you wish (i.e. look at the SYNOPSIS in how complicated it is to 364warnings you wish (i.e. look at the SYNOPSIS in how complicated it is to
317get a specific set of warnings - it is not reasonable to put this into 365get a specific set of warnings - it is not reasonable to put this into
… …
330It's a fact, yeah. But it's trivial to install, most popular modules have 378It's a fact, yeah. But it's trivial to install, most popular modules have
331many more dependencies and we consider dependencies a good thing - it 379many more dependencies and we consider dependencies a good thing - it
332leads to better APIs, more thought about interworking of modules and so 380leads to better APIs, more thought about interworking of modules and so
333on. 381on.
334 382
383=item Why do you use JSON and not YAML for your META.yml?
384
385This is not true - YAML supports a large subset of JSON, and this subset
386is what META.yml is written in, so it would be correct to say "the
387META.yml is written in a common subset of YAML and JSON".
388
389The META.yml follows the YAML, JSON and META.yml specifications, and is
390correctly parsed by CPAN, so if you have trouble with it, the problem is
391likely on your side.
392
335=item But! But! 393=item But! But!
336 394
337Yeah, we know. 395Yeah, we know.
338 396
339=back 397=back

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines