1 | =head1 NAME
|
---|
2 |
|
---|
3 | perlmodstyle - Perl module style guide
|
---|
4 |
|
---|
5 | =head1 INTRODUCTION
|
---|
6 |
|
---|
7 | This document attempts to describe the Perl Community's "best practice"
|
---|
8 | for writing Perl modules. It extends the recommendations found in
|
---|
9 | L<perlstyle> , which should be considered required reading
|
---|
10 | before reading this document.
|
---|
11 |
|
---|
12 | While this document is intended to be useful to all module authors, it is
|
---|
13 | particularly aimed at authors who wish to publish their modules on CPAN.
|
---|
14 |
|
---|
15 | The focus is on elements of style which are visible to the users of a
|
---|
16 | module, rather than those parts which are only seen by the module's
|
---|
17 | developers. However, many of the guidelines presented in this document
|
---|
18 | can be extrapolated and applied successfully to a module's internals.
|
---|
19 |
|
---|
20 | This document differs from L<perlnewmod> in that it is a style guide
|
---|
21 | rather than a tutorial on creating CPAN modules. It provides a
|
---|
22 | checklist against which modules can be compared to determine whether
|
---|
23 | they conform to best practice, without necessarily describing in detail
|
---|
24 | how to achieve this.
|
---|
25 |
|
---|
26 | All the advice contained in this document has been gleaned from
|
---|
27 | extensive conversations with experienced CPAN authors and users. Every
|
---|
28 | piece of advice given here is the result of previous mistakes. This
|
---|
29 | information is here to help you avoid the same mistakes and the extra
|
---|
30 | work that would inevitably be required to fix them.
|
---|
31 |
|
---|
32 | The first section of this document provides an itemized checklist;
|
---|
33 | subsequent sections provide a more detailed discussion of the items on
|
---|
34 | the list. The final section, "Common Pitfalls", describes some of the
|
---|
35 | most popular mistakes made by CPAN authors.
|
---|
36 |
|
---|
37 | =head1 QUICK CHECKLIST
|
---|
38 |
|
---|
39 | For more detail on each item in this checklist, see below.
|
---|
40 |
|
---|
41 | =head2 Before you start
|
---|
42 |
|
---|
43 | =over 4
|
---|
44 |
|
---|
45 | =item *
|
---|
46 |
|
---|
47 | Don't re-invent the wheel
|
---|
48 |
|
---|
49 | =item *
|
---|
50 |
|
---|
51 | Patch, extend or subclass an existing module where possible
|
---|
52 |
|
---|
53 | =item *
|
---|
54 |
|
---|
55 | Do one thing and do it well
|
---|
56 |
|
---|
57 | =item *
|
---|
58 |
|
---|
59 | Choose an appropriate name
|
---|
60 |
|
---|
61 | =back
|
---|
62 |
|
---|
63 | =head2 The API
|
---|
64 |
|
---|
65 | =over 4
|
---|
66 |
|
---|
67 | =item *
|
---|
68 |
|
---|
69 | API should be understandable by the average programmer
|
---|
70 |
|
---|
71 | =item *
|
---|
72 |
|
---|
73 | Simple methods for simple tasks
|
---|
74 |
|
---|
75 | =item *
|
---|
76 |
|
---|
77 | Separate functionality from output
|
---|
78 |
|
---|
79 | =item *
|
---|
80 |
|
---|
81 | Consistent naming of subroutines or methods
|
---|
82 |
|
---|
83 | =item *
|
---|
84 |
|
---|
85 | Use named parameters (a hash or hashref) when there are more than two
|
---|
86 | parameters
|
---|
87 |
|
---|
88 | =back
|
---|
89 |
|
---|
90 | =head2 Stability
|
---|
91 |
|
---|
92 | =over 4
|
---|
93 |
|
---|
94 | =item *
|
---|
95 |
|
---|
96 | Ensure your module works under C<use strict> and C<-w>
|
---|
97 |
|
---|
98 | =item *
|
---|
99 |
|
---|
100 | Stable modules should maintain backwards compatibility
|
---|
101 |
|
---|
102 | =back
|
---|
103 |
|
---|
104 | =head2 Documentation
|
---|
105 |
|
---|
106 | =over 4
|
---|
107 |
|
---|
108 | =item *
|
---|
109 |
|
---|
110 | Write documentation in POD
|
---|
111 |
|
---|
112 | =item *
|
---|
113 |
|
---|
114 | Document purpose, scope and target applications
|
---|
115 |
|
---|
116 | =item *
|
---|
117 |
|
---|
118 | Document each publically accessible method or subroutine, including params and return values
|
---|
119 |
|
---|
120 | =item *
|
---|
121 |
|
---|
122 | Give examples of use in your documentation
|
---|
123 |
|
---|
124 | =item *
|
---|
125 |
|
---|
126 | Provide a README file and perhaps also release notes, changelog, etc
|
---|
127 |
|
---|
128 | =item *
|
---|
129 |
|
---|
130 | Provide links to further information (URL, email)
|
---|
131 |
|
---|
132 | =back
|
---|
133 |
|
---|
134 | =head2 Release considerations
|
---|
135 |
|
---|
136 | =over 4
|
---|
137 |
|
---|
138 | =item *
|
---|
139 |
|
---|
140 | Specify pre-requisites in Makefile.PL or Build.PL
|
---|
141 |
|
---|
142 | =item *
|
---|
143 |
|
---|
144 | Specify Perl version requirements with C<use>
|
---|
145 |
|
---|
146 | =item *
|
---|
147 |
|
---|
148 | Include tests with your module
|
---|
149 |
|
---|
150 | =item *
|
---|
151 |
|
---|
152 | Choose a sensible and consistent version numbering scheme (X.YY is the common Perl module numbering scheme)
|
---|
153 |
|
---|
154 | =item *
|
---|
155 |
|
---|
156 | Increment the version number for every change, no matter how small
|
---|
157 |
|
---|
158 | =item *
|
---|
159 |
|
---|
160 | Package the module using "make dist"
|
---|
161 |
|
---|
162 | =item *
|
---|
163 |
|
---|
164 | Choose an appropriate license (GPL/Artistic is a good default)
|
---|
165 |
|
---|
166 | =back
|
---|
167 |
|
---|
168 | =head1 BEFORE YOU START WRITING A MODULE
|
---|
169 |
|
---|
170 | Try not to launch headlong into developing your module without spending
|
---|
171 | some time thinking first. A little forethought may save you a vast
|
---|
172 | amount of effort later on.
|
---|
173 |
|
---|
174 | =head2 Has it been done before?
|
---|
175 |
|
---|
176 | You may not even need to write the module. Check whether it's already
|
---|
177 | been done in Perl, and avoid re-inventing the wheel unless you have a
|
---|
178 | good reason.
|
---|
179 |
|
---|
180 | Good places to look for pre-existing modules include
|
---|
181 | http://search.cpan.org/ and asking on [email protected]
|
---|
182 |
|
---|
183 | If an existing module B<almost> does what you want, consider writing a
|
---|
184 | patch, writing a subclass, or otherwise extending the existing module
|
---|
185 | rather than rewriting it.
|
---|
186 |
|
---|
187 | =head2 Do one thing and do it well
|
---|
188 |
|
---|
189 | At the risk of stating the obvious, modules are intended to be modular.
|
---|
190 | A Perl developer should be able to use modules to put together the
|
---|
191 | building blocks of their application. However, it's important that the
|
---|
192 | blocks are the right shape, and that the developer shouldn't have to use
|
---|
193 | a big block when all they need is a small one.
|
---|
194 |
|
---|
195 | Your module should have a clearly defined scope which is no longer than
|
---|
196 | a single sentence. Can your module be broken down into a family of
|
---|
197 | related modules?
|
---|
198 |
|
---|
199 | Bad example:
|
---|
200 |
|
---|
201 | "FooBar.pm provides an implementation of the FOO protocol and the
|
---|
202 | related BAR standard."
|
---|
203 |
|
---|
204 | Good example:
|
---|
205 |
|
---|
206 | "Foo.pm provides an implementation of the FOO protocol. Bar.pm
|
---|
207 | implements the related BAR protocol."
|
---|
208 |
|
---|
209 | This means that if a developer only needs a module for the BAR standard,
|
---|
210 | they should not be forced to install libraries for FOO as well.
|
---|
211 |
|
---|
212 | =head2 What's in a name?
|
---|
213 |
|
---|
214 | Make sure you choose an appropriate name for your module early on. This
|
---|
215 | will help people find and remember your module, and make programming
|
---|
216 | with your module more intuitive.
|
---|
217 |
|
---|
218 | When naming your module, consider the following:
|
---|
219 |
|
---|
220 | =over 4
|
---|
221 |
|
---|
222 | =item *
|
---|
223 |
|
---|
224 | Be descriptive (i.e. accurately describes the purpose of the module).
|
---|
225 |
|
---|
226 | =item *
|
---|
227 |
|
---|
228 | Be consistent with existing modules.
|
---|
229 |
|
---|
230 | =item *
|
---|
231 |
|
---|
232 | Reflect the functionality of the module, not the implementation.
|
---|
233 |
|
---|
234 | =item *
|
---|
235 |
|
---|
236 | Avoid starting a new top-level hierarchy, especially if a suitable
|
---|
237 | hierarchy already exists under which you could place your module.
|
---|
238 |
|
---|
239 | =back
|
---|
240 |
|
---|
241 | You should contact [email protected] to ask them about your module name
|
---|
242 | before publishing your module. You should also try to ask people who
|
---|
243 | are already familiar with the module's application domain and the CPAN
|
---|
244 | naming system. Authors of similar modules, or modules with similar
|
---|
245 | names, may be a good place to start.
|
---|
246 |
|
---|
247 | =head1 DESIGNING AND WRITING YOUR MODULE
|
---|
248 |
|
---|
249 | Considerations for module design and coding:
|
---|
250 |
|
---|
251 | =head2 To OO or not to OO?
|
---|
252 |
|
---|
253 | Your module may be object oriented (OO) or not, or it may have both kinds
|
---|
254 | of interfaces available. There are pros and cons of each technique, which
|
---|
255 | should be considered when you design your API.
|
---|
256 |
|
---|
257 | According to Damian Conway, you should consider using OO:
|
---|
258 |
|
---|
259 | =over 4
|
---|
260 |
|
---|
261 | =item *
|
---|
262 |
|
---|
263 | When the system is large or likely to become so
|
---|
264 |
|
---|
265 | =item *
|
---|
266 |
|
---|
267 | When the data is aggregated in obvious structures that will become objects
|
---|
268 |
|
---|
269 | =item *
|
---|
270 |
|
---|
271 | When the types of data form a natural hierarchy that can make use of inheritance
|
---|
272 |
|
---|
273 | =item *
|
---|
274 |
|
---|
275 | When operations on data vary according to data type (making
|
---|
276 | polymorphic invocation of methods feasible)
|
---|
277 |
|
---|
278 | =item *
|
---|
279 |
|
---|
280 | When it is likely that new data types may be later introduced
|
---|
281 | into the system, and will need to be handled by existing code
|
---|
282 |
|
---|
283 | =item *
|
---|
284 |
|
---|
285 | When interactions between data are best represented by
|
---|
286 | overloaded operators
|
---|
287 |
|
---|
288 | =item *
|
---|
289 |
|
---|
290 | When the implementation of system components is likely to
|
---|
291 | change over time (and hence should be encapsulated)
|
---|
292 |
|
---|
293 | =item *
|
---|
294 |
|
---|
295 | When the system design is itself object-oriented
|
---|
296 |
|
---|
297 | =item *
|
---|
298 |
|
---|
299 | When large amounts of client code will use the software (and
|
---|
300 | should be insulated from changes in its implementation)
|
---|
301 |
|
---|
302 | =item *
|
---|
303 |
|
---|
304 | When many separate operations will need to be applied to the
|
---|
305 | same set of data
|
---|
306 |
|
---|
307 | =back
|
---|
308 |
|
---|
309 | Think carefully about whether OO is appropriate for your module.
|
---|
310 | Gratuitous object orientation results in complex APIs which are
|
---|
311 | difficult for the average module user to understand or use.
|
---|
312 |
|
---|
313 | =head2 Designing your API
|
---|
314 |
|
---|
315 | Your interfaces should be understandable by an average Perl programmer.
|
---|
316 | The following guidelines may help you judge whether your API is
|
---|
317 | sufficiently straightforward:
|
---|
318 |
|
---|
319 | =over 4
|
---|
320 |
|
---|
321 | =item Write simple routines to do simple things.
|
---|
322 |
|
---|
323 | It's better to have numerous simple routines than a few monolithic ones.
|
---|
324 | If your routine changes its behaviour significantly based on its
|
---|
325 | arguments, it's a sign that you should have two (or more) separate
|
---|
326 | routines.
|
---|
327 |
|
---|
328 | =item Separate functionality from output.
|
---|
329 |
|
---|
330 | Return your results in the most generic form possible and allow the user
|
---|
331 | to choose how to use them. The most generic form possible is usually a
|
---|
332 | Perl data structure which can then be used to generate a text report,
|
---|
333 | HTML, XML, a database query, or whatever else your users require.
|
---|
334 |
|
---|
335 | If your routine iterates through some kind of list (such as a list of
|
---|
336 | files, or records in a database) you may consider providing a callback
|
---|
337 | so that users can manipulate each element of the list in turn.
|
---|
338 | File::Find provides an example of this with its
|
---|
339 | C<find(\&wanted, $dir)> syntax.
|
---|
340 |
|
---|
341 | =item Provide sensible shortcuts and defaults.
|
---|
342 |
|
---|
343 | Don't require every module user to jump through the same hoops to achieve a
|
---|
344 | simple result. You can always include optional parameters or routines for
|
---|
345 | more complex or non-standard behaviour. If most of your users have to
|
---|
346 | type a few almost identical lines of code when they start using your
|
---|
347 | module, it's a sign that you should have made that behaviour a default.
|
---|
348 | Another good indicator that you should use defaults is if most of your
|
---|
349 | users call your routines with the same arguments.
|
---|
350 |
|
---|
351 | =item Naming conventions
|
---|
352 |
|
---|
353 | Your naming should be consistent. For instance, it's better to have:
|
---|
354 |
|
---|
355 | display_day();
|
---|
356 | display_week();
|
---|
357 | display_year();
|
---|
358 |
|
---|
359 | than
|
---|
360 |
|
---|
361 | display_day();
|
---|
362 | week_display();
|
---|
363 | show_year();
|
---|
364 |
|
---|
365 | This applies equally to method names, parameter names, and anything else
|
---|
366 | which is visible to the user (and most things that aren't!)
|
---|
367 |
|
---|
368 | =item Parameter passing
|
---|
369 |
|
---|
370 | Use named parameters. It's easier to use a hash like this:
|
---|
371 |
|
---|
372 | $obj->do_something(
|
---|
373 | name => "wibble",
|
---|
374 | type => "text",
|
---|
375 | size => 1024,
|
---|
376 | );
|
---|
377 |
|
---|
378 | ... than to have a long list of unnamed parameters like this:
|
---|
379 |
|
---|
380 | $obj->do_something("wibble", "text", 1024);
|
---|
381 |
|
---|
382 | While the list of arguments might work fine for one, two or even three
|
---|
383 | arguments, any more arguments become hard for the module user to
|
---|
384 | remember, and hard for the module author to manage. If you want to add
|
---|
385 | a new parameter you will have to add it to the end of the list for
|
---|
386 | backward compatibility, and this will probably make your list order
|
---|
387 | unintuitive. Also, if many elements may be undefined you may see the
|
---|
388 | following unattractive method calls:
|
---|
389 |
|
---|
390 | $obj->do_something(undef, undef, undef, undef, undef, undef, 1024);
|
---|
391 |
|
---|
392 | Provide sensible defaults for parameters which have them. Don't make
|
---|
393 | your users specify parameters which will almost always be the same.
|
---|
394 |
|
---|
395 | The issue of whether to pass the arguments in a hash or a hashref is
|
---|
396 | largely a matter of personal style.
|
---|
397 |
|
---|
398 | The use of hash keys starting with a hyphen (C<-name>) or entirely in
|
---|
399 | upper case (C<NAME>) is a relic of older versions of Perl in which
|
---|
400 | ordinary lower case strings were not handled correctly by the C<=E<gt>>
|
---|
401 | operator. While some modules retain uppercase or hyphenated argument
|
---|
402 | keys for historical reasons or as a matter of personal style, most new
|
---|
403 | modules should use simple lower case keys. Whatever you choose, be
|
---|
404 | consistent!
|
---|
405 |
|
---|
406 | =back
|
---|
407 |
|
---|
408 | =head2 Strictness and warnings
|
---|
409 |
|
---|
410 | Your module should run successfully under the strict pragma and should
|
---|
411 | run without generating any warnings. Your module should also handle
|
---|
412 | taint-checking where appropriate, though this can cause difficulties in
|
---|
413 | many cases.
|
---|
414 |
|
---|
415 | =head2 Backwards compatibility
|
---|
416 |
|
---|
417 | Modules which are "stable" should not break backwards compatibility
|
---|
418 | without at least a long transition phase and a major change in version
|
---|
419 | number.
|
---|
420 |
|
---|
421 | =head2 Error handling and messages
|
---|
422 |
|
---|
423 | When your module encounters an error it should do one or more of:
|
---|
424 |
|
---|
425 | =over 4
|
---|
426 |
|
---|
427 | =item *
|
---|
428 |
|
---|
429 | Return an undefined value.
|
---|
430 |
|
---|
431 | =item *
|
---|
432 |
|
---|
433 | set C<$Module::errstr> or similar (C<errstr> is a common name used by
|
---|
434 | DBI and other popular modules; if you choose something else, be sure to
|
---|
435 | document it clearly).
|
---|
436 |
|
---|
437 | =item *
|
---|
438 |
|
---|
439 | C<warn()> or C<carp()> a message to STDERR.
|
---|
440 |
|
---|
441 | =item *
|
---|
442 |
|
---|
443 | C<croak()> only when your module absolutely cannot figure out what to
|
---|
444 | do. (C<croak()> is a better version of C<die()> for use within
|
---|
445 | modules, which reports its errors from the perspective of the caller.
|
---|
446 | See L<Carp> for details of C<croak()>, C<carp()> and other useful
|
---|
447 | routines.)
|
---|
448 |
|
---|
449 | =item *
|
---|
450 |
|
---|
451 | As an alternative to the above, you may prefer to throw exceptions using
|
---|
452 | the Error module.
|
---|
453 |
|
---|
454 | =back
|
---|
455 |
|
---|
456 | Configurable error handling can be very useful to your users. Consider
|
---|
457 | offering a choice of levels for warning and debug messages, an option to
|
---|
458 | send messages to a separate file, a way to specify an error-handling
|
---|
459 | routine, or other such features. Be sure to default all these options
|
---|
460 | to the commonest use.
|
---|
461 |
|
---|
462 | =head1 DOCUMENTING YOUR MODULE
|
---|
463 |
|
---|
464 | =head2 POD
|
---|
465 |
|
---|
466 | Your module should include documentation aimed at Perl developers.
|
---|
467 | You should use Perl's "plain old documentation" (POD) for your general
|
---|
468 | technical documentation, though you may wish to write additional
|
---|
469 | documentation (white papers, tutorials, etc) in some other format.
|
---|
470 | You need to cover the following subjects:
|
---|
471 |
|
---|
472 | =over 4
|
---|
473 |
|
---|
474 | =item *
|
---|
475 |
|
---|
476 | A synopsis of the common uses of the module
|
---|
477 |
|
---|
478 | =item *
|
---|
479 |
|
---|
480 | The purpose, scope and target applications of your module
|
---|
481 |
|
---|
482 | =item *
|
---|
483 |
|
---|
484 | Use of each publically accessible method or subroutine, including
|
---|
485 | parameters and return values
|
---|
486 |
|
---|
487 | =item *
|
---|
488 |
|
---|
489 | Examples of use
|
---|
490 |
|
---|
491 | =item *
|
---|
492 |
|
---|
493 | Sources of further information
|
---|
494 |
|
---|
495 | =item *
|
---|
496 |
|
---|
497 | A contact email address for the author/maintainer
|
---|
498 |
|
---|
499 | =back
|
---|
500 |
|
---|
501 | The level of detail in Perl module documentation generally goes from
|
---|
502 | less detailed to more detailed. Your SYNOPSIS section should contain a
|
---|
503 | minimal example of use (perhaps as little as one line of code; skip the
|
---|
504 | unusual use cases or anything not needed by most users); the
|
---|
505 | DESCRIPTION should describe your module in broad terms, generally in
|
---|
506 | just a few paragraphs; more detail of the module's routines or methods,
|
---|
507 | lengthy code examples, or other in-depth material should be given in
|
---|
508 | subsequent sections.
|
---|
509 |
|
---|
510 | Ideally, someone who's slightly familiar with your module should be able
|
---|
511 | to refresh their memory without hitting "page down". As your reader
|
---|
512 | continues through the document, they should receive a progressively
|
---|
513 | greater amount of knowledge.
|
---|
514 |
|
---|
515 | The recommended order of sections in Perl module documentation is:
|
---|
516 |
|
---|
517 | =over 4
|
---|
518 |
|
---|
519 | =item *
|
---|
520 |
|
---|
521 | NAME
|
---|
522 |
|
---|
523 | =item *
|
---|
524 |
|
---|
525 | SYNOPSIS
|
---|
526 |
|
---|
527 | =item *
|
---|
528 |
|
---|
529 | DESCRIPTION
|
---|
530 |
|
---|
531 | =item *
|
---|
532 |
|
---|
533 | One or more sections or subsections giving greater detail of available
|
---|
534 | methods and routines and any other relevant information.
|
---|
535 |
|
---|
536 | =item *
|
---|
537 |
|
---|
538 | BUGS/CAVEATS/etc
|
---|
539 |
|
---|
540 | =item *
|
---|
541 |
|
---|
542 | AUTHOR
|
---|
543 |
|
---|
544 | =item *
|
---|
545 |
|
---|
546 | SEE ALSO
|
---|
547 |
|
---|
548 | =item *
|
---|
549 |
|
---|
550 | COPYRIGHT and LICENSE
|
---|
551 |
|
---|
552 | =back
|
---|
553 |
|
---|
554 | Keep your documentation near the code it documents ("inline"
|
---|
555 | documentation). Include POD for a given method right above that
|
---|
556 | method's subroutine. This makes it easier to keep the documentation up
|
---|
557 | to date, and avoids having to document each piece of code twice (once in
|
---|
558 | POD and once in comments).
|
---|
559 |
|
---|
560 | =head2 README, INSTALL, release notes, changelogs
|
---|
561 |
|
---|
562 | Your module should also include a README file describing the module and
|
---|
563 | giving pointers to further information (website, author email).
|
---|
564 |
|
---|
565 | An INSTALL file should be included, and should contain simple installation
|
---|
566 | instructions. When using ExtUtils::MakeMaker this will usually be:
|
---|
567 |
|
---|
568 | =over 4
|
---|
569 |
|
---|
570 | =item perl Makefile.PL
|
---|
571 |
|
---|
572 | =item make
|
---|
573 |
|
---|
574 | =item make test
|
---|
575 |
|
---|
576 | =item make install
|
---|
577 |
|
---|
578 | =back
|
---|
579 |
|
---|
580 | When using Module::Build, this will usually be:
|
---|
581 |
|
---|
582 | =over 4
|
---|
583 |
|
---|
584 | =item perl Build.PL
|
---|
585 |
|
---|
586 | =item perl Build
|
---|
587 |
|
---|
588 | =item perl Build test
|
---|
589 |
|
---|
590 | =item perl Build install
|
---|
591 |
|
---|
592 | =back
|
---|
593 |
|
---|
594 | Release notes or changelogs should be produced for each release of your
|
---|
595 | software describing user-visible changes to your module, in terms
|
---|
596 | relevant to the user.
|
---|
597 |
|
---|
598 | =head1 RELEASE CONSIDERATIONS
|
---|
599 |
|
---|
600 | =head2 Version numbering
|
---|
601 |
|
---|
602 | Version numbers should indicate at least major and minor releases, and
|
---|
603 | possibly sub-minor releases. A major release is one in which most of
|
---|
604 | the functionality has changed, or in which major new functionality is
|
---|
605 | added. A minor release is one in which a small amount of functionality
|
---|
606 | has been added or changed. Sub-minor version numbers are usually used
|
---|
607 | for changes which do not affect functionality, such as documentation
|
---|
608 | patches.
|
---|
609 |
|
---|
610 | The most common CPAN version numbering scheme looks like this:
|
---|
611 |
|
---|
612 | 1.00, 1.10, 1.11, 1.20, 1.30, 1.31, 1.32
|
---|
613 |
|
---|
614 | A correct CPAN version number is a floating point number with at least
|
---|
615 | 2 digits after the decimal. You can test whether it conforms to CPAN by
|
---|
616 | using
|
---|
617 |
|
---|
618 | perl -MExtUtils::MakeMaker -le 'print MM->parse_version(shift)' 'Foo.pm'
|
---|
619 |
|
---|
620 | If you want to release a 'beta' or 'alpha' version of a module but
|
---|
621 | don't want CPAN.pm to list it as most recent use an '_' after the
|
---|
622 | regular version number followed by at least 2 digits, eg. 1.20_01. If
|
---|
623 | you do this, the following idiom is recommended:
|
---|
624 |
|
---|
625 | $VERSION = "1.12_01";
|
---|
626 | $XS_VERSION = $VERSION; # only needed if you have XS code
|
---|
627 | $VERSION = eval $VERSION;
|
---|
628 |
|
---|
629 | With that trick MakeMaker will only read the first line and thus read
|
---|
630 | the underscore, while the perl interpreter will evaluate the $VERSION
|
---|
631 | and convert the string into a number. Later operations that treat
|
---|
632 | $VERSION as a number will then be able to do so without provoking a
|
---|
633 | warning about $VERSION not being a number.
|
---|
634 |
|
---|
635 | Never release anything (even a one-word documentation patch) without
|
---|
636 | incrementing the number. Even a one-word documentation patch should
|
---|
637 | result in a change in version at the sub-minor level.
|
---|
638 |
|
---|
639 | =head2 Pre-requisites
|
---|
640 |
|
---|
641 | Module authors should carefully consider whether to rely on other
|
---|
642 | modules, and which modules to rely on.
|
---|
643 |
|
---|
644 | Most importantly, choose modules which are as stable as possible. In
|
---|
645 | order of preference:
|
---|
646 |
|
---|
647 | =over 4
|
---|
648 |
|
---|
649 | =item *
|
---|
650 |
|
---|
651 | Core Perl modules
|
---|
652 |
|
---|
653 | =item *
|
---|
654 |
|
---|
655 | Stable CPAN modules
|
---|
656 |
|
---|
657 | =item *
|
---|
658 |
|
---|
659 | Unstable CPAN modules
|
---|
660 |
|
---|
661 | =item *
|
---|
662 |
|
---|
663 | Modules not available from CPAN
|
---|
664 |
|
---|
665 | =back
|
---|
666 |
|
---|
667 | Specify version requirements for other Perl modules in the
|
---|
668 | pre-requisites in your Makefile.PL or Build.PL.
|
---|
669 |
|
---|
670 | Be sure to specify Perl version requirements both in Makefile.PL or
|
---|
671 | Build.PL and with C<require 5.6.1> or similar. See the section on
|
---|
672 | C<use VERSION> of L<perlfunc/require> for details.
|
---|
673 |
|
---|
674 | =head2 Testing
|
---|
675 |
|
---|
676 | All modules should be tested before distribution (using "make disttest"),
|
---|
677 | and the tests should also be available to people installing the modules
|
---|
678 | (using "make test").
|
---|
679 | For Module::Build you would use the C<make test> equivalent C<perl Build test>.
|
---|
680 |
|
---|
681 | The importance of these tests is proportional to the alleged stability of a
|
---|
682 | module -- a module which purports to be stable or which hopes to achieve wide
|
---|
683 | use should adhere to as strict a testing regime as possible.
|
---|
684 |
|
---|
685 | Useful modules to help you write tests (with minimum impact on your
|
---|
686 | development process or your time) include Test::Simple, Carp::Assert
|
---|
687 | and Test::Inline.
|
---|
688 | For more sophisticated test suites there are Test::More and Test::MockObject.
|
---|
689 |
|
---|
690 | =head2 Packaging
|
---|
691 |
|
---|
692 | Modules should be packaged using one of the standard packaging tools.
|
---|
693 | Currently you have the choice between ExtUtils::MakeMaker and the
|
---|
694 | more platform independent Module::Build, allowing modules to be installed in a
|
---|
695 | consistent manner.
|
---|
696 | When using ExtUtils::MakeMaker, you can use "make dist" to create your
|
---|
697 | package. Tools exist to help you to build your module in a MakeMaker-friendly
|
---|
698 | style. These include ExtUtils::ModuleMaker and h2xs. See also L<perlnewmod>.
|
---|
699 |
|
---|
700 | =head2 Licensing
|
---|
701 |
|
---|
702 | Make sure that your module has a license, and that the full text of it
|
---|
703 | is included in the distribution (unless it's a common one and the terms
|
---|
704 | of the license don't require you to include it).
|
---|
705 |
|
---|
706 | If you don't know what license to use, dual licensing under the GPL
|
---|
707 | and Artistic licenses (the same as Perl itself) is a good idea.
|
---|
708 | See L<perlgpl> and L<perlartistic>.
|
---|
709 |
|
---|
710 | =head1 COMMON PITFALLS
|
---|
711 |
|
---|
712 | =head2 Reinventing the wheel
|
---|
713 |
|
---|
714 | There are certain application spaces which are already very, very well
|
---|
715 | served by CPAN. One example is templating systems, another is date and
|
---|
716 | time modules, and there are many more. While it is a rite of passage to
|
---|
717 | write your own version of these things, please consider carefully
|
---|
718 | whether the Perl world really needs you to publish it.
|
---|
719 |
|
---|
720 | =head2 Trying to do too much
|
---|
721 |
|
---|
722 | Your module will be part of a developer's toolkit. It will not, in
|
---|
723 | itself, form the B<entire> toolkit. It's tempting to add extra features
|
---|
724 | until your code is a monolithic system rather than a set of modular
|
---|
725 | building blocks.
|
---|
726 |
|
---|
727 | =head2 Inappropriate documentation
|
---|
728 |
|
---|
729 | Don't fall into the trap of writing for the wrong audience. Your
|
---|
730 | primary audience is a reasonably experienced developer with at least
|
---|
731 | a moderate understanding of your module's application domain, who's just
|
---|
732 | downloaded your module and wants to start using it as quickly as possible.
|
---|
733 |
|
---|
734 | Tutorials, end-user documentation, research papers, FAQs etc are not
|
---|
735 | appropriate in a module's main documentation. If you really want to
|
---|
736 | write these, include them as sub-documents such as C<My::Module::Tutorial> or
|
---|
737 | C<My::Module::FAQ> and provide a link in the SEE ALSO section of the
|
---|
738 | main documentation.
|
---|
739 |
|
---|
740 | =head1 SEE ALSO
|
---|
741 |
|
---|
742 | =over 4
|
---|
743 |
|
---|
744 | =item L<perlstyle>
|
---|
745 |
|
---|
746 | General Perl style guide
|
---|
747 |
|
---|
748 | =item L<perlnewmod>
|
---|
749 |
|
---|
750 | How to create a new module
|
---|
751 |
|
---|
752 | =item L<perlpod>
|
---|
753 |
|
---|
754 | POD documentation
|
---|
755 |
|
---|
756 | =item L<podchecker>
|
---|
757 |
|
---|
758 | Verifies your POD's correctness
|
---|
759 |
|
---|
760 | =item Packaging Tools
|
---|
761 |
|
---|
762 | L<ExtUtils::MakeMaker>, L<Module::Build>
|
---|
763 |
|
---|
764 | =item Testing tools
|
---|
765 |
|
---|
766 | L<Test::Simple>, L<Test::Inline>, L<Carp::Assert>, L<Test::More>, L<Test::MockObject>
|
---|
767 |
|
---|
768 | =item http://pause.perl.org/
|
---|
769 |
|
---|
770 | Perl Authors Upload Server. Contains links to information for module
|
---|
771 | authors.
|
---|
772 |
|
---|
773 | =item Any good book on software engineering
|
---|
774 |
|
---|
775 | =back
|
---|
776 |
|
---|
777 | =head1 AUTHOR
|
---|
778 |
|
---|
779 | Kirrily "Skud" Robert <[email protected]>
|
---|
780 |
|
---|