perlmodstyle 5.20.1 と 5.16.1 の差分

1	1
2	2	=encoding euc-jp
3	3
4	4	=head1 NAME
5	5
6	6	=begin original
7	7
8	8	perlmodstyle - Perl module style guide
9	9
10	10	=end original
11	11
12	12	perlmodstyle - Perl モジュールスタイルガイド
13	13
14	14	=head1 INTRODUCTION
15	15
16	16	=begin original
17	17
18	18	This document attempts to describe the Perl Community's "best practice"
19	19	for writing Perl modules. It extends the recommendations found in
20	20	L<perlstyle> , which should be considered required reading
21	21	before reading this document.
22	22
23	23	=end original
24	24
25	25	このドキュメントは Perl コミュニティにおける
26	26	Perl モジュールを書くときの「ベストプラクティス」を
27	27	説明しています。
28	28	これは L<perlstyle> にある推奨項目を拡張します;
29	29	L<perlstyle> はこのドキュメントに先立って目を通しておいてください。
30	30
31	31	=begin original
32	32
33	33	While this document is intended to be useful to all module authors, it is
34	34	particularly aimed at authors who wish to publish their modules on CPAN.
35	35
36	36	=end original
37	37
38	38	このドキュメントは全てのモジュール作者に役立つように
39	39	意図していますが、CPAN にモジュールを公開しようと
40	40	している作者を特に意図しています。
41	41
42	42	=begin original
43	43
44	44	The focus is on elements of style which are visible to the users of a
45	45	module, rather than those parts which are only seen by the module's
46	46	developers. However, many of the guidelines presented in this document
47	47	can be extrapolated and applied successfully to a module's internals.
48	48
49	49	=end original
50	50
51	51	焦点は、モジュール開発者の目にとまる点ではなく、
52	52	モジュールのユーザの目にとまるスタイルの要素に置かれています。
53	53	しかし、このドキュメントであげられているガイドラインの
54	54	多くはモジュールの内部にも推測、適用できるでしょう。
55	55
56	56	=begin original
57	57
58	58	This document differs from L<perlnewmod> in that it is a style guide
59	59	rather than a tutorial on creating CPAN modules. It provides a
60	60	checklist against which modules can be compared to determine whether
61	61	they conform to best practice, without necessarily describing in detail
62	62	how to achieve this.
63	63
64	64	=end original
65	65
66	66	L<perlnewmod> は CPAN モジュールを作るためのチュートリアルであるのに対し、
67	67	この文書はスタイルに関するガイドという点で異なっています。
68	68	それはモジュールがベストプラクティスに沿っているかを
69	69	これを成し遂げる方法を詳細に記述する必要なしに
70	70	決定するために比較するためのチェックリストを
71	71	提供しています。
72	72
73	73	=begin original
74	74
75	75	All the advice contained in this document has been gleaned from
76	76	extensive conversations with experienced CPAN authors and users. Every
77	77	piece of advice given here is the result of previous mistakes. This
78	78	information is here to help you avoid the same mistakes and the extra
79	79	work that would inevitably be required to fix them.
80	80
81	81	=end original
82	82
83	83	このドキュメントに含まれる全てのアドバイスは
84	84	経験に富んだ CPAN 作者及びユーザの広範囲にわたる
85	85	議論から少しずつ集められています。
86	86	ここにあるアドバイスのどの欠片も以前の過ちの解決として
87	87	生まれました。
88	88	この情報は同じ過ちを繰り返さないように、
89	89	そして必然的にそれらを修正するという余計な作業が
90	90	必要とならないように、あなたを手助けするために
91	91	ここにあります。
92	92
93	93	=begin original
94	94
95	95	The first section of this document provides an itemized checklist;
96	96	subsequent sections provide a more detailed discussion of the items on
97	97	the list. The final section, "Common Pitfalls", describes some of the
98	98	most popular mistakes made by CPAN authors.
99	99
100	100	=end original
101	101
102	102	このドキュメントの最初のセクションでは項目別のチェックリストを
103	103	提供します; その後のセクションではリストの各項目について
104	104	より詳しい説明を行います。
105	105	そして最後のセクション、「よくある落とし穴」で CPAN 作者が
106	106	よくやってしまう、特にメジャーな失敗をいくつか説明します。
107	107
108	108	=head1 QUICK CHECKLIST
109	109
110	110	(クイックチェックリスト)
111	111
112	112	=begin original
113	113
114	114	For more detail on each item in this checklist, see below.
115	115
116	116	=end original
117	117
118	118	このチェックリストにおける各項目の詳細は後のセクションを
119	119	参照してください。
120	120
121	121	=head2 Before you start
122	122
123	123	(始める前に)
124	124
125	125	=over 4
126	126
127	127	=item *
128	128
129	129	=begin original
130	130
131	131	Don't re-invent the wheel
132	132
133	133	=end original
134	134
135	135	車輪の再発明をしない
136	136
137	137	=item *
138	138
139	139	=begin original
140	140
141	141	Patch, extend or subclass an existing module where possible
142	142
143	143	=end original
144	144
145	145	可能であるのなら既存のモジュールにパッチ、拡張、
146	146	サブクラス化を行う
147	147
148	148	=item *
149	149
150	150	=begin original
151	151
152	152	Do one thing and do it well
153	153
154	154	=end original
155	155
156	156	一つのことをうまくやる
157	157
158	158	=item *
159	159
160	160	=begin original
161	161
162	162	Choose an appropriate name
163	163
164	164	=end original
165	165
166	166	ふさわしい名前を選ぶ
167	167
168	168	=back
169	169
170	170	=head2 The API
171	171
172	172	(API)
173	173
174	174	=over 4
175	175
176	176	=item *
177	177
178	178	=begin original
179	179
180	180	API should be understandable by the average programmer
181	181
182	182	=end original
183	183
184	184	API は平均的なプログラマが理解できるようにするべき
185	185
186	186	=item *
187	187
188	188	=begin original
189	189
190	190	Simple methods for simple tasks
191	191
192	192	=end original
193	193
194	194	簡単なタスクのための簡単なメソッドを
195	195
196	196	=item *
197	197
198	198	=begin original
199	199
200	200	Separate functionality from output
201	201
202	202	=end original
203	203
204	204	機能を出力から分離する
205	205
206	206	=item *
207	207
208	208	=begin original
209	209
210	210	Consistent naming of subroutines or methods
211	211
212	212	=end original
213	213
214	214	関数やメソッドには一貫性のある名前を付ける
215	215
216	216	=item *
217	217
218	218	=begin original
219	219
220	220	Use named parameters (a hash or hashref) when there are more than two
221	221	parameters
222	222
223	223	=end original
224	224
225	225	二つ以上の引数ををとるのなら
226	226	名前付きの引数(ハッシュまたはハッシュリファレンス)を使う
227	227
228	228	=back
229	229
230	230	=head2 Stability
231	231
232	232	(安定性)
233	233
234	234	=over 4
235	235
236	236	=item *
237	237
238	238	=begin original
239	239
240	240	Ensure your module works under C<use strict> and C<-w>
241	241
242	242	=end original
243	243
244	244	C<use strict> 及び C<-w> の環境下で動作することを
245	245	保証する
246	246
247	247	=item *
248	248
249	249	=begin original
250	250
251	251	Stable modules should maintain backwards compatibility
252	252
253	253	=end original
254	254
255	255	安定したモジュールは後方互換性を維持するべき
256	256
257	257	=back
258	258
259	259	=head2 Documentation
260	260
261	261	(ドキュメンテーション)
262	262
263	263	=over 4
264	264
265	265	=item *
266	266
267	267	=begin original
268	268
269	269	Write documentation in POD
270	270
271	271	=end original
272	272
273	273	文書を POD 形式で書く
274	274
275	275	=item *
276	276
277	277	=begin original
278	278
279	279	Document purpose, scope and target applications
280	280
281	281	=end original
282	282
283	283	目的、範囲、及び対象となるアプリケーションを記述する
284	284
285	285	=item *
286	286
287	287	=begin original
288	288
289	289	Document each publically accessible method or subroutine, including params and return values
290	290
291	291	=end original
292	292
293	293	個々の公開されているアクセスメソッドまたは関数を、
294	294	引数及び返り値も含めて記述する
295	295
296	296	=item *
297	297
298	298	=begin original
299	299
300	300	Give examples of use in your documentation
301	301
302	302	=end original
303	303
304	304	文書に使い方を例示する
305	305
306	306	=item *
307	307
308	308	=begin original
309	309
310	310	Provide a README file and perhaps also release notes, changelog, etc
311	311
312	312	=end original
313	313
314	314	README ファイルを提供する; またできればリリースノート、更新履歴も
315	315
316	316	=item *
317	317
318	318	=begin original
319	319
320	320	Provide links to further information (URL, email)
321	321
322	322	=end original
323	323
324	324	さらなる情報へのリンク(URL, email)を提供する
325	325
326	326	=back
327	327
328	328	=head2 Release considerations
329	329
330	330	(リリース時に確認すること)
331	331
332	332	=over 4
333	333
334	334	=item *
335	335
336	336	=begin original
337	337
338	338	Specify pre-requisites in Makefile.PL or Build.PL
339	339
340	340	=end original
341	341
342	342	Makefile.PL または Build.PL に依存(pre-requisites)を記述する
343	343
344	344	=item *
345	345
346	346	=begin original
347	347
348	348	Specify Perl version requirements with C<use>
349	349
350	350	=end original
351	351
352	352	動作に必要な Perl のバージョンを C<use> で記述する
353	353
354	354	=item *
355	355
356	356	=begin original
357	357
358	358	Include tests with your module
359	359
360	360	=end original
361	361
362	362	モジュールにはテストを含める
363	363
364	364	=item *
365	365
366	366	=begin original
367	367
368	368	Choose a sensible and consistent version numbering scheme (X.YY is the common Perl module numbering scheme)
369	369
370	370	=end original
371	371
372	372	バージョン番号の採番には一般的で矛盾の起きない形式を選ぶ
373	373	(Perl モジュールでは一般的に X.YY が使われている)
374	374
375	375	=item *
376	376
377	377	=begin original
378	378
379	379	Increment the version number for every change, no matter how small
380	380
381	381	=end original
382	382
383	383	たとえそれがどんなに小さな変更であっても、変更毎にバージョン番号を増やす
384	384
385	385	=item *
386	386
387	387	=begin original
388	388
389	389	Package the module using "make dist"
390	390
391	391	=end original
392	392
393	393	モジュールのパッケージングには "make dist" を使う
394	394
395	395	=item *
396	396
397	397	=begin original
398	398
399	399	Choose an appropriate license (GPL/Artistic is a good default)
400	400
401	401	=end original
402	402
403	403	適切なライセンスを選ぶ (GPL/Artistic はよいデフォルトです)
404	404
405	405	=back
406	406
407	407	=head1 BEFORE YOU START WRITING A MODULE
408	408
409	409	(モジュールを書き始める前に)
410	410
411	411	=begin original
412	412
413	413	Try not to launch headlong into developing your module without spending
414	414	some time thinking first. A little forethought may save you a vast
415	415	amount of effort later on.
416	416
417	417	=end original
418	418
419	419	最初に少し考える時間を取らずにモジュール開発に取りかかろうとしないで
420	420	ください。
421	421	予め少し考えておくことで、後での多くの苦労を防げます。
422	422
423	423	=head2 Has it been done before?
424	424
425	425	(以前作られていなかった?)
426	426
427	427	=begin original
428	428
429	429	You may not even need to write the module. Check whether it's already
430	430	been done in Perl, and avoid re-inventing the wheel unless you have a
431	431	good reason.
432	432
433	433	=end original
434	434
435	435	そもそもモジュールを書く必要がないかもしれません。
436	436	既に Perl で行われているかどうかを調べて、よい理由がない限り
437	437	車輪の再発明は避けてください。
438	438
439	439	=begin original
440	440
441	441	Good places to look for pre-existing modules include
442	442	http://search.cpan.org/ and asking on modules@perl.org
443	443
444	444	=end original
445	445
446	446	既にあるモジュールを探すのによい場所は、http://search.cpan.org/ と、
447	447	modules@perl.org に聞くことです。
448	448
449	449	=begin original
450	450
451	451	If an existing module B<almost> does what you want, consider writing a
452	452	patch, writing a subclass, or otherwise extending the existing module
453	453	rather than rewriting it.
454	454
455	455	=end original
456	456
457	457	もし既にあるモジュールがやりたいことを B<ほとんど> しているなら、
458	458	それを書き直すのではなく、パッチを作ったり、派生クラスを作ったり、
459	459	あるいは既にあるモジュールを拡張するためのその他の手段を考慮してください。
460	460
461	461	=head2 Do one thing and do it well
462	462
463	463	(一つのことをうまくやる)
464	464
465	465	=begin original
466	466
467	467	At the risk of stating the obvious, modules are intended to be modular.
468	468	A Perl developer should be able to use modules to put together the
469	469	building blocks of their application. However, it's important that the
470	470	blocks are the right shape, and that the developer shouldn't have to use
471	471	a big block when all they need is a small one.
472	472
473	473	=end original
474	474
475	475	当たり前のことを述べるという危険を冒しますが、モジュールはモジュール式で
476	476	あることを目的としています。
477	477	Perl 開発者は、自身のアプリケーションの建築ブロックを寄せ集めるために
478	478	モジュールを使えるようにするべきです。
479	479	しかし、ブロックが正しい形をしていて、開発者が小さいブロックが必要な
480	480	だけのときに大きいブロックを使う必要がないようにすることが重要です。
481	481
482	482	=begin original
483	483
484	484	Your module should have a clearly defined scope which is no longer than
485	485	a single sentence. Can your module be broken down into a family of
486	486	related modules?
487	487
488	488	=end original
489	489
490	490	モジュールは、一文だけで表現できる明確に定義されたスコープを持つべきです。
491	491	あなたのモジュールは関係するモジュール群に分割できませんか?
492	492
493	493	=begin original
494	494
495	495	Bad example:
496	496
497	497	=end original
498	498
499	499	悪い例:
500	500
501	501	=begin original
502	502
503	503	"FooBar.pm provides an implementation of the FOO protocol and the
504	504	related BAR standard."
505	505
506	506	=end original
507	507
508	508	「FooBar.pm は、FOO プロトコルと、関連する BAR 標準の実装を提供します。」
509	509
510	510	=begin original
511	511
512	512	Good example:
513	513
514	514	=end original
515	515
516	516	良い例:
517	517
518	518	=begin original
519	519
520	520	"Foo.pm provides an implementation of the FOO protocol. Bar.pm
521	521	implements the related BAR protocol."
522	522
523	523	=end original
524	524
525	525	「Foo.pm は FOO プロトコルの実装を提供します。
526	526	Bar.pm は関連する BAR プロトコルを実装します。」
527	527
528	528	=begin original
529	529
530	530	This means that if a developer only needs a module for the BAR standard,
531	531	they should not be forced to install libraries for FOO as well.
532	532
533	533	=end original
534	534
535	535	これは、もし開発者が BAR 標準のモジュールだけを必要としているなら、
536	536	FOO ライブラリのインストールを強制されないということです。
537	537
538	538	=head2 What's in a name?
539	539
540	540	(なんて名前?)
541	541
542	542	=begin original
543	543
544	544	Make sure you choose an appropriate name for your module early on. This
545	545	will help people find and remember your module, and make programming
546	546	with your module more intuitive.
547	547
548	548	=end original
549	549
550	550	前もって、モジュールのための適切な名前を選んでください。
551	551	これは人々がモジュールを探したり覚えたりする助けになり、モジュールを
552	552	使ったプログラミングがより直観的になります。
553	553
554	554	=begin original
555	555
556	556	When naming your module, consider the following:
557	557
558	558	=end original
559	559
560	560	モジュールに名前を付けるときには、以下のことを考慮してください:
561	561
562	562	=over 4
563	563
564	564	=item *
565	565
566	566	=begin original
567	567
568	568	Be descriptive (i.e. accurately describes the purpose of the module).
569	569
570	570	=end original
571	571
572	572	説明的にする (モジュールの目的を正確に表現する)。
573	573
574	574	=item *
575	575
576	576	=begin original
577	577
578	578	Be consistent with existing modules.
579	579
580	580	=end original
581	581
582	582	すでにあるモジュールと一貫性をもつ。
583	583
584	584	=item *
585	585
586	586	=begin original
587	587
588	588	Reflect the functionality of the module, not the implementation.
589	589
590	590	=end original
591	591
592	592	モジュールの実装ではなく、モジュールの機能を反映させる。
593	593
594	594	=item *
595	595
596	596	=begin original
597	597
598	598	Avoid starting a new top-level hierarchy, especially if a suitable
599	599	hierarchy already exists under which you could place your module.
600	600
601	601	=end original
602	602
603	603	新しいトップレベル階層を作るのを避ける(特にモジュールを置くのに
604	604	適切な階層がすでにある場合は)。
605	605
606	606	=back
607	607
608	608	=begin original
609	609
610	610	You should contact modules@perl.org to ask them about your module name
611	611	before publishing your module. You should also try to ask people who
612	612	are already familiar with the module's application domain and the CPAN
613	613	naming system. Authors of similar modules, or modules with similar
614	614	names, may be a good place to start.
615	615
616	616	=end original
617	617
618	618	モジュールを出版する前に、モジュール名について訊ねるために
619	619	modules@perl.org に連絡するべきです。
620	620	また、すでにモジュールのアプリケーションドメインと CPAN 命名システムに
621	621	親しんでいる人々に尋ねてみるべきです。
622	622	同様なモジュールの作者や、似た名前のモジュールは始めるのに
623	623	いいところでしょう。
624	624
625	625	=head1 DESIGNING AND WRITING YOUR MODULE
626	626
627	627	(モジュールの設計と作成)
628	628
629	629	=begin original
630	630
631	631	Considerations for module design and coding:
632	632
633	633	=end original
634	634
635	635	モジュールの設計とコーディングで考慮すること:
636	636
637	637	=head2 To OO or not to OO?
638	638
639	639	(OO か非 OO か?)
640	640
641	641	=begin original
642	642
643	643	Your module may be object oriented (OO) or not, or it may have both kinds
644	644	of interfaces available. There are pros and cons of each technique, which
645	645	should be considered when you design your API.
646	646
647	647	=end original
648	648
649	649	モジュールはオブジェクト指向 (OO) にするかしないか、あるいは両方の
650	650	インターフェースを持つようにもできます。
651	651	それぞれの技術には、API を設計するときに検討するべき
652	652	メリットデメリットがあります。
653	653
654	654	=begin original
655	655
656	656	In I<Perl Best Practices> (copyright 2004, Published by O'Reilly Media, Inc.),
657	657	Damian Conway provides a list of criteria to use when deciding if OO is the
658	658	right fit for your problem:
659	659
660	660	=end original
661	661
662	662	I<Perl ベストプラクティス>(Perl Best Practices>) (2004 年、
663	663	オライリーメディアによって出版)で、Damian Conway は OO が問題を解決するのに
664	664	向いているかを判断するときに使う基準の一覧を提供しています:
665	665
666	666	=over 4
667	667
668		=item *
	668	=item *
669	669
670	670	=begin original
671	671
672	672	The system being designed is large, or is likely to become large.
673	673
674	674	=end original
675	675
676	676	システムが大きかったり大きくなりそう。
677	677
678		=item *
	678	=item *
679	679
680	680	=begin original
681	681
682	682	The data can be aggregated into obvious structures, especially if
683	683	there's a large amount of data in each aggregate.
684	684
685	685	=end original
686	686
687	687	データが、オブジェクトになるよくある構造に集約される; 特にそれぞれの集約が
688	688	大量のデータである。
689	689
690		=item *
	690	=item *
691	691
692	692	=begin original
693	693
694	694	The various types of data aggregate form a natural hierarchy that
695	695	facilitates the use of inheritance and polymorphism.
696	696
697	697	=end original
698	698
699	699	データ形式が継承や多態性を容易にするような自然な階層を形成している。
700	700
701	701	=item *
702	702
703	703	=begin original
704	704
705	705	You have a piece of data on which many different operations are
706	706	applied.
707	707
708	708	=end original
709	709
710	710	様々な異なる操作が行われるデータがある。
711	711
712	712	=item *
713	713
714	714	=begin original
715	715
716	716	You need to perform the same general operations on related types of
717	717	data, but with slight variations depending on the specific type of data
718	718	the operations are applied to.
719	719
720	720	=end original
721	721
722	722	データの型に関係する同じ一般的な操作をする必要があるけれども、操作を
723	723	適用するデータの型によって少しずつ異なる。
724	724
725	725	=item *
726	726
727	727	=begin original
728	728
729	729	It's likely you'll have to add new data types later.
730	730
731	731	=end original
732	732
733	733	後で新しいデータ型を追加する必要がありそう。
734	734
735	735	=item *
736	736
737	737	=begin original
738	738
739	739	The typical interactions between pieces of data are best represented by
740	740	operators.
741	741
742	742	=end original
743	743
744	744	データとの典型的な相互作用が演算子によって最もよく表現される。
745	745
746	746	=item *
747	747
748	748	=begin original
749	749
750	750	The implementation of individual components of the system is likely to
751	751	change over time.
752	752
753	753	=end original
754	754
755	755	システムの個々の要素の実装が後でやがて変更になりそう。
756	756
757	757	=item *
758	758
759	759	=begin original
760	760
761	761	The system design is already object-oriented.
762	762
763	763	=end original
764	764
765	765	システム設計自身が既にオブジェクト指向である。
766	766
767	767	=item *
768	768
769	769	=begin original
770	770
771	771	Large numbers of other programmers will be using your code modules.
772	772
773	773	=end original
774	774
775	775	大量のクライアントコードがこのソフトウェアを使う (そして実装から変更を
776	776	分離しておくべき) とき
777	777
778	778	=back
779	779
780	780	=begin original
781	781
782	782	Think carefully about whether OO is appropriate for your module.
783	783	Gratuitous object orientation results in complex APIs which are
784	784	difficult for the average module user to understand or use.
785	785
786	786	=end original
787	787
788	788	あなたのモジュールに OO が適切かどうかを慎重に考えてください。
789	789	不必要なオブジェクト指向は、平均的なモジュール利用者が理解や使用するのが
790	790	困難な複雑な API となります。
791	791
792	792	=head2 Designing your API
793	793
794	794	(API の設計)
795	795
796	796	=begin original
797	797
798	798	Your interfaces should be understandable by an average Perl programmer.
799	799	The following guidelines may help you judge whether your API is
800	800	sufficiently straightforward:
801	801
802	802	=end original
803	803
804	804	インターフェースは平均的な Perl プログラマが理解可能であるべきです。
805	805	以下のガイドラインは、API が充分に簡単かどうかを判断する手助けに
806	806	なるでしょう:
807	807
808	808	=over 4
809	809
810	810	=item Write simple routines to do simple things.
811	811
812	812	(単純なことをする単純なルーチンを書く。)
813	813
814	814	=begin original
815	815
816	816	It's better to have numerous simple routines than a few monolithic ones.
817	817	If your routine changes its behaviour significantly based on its
818	818	arguments, it's a sign that you should have two (or more) separate
819	819	routines.
820	820
821	821	=end original
822	822
823	823	少量の巨大なルーチンよりも、たくさんの単純なルーチンの方がよいです。
824	824	ルーチンが引数によって大きく振る舞いを変えるなら、複数のルーチンに
825	825	分割するべきと言うサインです。
826	826
827	827	=item Separate functionality from output.
828	828
829	829	(機能を出力から分離する。)
830	830
831	831	=begin original
832	832
833	833	Return your results in the most generic form possible and allow the user
834	834	to choose how to use them. The most generic form possible is usually a
835	835	Perl data structure which can then be used to generate a text report,
836	836	HTML, XML, a database query, or whatever else your users require.
837	837
838	838	=end original
839	839
840	840	結果は出来るだけ一般的な形式で返して、ユーザがそれをどのように使うかを
841	841	選択できるようにします。
842	842	最も一般的な形式とは、おそらく後でテキストレポート、HTML、XML、
843	843	データベースクエリ、あるいはユーザが求めるもの何でも生成できる
844	844	Perl データ構造です。
845	845
846	846	=begin original
847	847
848	848	If your routine iterates through some kind of list (such as a list of
849	849	files, or records in a database) you may consider providing a callback
850	850	so that users can manipulate each element of the list in turn.
851	851	File::Find provides an example of this with its
852	852	C<find(\&wanted, $dir)> syntax.
853	853
854	854	=end original
855	855
856	856	あなたのルーチンがある種のリスト(ファイルのリスト、データベースの
857	857	レコードなど)に対して反復するなら、ユーザがリストのそれぞれの要素を
858	858	操作できるようなコールバックを提供することを考慮してください。
859	859	File::Find は C<find(\&wanted, $dir)> という文法で、この場合の例を
860	860	提供しています。
861	861
862	862	=item Provide sensible shortcuts and defaults.
863	863
864	864	(実用的なショートカットやデフォルトを提供する。)
865	865
866	866	=begin original
867	867
868	868	Don't require every module user to jump through the same hoops to achieve a
869	869	simple result. You can always include optional parameters or routines for
870	870	more complex or non-standard behaviour. If most of your users have to
871	871	type a few almost identical lines of code when they start using your
872	872	module, it's a sign that you should have made that behaviour a default.
873	873	Another good indicator that you should use defaults is if most of your
874	874	users call your routines with the same arguments.
875	875
876	876	=end original
877	877
878	878	単純な結果を得るために全てのモジュールユーザに同じ輪をくぐることを
879	879	要求しないようにしてください。
880	880	より複雑だったり標準でない振る舞いのためには、常にオプションの引数や
881	881	ルーチンを用意して管浅い。
882	882	もしほとんどのユーザがモジュールを使い始めるときにほとんど同じ
883	883	数行のコードを書く必要があるなら、それはその振る舞いをデフォルトに
884	884	するべきというサインです。
885	885	デフォルトを使うべきというもう一つの指標は、ユーザのほとんどが同じ引数で
886	886	ルーチンを呼び出すときです。
887	887
888	888	=item Naming conventions
889	889
890	890	(命名規則)
891	891
892	892	=begin original
893	893
894	894	Your naming should be consistent. For instance, it's better to have:
895	895
896	896	=end original
897	897
898	898	命名は一貫性を持たせるべきです。
899	899	例えば、以下のものは:
900	900
901	901	display_day();
902	902	display_week();
903	903	display_year();
904	904
905	905	=begin original
906	906
907	907	than
908	908
909	909	=end original
910	910
911	911	以下のものよりよいです:
912	912
913	913	display_day();
914	914	week_display();
915	915	show_year();
916	916
917	917	=begin original
918	918
919	919	This applies equally to method names, parameter names, and anything else
920	920	which is visible to the user (and most things that aren't!)
921	921
922	922	=end original
923	923
924	924	これはメソッド名、引数名、その他ユーザに見えるもの何にでも
925	925	(そして見えない物のほとんどにも!)適用されます。
926	926
927	927	=item Parameter passing
928	928
929	929	(引数の渡し方)
930	930
931	931	=begin original
932	932
933	933	Use named parameters. It's easier to use a hash like this:
934	934
935	935	=end original
936	936
937	937	名前付き引数を使いましょう。
938	938	これは以下のようにハッシュを使えば:
939	939
940	940	$obj->do_something(
941	941	name => "wibble",
942	942	type => "text",
943	943	size => 1024,
944	944	);
945	945
946	946	=begin original
947	947
948	948	... than to have a long list of unnamed parameters like this:
949	949
950	950	=end original
951	951
952	952	…以下のように名前のない引数の長いリストより簡単です:
953	953
954	954	$obj->do_something("wibble", "text", 1024);
955	955
956	956	=begin original
957	957
958	958	While the list of arguments might work fine for one, two or even three
959	959	arguments, any more arguments become hard for the module user to
960	960	remember, and hard for the module author to manage. If you want to add
961	961	a new parameter you will have to add it to the end of the list for
962	962	backward compatibility, and this will probably make your list order
963	963	unintuitive. Also, if many elements may be undefined you may see the
964	964	following unattractive method calls:
965	965
966	966	=end original
967	967
968	968	引数のリストは 1 引数、2 引数、そして 3 引数でもうまく動作するでしょうが、
969	969	それ以上になるとモジュールユーザが覚えるのが難しくなり、モジュール
970	970	作者が管理するのも難しくなります。
971	971	新しい引数を追加したいときは、後方互換性のためにリストの最後に追加する
972	972	必要があり、そしてこれによっておそらくリストの順序が直観的では
973	973	なくなるでしょう。
974	974	また、多くの要素が未定義の場合、以下のような美しくないメソッド呼び出しを
975	975	見ることになるでしょう:
976	976
977		$obj->do_something(undef, undef, undef, undef, undef, 1024);
	977	$obj->do_something(undef, undef, undef, undef, undef, undef, 1024);
978	978
979	979	=begin original
980	980
981	981	Provide sensible defaults for parameters which have them. Don't make
982	982	your users specify parameters which will almost always be the same.
983	983
984	984	=end original
985	985
986	986	引数に、意味のあるデフォルトがあるならそれをデフォルトにしましょう。
987	987	ユーザーに、毎回ほとんど同じような引数を指定させてはいけません。
988	988
989	989	=begin original
990	990
991	991	The issue of whether to pass the arguments in a hash or a hashref is
992	992	largely a matter of personal style.
993	993
994	994	=end original
995	995
996	996	引数をハッシュで渡すかハッシュリファレンスで渡すかの問題は主に個人的な
997	997	スタイルの問題です。
998	998
999	999	=begin original
1000	1000
1001	1001	The use of hash keys starting with a hyphen (C<-name>) or entirely in
1002	1002	upper case (C<NAME>) is a relic of older versions of Perl in which
1003	1003	ordinary lower case strings were not handled correctly by the C<=E<gt>>
1004	1004	operator. While some modules retain uppercase or hyphenated argument
1005	1005	keys for historical reasons or as a matter of personal style, most new
1006	1006	modules should use simple lower case keys. Whatever you choose, be
1007	1007	consistent!
1008	1008
1009	1009	=end original
1010	1010
1011	1011	ハイフンで始まるハッシュキー (C<-name>) や全て大文字のハッシュキー
1012	1012	(C<NAME>) は、普通の小文字の文字列が C<=E<gt>> 演算子で扱えなかった
1013	1013	古いバージョンの Perl の遺物です。
1014	1014	一部のモジュールでは歴史的な理由や個人的なスタイルの問題で大文字や
1015	1015	ハイフン付きのキーのままですが、ほとんどの新しいモジュールは単純な
1016	1016	小文字のキーを使うべきです。
1017	1017	どちらを選ぶにせよ、一貫性を持ちましょう!
1018	1018
1019	1019	=back
1020	1020
1021	1021	=head2 Strictness and warnings
1022	1022
1023	1023	(strict と warnings)
1024	1024
1025	1025	=begin original
1026	1026
1027	1027	Your module should run successfully under the strict pragma and should
1028	1028	run without generating any warnings. Your module should also handle
1029	1029	taint-checking where appropriate, though this can cause difficulties in
1030	1030	many cases.
1031	1031
1032	1032	=end original
1033	1033
1034	1034	モジュールは stirct プラグマ付きでも正しく動作し、一切の警告なしで
1035	1035	動作するべきです。
1036	1036	また、適切な場所では汚染チェックも扱うべきですが、これは多くの場合で困難を
1037	1037	伴います。
1038	1038
1039	1039	=head2 Backwards compatibility
1040	1040
1041	1041	(後方互換性)
1042	1042
1043	1043	=begin original
1044	1044
1045	1045	Modules which are "stable" should not break backwards compatibility
1046	1046	without at least a long transition phase and a major change in version
1047	1047	number.
1048	1048
1049	1049	=end original
1050	1050
1051	1051	「安定版の」モジュールは、少なくとも長い移行フェーズとバージョン番号の
1052	1052	メジャー番号の変更することなく、後方互換性を壊すべきではありません。
1053	1053
1054	1054	=head2 Error handling and messages
1055	1055
1056	1056	(エラーハンドリングとメッセージ)
1057	1057
1058	1058	=begin original
1059	1059
1060	1060	When your module encounters an error it should do one or more of:
1061	1061
1062	1062	=end original
1063	1063
1064	1064	モジュールがエラーに遭遇した場合、以下の一つあるいは複数を行うべきです:
1065	1065
1066	1066	=over 4
1067	1067
1068	1068	=item *
1069	1069
1070	1070	=begin original
1071	1071
1072	1072	Return an undefined value.
1073	1073
1074	1074	=end original
1075	1075
1076	1076	未定義値を返す。
1077	1077
1078	1078	=item *
1079	1079
1080	1080	=begin original
1081	1081
1082	1082	set C<$Module::errstr> or similar (C<errstr> is a common name used by
1083	1083	DBI and other popular modules; if you choose something else, be sure to
1084	1084	document it clearly).
1085	1085
1086	1086	=end original
1087	1087
1088	1088	C<$Module::errstr> あるいは同様のものを設定する (C<errstr> は DBI および
1089	1089	その他の有名なモジュールで使われている一般的な名前です; もし他のものを
1090	1090	選んだなら、それを明確に文書化しておきましょう)。
1091	1091
1092	1092	=item *
1093	1093
1094	1094	=begin original
1095	1095
1096	1096	C<warn()> or C<carp()> a message to STDERR.
1097	1097
1098	1098	=end original
1099	1099
1100	1100	C<warn()> や C<carp()> を使ってメッセージを STDERR に出力する。
1101	1101
1102	1102	=item *
1103	1103
1104	1104	=begin original
1105	1105
1106	1106	C<croak()> only when your module absolutely cannot figure out what to
1107	1107	do. (C<croak()> is a better version of C<die()> for use within
1108	1108	modules, which reports its errors from the perspective of the caller.
1109	1109	See L<Carp> for details of C<croak()>, C<carp()> and other useful
1110	1110	routines.)
1111	1111
1112	1112	=end original
1113	1113
1114	1114	C<croak()> は、あなたのモジュールが何をすればいいのか全く分からないときにのみ
1115	1115	使います。
1116	1116	(C<croak()> はモジュール内で使うための C<die()> の改良版で、
1117	1117	エラーを呼び出し元の観点から報告します。
1118	1118	C<croak()>, C<carp()> およびその他の便利なルーチンについては
1119	1119	L<Carp> を参照してください。)
1120	1120
1121	1121	=item *
1122	1122
1123	1123	=begin original
1124	1124
1125	1125	As an alternative to the above, you may prefer to throw exceptions using
1126	1126	the Error module.
1127	1127
1128	1128	=end original
1129	1129
1130	1130	上述の代替案として、Error モジュールを使って例外を投げる方を
1131	1131	好むかもしれません。
1132	1132
1133	1133	=back
1134	1134
1135	1135	=begin original
1136	1136
1137	1137	Configurable error handling can be very useful to your users. Consider
1138	1138	offering a choice of levels for warning and debug messages, an option to
1139	1139	send messages to a separate file, a way to specify an error-handling
1140	1140	routine, or other such features. Be sure to default all these options
1141	1141	to the commonest use.
1142	1142
1143	1143	=end original
1144	1144
1145	1145	設定可能なエラー処理はユーザーにとってとても便利です。
1146	1146	警告やデバッグメッセージのレベルの選択、メッセージの別のファイルへの書き出し、
1147	1147	エラー処理ルーチンの指定方法、あるいはその他の同様の機能の提供を
1148	1148	考慮してください。
1149	1149	これらのオプション全てのデフォルトは最も一般的な使用法に設定してください。
1150	1150
1151	1151	=head1 DOCUMENTING YOUR MODULE
1152	1152
1153	1153	(モジュールを文書化する)
1154	1154
1155	1155	=head2 POD
1156	1156
1157	1157	=begin original
1158	1158
1159	1159	Your module should include documentation aimed at Perl developers.
1160	1160	You should use Perl's "plain old documentation" (POD) for your general
1161	1161	technical documentation, though you may wish to write additional
1162	1162	documentation (white papers, tutorials, etc) in some other format.
1163	1163	You need to cover the following subjects:
1164	1164
1165	1165	=end original
1166	1166
1167	1167	モジュールは Perl の開発者向けの文書を含めるべきです。
1168	1168	一般的な技術文書に対しては Perl の "plain old documentation" (POD) を
1169	1169	使うべきですが、追加の文書 (ホワイトペーパー、チュートリアルなど) は
1170	1170	その他のフォーマットで書きたいかもしれません。
1171	1171	以下のような主題に対応する必要があります:
1172	1172
1173	1173	=over 4
1174	1174
1175	1175	=item *
1176	1176
1177	1177	=begin original
1178	1178
1179	1179	A synopsis of the common uses of the module
1180	1180
1181	1181	=end original
1182	1182
1183	1183	モジュールの一般的な使い方の概要
1184	1184
1185	1185	=item *
1186	1186
1187	1187	=begin original
1188	1188
1189	1189	The purpose, scope and target applications of your module
1190	1190
1191	1191	=end original
1192	1192
1193	1193	モジュールの目的、スコープ、対象アプリケーション
1194	1194
1195	1195	=item *
1196	1196
1197	1197	=begin original
1198	1198
1199	1199	Use of each publically accessible method or subroutine, including
1200	1200	parameters and return values
1201	1201
1202	1202	=end original
1203	1203
1204	1204	(引数と返り値を含む) 公開されているメソッドやサブルーチンの使用法
1205	1205
1206	1206	=item *
1207	1207
1208	1208	=begin original
1209	1209
1210	1210	Examples of use
1211	1211
1212	1212	=end original
1213	1213
1214	1214	使用例
1215	1215
1216	1216	=item *
1217	1217
1218	1218	=begin original
1219	1219
1220	1220	Sources of further information
1221	1221
1222	1222	=end original
1223	1223
1224	1224	さらなる情報の情報源
1225	1225
1226	1226	=item *
1227	1227
1228	1228	=begin original
1229	1229
1230	1230	A contact email address for the author/maintainer
1231	1231
1232	1232	=end original
1233	1233
1234	1234	作者/メンテナへ連絡するための email アドレス
1235	1235
1236	1236	=back
1237	1237
1238	1238	=begin original
1239	1239
1240	1240	The level of detail in Perl module documentation generally goes from
1241	1241	less detailed to more detailed. Your SYNOPSIS section should contain a
1242	1242	minimal example of use (perhaps as little as one line of code; skip the
1243	1243	unusual use cases or anything not needed by most users); the
1244	1244	DESCRIPTION should describe your module in broad terms, generally in
1245	1245	just a few paragraphs; more detail of the module's routines or methods,
1246	1246	lengthy code examples, or other in-depth material should be given in
1247	1247	subsequent sections.
1248	1248
1249	1249	=end original
1250	1250
1251	1251	Perl モジュール文書の詳細度は、一般的に概略から詳細へという順序に
1252	1252	なっています。
1253	1253	SYNOPSIS 節には使うための最小限の例を含むべきです
1254	1254	(おそらくは一行でしょう; 一般的でない使い方やほとんどのユーザーにとって
1255	1255	必要でないものは省略します);
1256	1256	DESCRIPTION はモジュールを広義で記述し、一般的には単に数段落です;
1257	1257	モジュールのルーチンやメソッドに関する更なる詳細、長いコード例、その他の
1258	1258	より深い内容は引き続く節に書くべきです。
1259	1259
1260	1260	=begin original
1261	1261
1262	1262	Ideally, someone who's slightly familiar with your module should be able
1263	1263	to refresh their memory without hitting "page down". As your reader
1264	1264	continues through the document, they should receive a progressively
1265	1265	greater amount of knowledge.
1266	1266
1267	1267	=end original
1268	1268
1269	1269	理想的には、モジュールに対して少しなじみのあるユーザーなら "page down" キーを
1270	1270	押すことなく記憶を思い出せるようにするべきです。
1271	1271	読者が文書を読み進めるにつれて、徐々に多くの量の知識を受け取ります。
1272	1272
1273	1273	=begin original
1274	1274
1275	1275	The recommended order of sections in Perl module documentation is:
1276	1276
1277	1277	=end original
1278	1278
1279	1279	推奨する Perl モジュール文書の章の順序は:
1280	1280
1281	1281	=over 4
1282	1282
1283	1283	=item *
1284	1284
1285	1285	NAME
1286	1286
1287	1287	=item *
1288	1288
1289	1289	SYNOPSIS
1290	1290
1291	1291	=item *
1292	1292
1293	1293	DESCRIPTION
1294	1294
1295	1295	=item *
1296	1296
1297	1297	=begin original
1298	1298
1299	1299	One or more sections or subsections giving greater detail of available
1300	1300	methods and routines and any other relevant information.
1301	1301
1302	1302	=end original
1303	1303
1304	1304	利用可能なメソッドやルーチンのより詳細と、その他の関係する情報のための
1305	1305	一つまたは複数の節。
1306	1306
1307	1307	=item *
1308	1308
1309	1309	=begin original
1310	1310
1311	1311	BUGS/CAVEATS/etc
1312	1312
1313	1313	=end original
1314	1314
1315	1315	BUGS/CAVEATS など
1316	1316
1317	1317	=item *
1318	1318
1319	1319	AUTHOR
1320	1320
1321	1321	=item *
1322	1322
1323	1323	SEE ALSO
1324	1324
1325	1325	=item *
1326	1326
1327	1327	=begin original
1328	1328
1329	1329	COPYRIGHT and LICENSE
1330	1330
1331	1331	=end original
1332	1332
1333	1333	COPYRIGHT と LICENSE
1334	1334
1335	1335	=back
1336	1336
1337	1337	=begin original
1338	1338
1339	1339	Keep your documentation near the code it documents ("inline"
1340	1340	documentation). Include POD for a given method right above that
1341	1341	method's subroutine. This makes it easier to keep the documentation up
1342	1342	to date, and avoids having to document each piece of code twice (once in
1343	1343	POD and once in comments).
1344	1344
1345	1345	=end original
1346	1346
1347	1347	文書は、記述しているコードの近くになるように(「インライン」文書)
1348	1348	維持してください。
1349	1349	メソッドのための POD はメソッドのサブルーチンの直前に書いてください。
1350	1350	これにより文書を最新に保つのが容易になり、一つのコードに対して 2 箇所
1351	1351	(POD とコメント) に書く必要がなくなります。
1352	1352
1353	1353	=head2 README, INSTALL, release notes, changelogs
1354	1354
1355	1355	(README, INSTALL, リリースノート, changelogs)
1356	1356
1357	1357	=begin original
1358	1358
1359	1359	Your module should also include a README file describing the module and
1360	1360	giving pointers to further information (website, author email).
1361	1361
1362	1362	=end original
1363	1363
1364	1364	モジュールには、モジュールの説明と、さらなる情報へのポインタ (ウェブサイト、
1365	1365	作者への email) を記述した README ファイルも含めるべきです。
1366	1366
1367	1367	=begin original
1368	1368
1369	1369	An INSTALL file should be included, and should contain simple installation
1370	1370	instructions. When using ExtUtils::MakeMaker this will usually be:
1371	1371
1372	1372	=end original
1373	1373
1374	1374	INSTALL ファイルを含めて、そこに簡単なインストール手順を記述するべきです。
1375	1375	ExtUtils::MakeMaker を使っているなら、これは普通は以下のようになります:
1376	1376
1377	1377	=over 4
1378	1378
1379	1379	=item perl Makefile.PL
1380	1380
1381	1381	=item make
1382	1382
1383	1383	=item make test
1384	1384
1385	1385	=item make install
1386	1386
1387	1387	=back
1388	1388
1389	1389	=begin original
1390	1390
1391	1391	When using Module::Build, this will usually be:
1392	1392
1393	1393	=end original
1394	1394
1395	1395	Module::Build を使っているなら、これは普通は以下のようになります:
1396	1396
1397	1397	=over 4
1398	1398
1399	1399	=item perl Build.PL
1400	1400
1401	1401	=item perl Build
1402	1402
1403	1403	=item perl Build test
1404	1404
1405	1405	=item perl Build install
1406	1406
1407	1407	=back
1408	1408
1409	1409	=begin original
1410	1410
1411	1411	Release notes or changelogs should be produced for each release of your
1412	1412	software describing user-visible changes to your module, in terms
1413	1413	relevant to the user.
1414	1414
1415	1415	=end original
1416	1416
1417	1417	リリースノートまたは changelogs は、ユーザーからの観点でモジュールの
1418	1418	ユーザーから見える変更点を記述して、リリース毎に作成するべきです。
1419
1420		=begin original
1421
1422		Unless you have good reasons for using some other format
1423		(for example, a format used within your company),
1424		the convention is to name your changelog file C<Changes>,
1425		and to follow the simple format described in L<CPAN::Changes::Spec>.
1426
1427		=end original
1428
1429		他の形式を使う良い理由 (例えば、会社で使われている形式) がない限り、
1430		変更履歴ファイルは C<Changes> という名前にして、L<CPAN::Changes::Spec> に
1431		ある単純な形式に従うのが慣習です。
1432	1419
1433	1420	=head1 RELEASE CONSIDERATIONS
1434	1421
1435	1422	=head2 Version numbering
1436	1423
1437	1424	(バージョン番号)
1438	1425
1439	1426	=begin original
1440	1427
1441	1428	Version numbers should indicate at least major and minor releases, and
1442	1429	possibly sub-minor releases. A major release is one in which most of
1443	1430	the functionality has changed, or in which major new functionality is
1444	1431	added. A minor release is one in which a small amount of functionality
1445	1432	has been added or changed. Sub-minor version numbers are usually used
1446	1433	for changes which do not affect functionality, such as documentation
1447	1434	patches.
1448	1435
1449	1436	=end original
1450	1437
1451	1438	バージョン番号は少なくともメジャーリリースとマイナーリリース、そして
1452	1439	場合により副マイナーリリースを示すべきです。
1453	1440	メジャーリリースは、主な機能の変更や、あるいは主な新機能が
1454	1441	追加です。
1455	1442	マイナーリリースは機能の一部の追加や修正です。
1456	1443	副マイナーバージョン番号は普通、文書パッチのような機能に影響を与えない
1457	1444	変更に使われます。
1458	1445
1459	1446	=begin original
1460	1447
1461	1448	The most common CPAN version numbering scheme looks like this:
1462	1449
1463	1450	=end original
1464	1451
1465	1452	最も一般的な CPAN のバージョン番号付け方式は次のようなものです:
1466	1453
1467	1454	1.00, 1.10, 1.11, 1.20, 1.30, 1.31, 1.32
1468	1455
1469	1456	=begin original
1470	1457
1471	1458	A correct CPAN version number is a floating point number with at least
1472	1459	2 digits after the decimal. You can test whether it conforms to CPAN by
1473	1460	using
1474	1461
1475	1462	=end original
1476	1463
1477	1464	正しい CPAN バージョン番号は、小数点の後に少なくとも 2 桁の数字がある
1478	1465	浮動小数点数です。
1479	1466	CPAN に準拠しているかどうかは以下のようにしてテストできます
1480	1467
1481	1468	perl -MExtUtils::MakeMaker -le 'print MM->parse_version(shift)' 'Foo.pm'
1482	1469
1483	1470	=begin original
1484	1471
1485	1472	If you want to release a 'beta' or 'alpha' version of a module but
1486	1473	don't want CPAN.pm to list it as most recent use an '_' after the
1487	1474	regular version number followed by at least 2 digits, eg. 1.20_01. If
1488	1475	you do this, the following idiom is recommended:
1489	1476
1490	1477	=end original
1491	1478
1492	1479	「ベータ」あるいは「アルファ」バージョンのモジュールをリリースしたいけれども
1493	1480	CPAN.pm に最新版として扱ってほしくない場合、通常のバージョン番号の
1494	1481	後に '_' を使い、引き続いて最低 2 桁の数字を付けます; 例えば 1.20_01。
1495	1482	こうするなら、以下の慣用句が推奨されます:
1496	1483
1497	1484	$VERSION = "1.12_01";
1498	1485	$XS_VERSION = $VERSION; # only needed if you have XS code
1499	1486	$VERSION = eval $VERSION;
1500	1487
1501	1488	=begin original
1502	1489
1503	1490	With that trick MakeMaker will only read the first line and thus read
1504	1491	the underscore, while the perl interpreter will evaluate the $VERSION
1505	1492	and convert the string into a number. Later operations that treat
1506	1493	$VERSION as a number will then be able to do so without provoking a
1507	1494	warning about $VERSION not being a number.
1508	1495
1509	1496	=end original
1510	1497
1511	1498	この小技を使うと、MakeMaker は最初の行だけを読むので下線付きで読み、
1512	1499	一方 perl インタプリタは $VERSION を eval して文字列を数値に変換します。
1513	1500	これにより、後の操作で $VERSION を数値として扱うものがあっても
1514	1501	$VERSION が数値でないという警告が出なくなります。
1515	1502
1516	1503	=begin original
1517	1504
1518	1505	Never release anything (even a one-word documentation patch) without
1519	1506	incrementing the number. Even a one-word documentation patch should
1520	1507	result in a change in version at the sub-minor level.
1521	1508
1522	1509	=end original
1523	1510
1524	1511	(たとえ 1 文字の文書パッチでも)バージョン番号を増やすことなく何かを
1525	1512	リリースしてはいけません。
1526	1513	1 文字の文書パッチであっても副マイナー番号を変更するべきです。
1527	1514
1528	1515	=head2 Pre-requisites
1529	1516
1530	1517	(依存)
1531	1518
1532	1519	=begin original
1533	1520
1534	1521	Module authors should carefully consider whether to rely on other
1535	1522	modules, and which modules to rely on.
1536	1523
1537	1524	=end original
1538	1525
1539	1526	モジュール作者は、他のモジュールに依存するかどうか、どのモジュールに
1540	1527	依存するかについて注意深く考慮するべきです。
1541	1528
1542	1529	=begin original
1543	1530
1544	1531	Most importantly, choose modules which are as stable as possible. In
1545	1532	order of preference:
1546	1533
1547	1534	=end original
1548	1535
1549	1536	もっとも重要なこととして、できるだけ安定しているモジュールを選んでください。
1550	1537	優先順位としては:
1551	1538
1552	1539	=over 4
1553	1540
1554	1541	=item *
1555	1542
1556	1543	=begin original
1557	1544
1558	1545	Core Perl modules
1559	1546
1560	1547	=end original
1561	1548
1562	1549	コア Perl モジュール
1563	1550
1564	1551	=item *
1565	1552
1566	1553	=begin original
1567	1554
1568	1555	Stable CPAN modules
1569	1556
1570	1557	=end original
1571	1558
1572	1559	安定している CPAN モジュール
1573	1560
1574	1561	=item *
1575	1562
1576	1563	=begin original
1577	1564
1578	1565	Unstable CPAN modules
1579	1566
1580	1567	=end original
1581	1568
1582	1569	不安定な CPAN モジュール
1583	1570
1584	1571	=item *
1585	1572
1586	1573	=begin original
1587	1574
1588	1575	Modules not available from CPAN
1589	1576
1590	1577	=end original
1591	1578
1592	1579	CPAN から利用できないモジュール
1593	1580
1594	1581	=back
1595	1582
1596	1583	=begin original
1597	1584
1598	1585	Specify version requirements for other Perl modules in the
1599	1586	pre-requisites in your Makefile.PL or Build.PL.
1600	1587
1601	1588	=end original
1602	1589
1603	1590	Makefile.PL か Build.PL の pre-requisites に、他の Perl モジュールの
1604	1591	必要バージョンを指定します。
1605	1592
1606	1593	=begin original
1607	1594
1608	1595	Be sure to specify Perl version requirements both in Makefile.PL or
1609	1596	Build.PL and with C<require 5.6.1> or similar. See the section on
1610	1597	C<use VERSION> of L<perlfunc/require> for details.
1611	1598
1612	1599	=end original
1613	1600
1614	1601	Makefile.PL や Build.PL と、C<require 5.6.1> のような形の両方で、
1615	1602	Perl の必要バージョンを指定します。
1616	1603	詳しくは L<perlfunc/require> の C<use VERSION> の節を参照してください。
1617	1604
1618	1605	=head2 Testing
1619	1606
1620	1607	(テスト)
1621	1608
1622	1609	=begin original
1623	1610
1624	1611	All modules should be tested before distribution (using "make disttest"),
1625	1612	and the tests should also be available to people installing the modules
1626	1613	(using "make test").
1627	1614	For Module::Build you would use the C<make test> equivalent C<perl Build test>.
1628	1615
1629	1616	=end original
1630	1617
1631	1618	全てのモジュールは配布する前に ("make disttest" を使って)
1632	1619	テストされるべきですし、テストはモジュールをインストールしようとしている
1633	1620	人々によっても ("make test" を使って) 実行可能であるべきです。
1634	1621	Module::Build の場合は C<make test> の等価物である C<perl Build test> を
1635	1622	使います。
1636	1623
1637	1624	=begin original
1638	1625
1639	1626	The importance of these tests is proportional to the alleged stability of a
1640	1627	module. A module which purports to be stable or which hopes to achieve wide
1641	1628	use should adhere to as strict a testing regime as possible.
1642	1629
1643	1630	=end original
1644	1631
1645	1632	これらのテストの重要性はモジュールの安定性に比例します。
1646	1633	安定していると表明したり、広く使われることを望むモジュールは、できるだけ
1647	1634	厳密なテスト体制に固執するべきです。
1648	1635
1649	1636	=begin original
1650	1637
1651	1638	Useful modules to help you write tests (with minimum impact on your
1652	1639	development process or your time) include Test::Simple, Carp::Assert
1653	1640	and Test::Inline.
1654	1641	For more sophisticated test suites there are Test::More and Test::MockObject.
1655	1642
1656	1643	=end original
1657	1644
1658	1645	(開発プロセスや時間に与える影響を最小限にするように) テストを書くのを助ける
1659	1646	モジュールには Test::Simple, Carp::Assert, Test::Inline などがあります。
1660	1647	さらに洗練されたテストスイートは Test::More と Test::MockObject です。
1661	1648
1662	1649	=head2 Packaging
1663	1650
1664	1651	(パッケージング)
1665	1652
1666	1653	=begin original
1667	1654
1668	1655	Modules should be packaged using one of the standard packaging tools.
1669	1656	Currently you have the choice between ExtUtils::MakeMaker and the
1670	1657	more platform independent Module::Build, allowing modules to be installed in a
1671	1658	consistent manner.
1672	1659	When using ExtUtils::MakeMaker, you can use "make dist" to create your
1673	1660	package. Tools exist to help you to build your module in a MakeMaker-friendly
1674	1661	style. These include ExtUtils::ModuleMaker and h2xs. See also L<perlnewmod>.
1675	1662
1676	1663	=end original
1677	1664
1678	1665	モジュールは標準的なパッケージングツールの一つを使って
1679	1666	パッケージ化するべきです。
1680	1667	現在のところ、ExtUtils::MakeMaker および、よりプラットフォーム独立で、
1681	1668	一貫した方法でモジュールをインストールできる Module::Build という選択肢が
1682	1669	あります。
1683	1670	ExtUtils::MakeMaker を使うときは、パッケージを作るには "make dist" を
1684	1671	使います。
1685	1672	MakeMaker 風のスタイルでモジュールをビルドするのを助けるツールがあります。
1686	1673	これらには ExtUtils::ModuleMaker や h2xs などがあります。
1687	1674	L<perlnewmod> も参照してください。
1688	1675
1689	1676	=head2 Licensing
1690	1677
1691	1678	(ライセンス)
1692	1679
1693	1680	=begin original
1694	1681
1695	1682	Make sure that your module has a license, and that the full text of it
1696	1683	is included in the distribution (unless it's a common one and the terms
1697	1684	of the license don't require you to include it).
1698	1685
1699	1686	=end original
1700	1687
1701	1688	モジュールにはライセンスを付け、(そのライセンスが一般的なもので、
1702	1689	そのライセンスがライセンスの全文を配布物に含めることを要求していないのでない
1703	1690	限り)、その全文を配布に含めるようにしてください。
1704	1691
1705	1692	=begin original
1706	1693
1707	1694	If you don't know what license to use, dual licensing under the GPL
1708	1695	and Artistic licenses (the same as Perl itself) is a good idea.
1709	1696	See L<perlgpl> and L<perlartistic>.
1710	1697
1711	1698	=end original
1712	1699
1713	1700	もしどのライセンスを使えばいいかわからない場合は、GPL と
1714	1701	Artistic licenses のデュアルライセンス (Perl 自身と同じ) にするというのが
1715	1702	いい考えです。
1716	1703	L<perlgpl> と L<perlartistic> を参照してください。
1717	1704
1718	1705	=head1 COMMON PITFALLS
1719	1706
1720	1707	(よくある落とし穴)
1721	1708
1722	1709	=head2 Reinventing the wheel
1723	1710
1724	1711	(車輪の再発明)
1725	1712
1726	1713	=begin original
1727	1714
1728	1715	There are certain application spaces which are already very, very well
1729	1716	served by CPAN. One example is templating systems, another is date and
1730	1717	time modules, and there are many more. While it is a rite of passage to
1731	1718	write your own version of these things, please consider carefully
1732	1719	whether the Perl world really needs you to publish it.
1733	1720
1734	1721	=end original
1735	1722
1736	1723	CPAN によって提供されている、すでにとてもとてもうまくいっている
1737	1724	アプリケーション分野もあります。
1738	1725	例としてはテンプレートシステムや日付と時間のためのモジュールであり、
1739	1726	その他にもたくさんあります。
1740	1727	これらのものの自分専用版を書くというのは通過儀礼ではありますが、
1741	1728	あなたがそれを公開することを Perl の世界が本当に必要としているかどうかを
1742	1729	慎重に検討してください。
1743	1730
1744	1731	=head2 Trying to do too much
1745	1732
1746	1733	(やりすぎ)
1747	1734
1748	1735	=begin original
1749	1736
1750	1737	Your module will be part of a developer's toolkit. It will not, in
1751	1738	itself, form the B<entire> toolkit. It's tempting to add extra features
1752	1739	until your code is a monolithic system rather than a set of modular
1753	1740	building blocks.
1754	1741
1755	1742	=end original
1756	1743
1757	1744	あなたのモジュールは開発者のツールキットの一部です。
1758	1745	ツールキット B<全体> ではありません。
1759	1746	これはあなたのコードをモジュール化された建築ブロックではなく一枚岩のシステムに
1760	1747	なるまで余分な機能を追加しようとする誘惑です。
1761	1748
1762	1749	=head2 Inappropriate documentation
1763	1750
1764	1751	(不適切な文書)
1765	1752
1766	1753	=begin original
1767	1754
1768	1755	Don't fall into the trap of writing for the wrong audience. Your
1769	1756	primary audience is a reasonably experienced developer with at least
1770	1757	a moderate understanding of your module's application domain, who's just
1771	1758	downloaded your module and wants to start using it as quickly as possible.
1772	1759
1773	1760	=end original
1774	1761
1775	1762	間違った読者に向けて書くという罠に陥らないでください。
1776	1763	主な読者は、少なくともモジュールの適用分野についてある程度の理解のある
1777	1764	適度に経験を積んだ開発者で、単にモジュールをダウンロードして、できるだけ
1778	1765	早く使い始めたいと思っている人々です。
1779	1766
1780	1767	=begin original
1781	1768
1782	1769	Tutorials, end-user documentation, research papers, FAQs etc are not
1783	1770	appropriate in a module's main documentation. If you really want to
1784	1771	write these, include them as sub-documents such as C<My::Module::Tutorial> or
1785	1772	C<My::Module::FAQ> and provide a link in the SEE ALSO section of the
1786	1773	main documentation.
1787	1774
1788	1775	=end original
1789	1776
1790	1777	チュートリアル、エンドユーザー向け文書、研究論文、FAQ などはモジュールの
1791	1778	主文書としては不適切です。
1792	1779	どうしてもこれらのものを書きたいなら、C<My::Module::Tutorial> や
1793	1780	C<My::Module::FAQ> のような副文書として含めて、主文書の SEE ALSO 節に
1794	1781	リンクをつけてください。
1795	1782
1796	1783	=head1 SEE ALSO
1797	1784
1798	1785	=over 4
1799	1786
1800	1787	=item L<perlstyle>
1801	1788
1802	1789	=begin original
1803	1790
1804	1791	General Perl style guide
1805	1792
1806	1793	=end original
1807	1794
1808	1795	一般的な Perl スタイルガイド
1809	1796
1810	1797	=item L<perlnewmod>
1811	1798
1812	1799	=begin original
1813	1800
1814	1801	How to create a new module
1815	1802
1816	1803	=end original
1817	1804
1818	1805	新しいモジュールの作り方
1819	1806
1820	1807	=item L<perlpod>
1821	1808
1822	1809	=begin original
1823	1810
1824	1811	POD documentation
1825	1812
1826	1813	=end original
1827	1814
1828	1815	POD 文書
1829	1816
1830	1817	=item L<podchecker>
1831	1818
1832	1819	=begin original
1833	1820
1834	1821	Verifies your POD's correctness
1835	1822
1836	1823	=end original
1837	1824
1838	1825	POD の正しさを検証する
1839	1826
1840	1827	=item Packaging Tools
1841	1828
1842	1829	(パッケージングツール)
1843	1830
1844	1831	L<ExtUtils::MakeMaker>, L<Module::Build>
1845	1832
1846	1833	=item Testing tools
1847	1834
1848	1835	(テストツール)
1849	1836
1850	1837	L<Test::Simple>, L<Test::Inline>, L<Carp::Assert>, L<Test::More>, L<Test::MockObject>
1851	1838
1852	1839	=item http://pause.perl.org/
1853	1840
1854	1841	=begin original
1855	1842
1856	1843	Perl Authors Upload Server. Contains links to information for module
1857	1844	authors.
1858	1845
1859	1846	=end original
1860	1847
1861	1848	Perl Authors Upload Server。
1862	1849	モジュール作者のための情報へのリンクがあります。
1863	1850
1864	1851	=item Any good book on software engineering
1865	1852
1866	1853	(ソフトウェア工学に関する良い本はなんでも)
1867	1854
1868	1855	=back
1869	1856
1870	1857	=head1 AUTHOR
1871	1858
1872	1859	Kirrily "Skud" Robert <skud@cpan.org>
1873	1860
1874	1861	=begin meta
1875	1862
1876	1863	Translate: 山科氷魚 (YAMASHINA Hio) <hio@hio.jp> (5.10.0)
1877	1864	Update: SHIRAKATA Kentaro <argrath@ub32.org> (5.10.1-)
1878	1865	Status: completed
1879	1866
1880	1867	=end meta

Powered by Amon2, 翻訳, サイト. Operated by Japan Perl Association