perlmodstyle - Dalam talian di Awan

JADUAL:

NAMA

perlmodstyle - Panduan gaya modul Perl

PENGENALAN

Dokumen ini cuba menerangkan "amalan terbaik" Komuniti Perl untuk menulis Perl
modul. Ia melanjutkan pengesyoran yang terdapat dalam perlstyle , yang harus dipertimbangkan
membaca yang diperlukan sebelum membaca dokumen ini.

Walaupun dokumen ini bertujuan untuk berguna kepada semua pengarang modul, ia terutamanya
ditujukan kepada pengarang yang ingin menerbitkan modul mereka di CPAN.

Tumpuan adalah pada elemen gaya yang boleh dilihat oleh pengguna modul, bukannya
bahagian yang hanya dilihat oleh pembangun modul. Walau bagaimanapun, banyak daripada
garis panduan yang dibentangkan dalam dokumen ini boleh diekstrapolasi dan digunakan dengan jayanya untuk a
dalaman modul.

Dokumen ini berbeza daripada perlnewmod kerana ia adalah panduan gaya dan bukannya tutorial
untuk mencipta modul CPAN. Ia menyediakan senarai semak terhadap modul yang boleh dibandingkan
untuk menentukan sama ada mereka mematuhi amalan terbaik, tanpa perlu menerangkannya
terperinci bagaimana untuk mencapai ini.

Semua nasihat yang terkandung dalam dokumen ini telah diperolehi daripada perbualan yang meluas
dengan pengarang dan pengguna CPAN yang berpengalaman. Setiap nasihat yang diberikan di sini adalah hasilnya
daripada kesilapan sebelumnya. Maklumat ini ada di sini untuk membantu anda mengelakkan kesilapan yang sama dan
kerja tambahan yang pasti akan diperlukan untuk memperbaikinya.

Bahagian pertama dokumen ini menyediakan senarai semak terperinci; bahagian seterusnya
menyediakan perbincangan yang lebih terperinci tentang item dalam senarai. Bahagian akhir, "Biasa
Perangkap", menerangkan beberapa kesilapan paling popular yang dibuat oleh pengarang CPAN.

CEPAT CHECKLIST

Untuk butiran lanjut tentang setiap item dalam senarai semak ini, lihat di bawah.

Sebelum anda permulaan
· Jangan cipta semula roda

· Tampal, lanjutkan atau subkelaskan modul sedia ada jika boleh

· Lakukan satu perkara dan lakukan dengan baik

· Pilih nama yang sesuai

· Dapatkan maklum balas sebelum diterbitkan

. API
· API harus difahami oleh pengaturcara biasa

· Kaedah mudah untuk tugasan mudah

· Asingkan fungsi daripada output

· Penamaan subrutin atau kaedah yang konsisten

· Gunakan parameter bernama (cincang atau cincang) apabila terdapat lebih daripada dua parameter

Kestabilan
· Pastikan modul anda berfungsi di bawah "use strict" dan "-w"

· Modul yang stabil harus mengekalkan keserasian ke belakang

dokumentasi
· Tulis dokumentasi dalam POD

· Dokumen tujuan, skop dan aplikasi sasaran

· Dokumentasikan setiap kaedah atau subrutin yang boleh diakses secara umum, termasuk param dan pemulangan
nilai

· Berikan contoh penggunaan dalam dokumentasi anda

· Menyediakan fail README dan mungkin juga mengeluarkan nota, changelog, dsb

· Menyediakan pautan ke maklumat lanjut (URL, e-mel)

Lepaskan pertimbangan
· Tentukan pra-syarat dalam Makefile.PL atau Build.PL

· Tentukan keperluan versi Perl dengan "penggunaan"

· Sertakan ujian dengan modul anda

· Pilih skema penomboran versi yang wajar dan konsisten (X.YY ialah Perl biasa
skema penomboran modul)

· Tambah nombor versi untuk setiap perubahan, tidak kira betapa kecilnya

· Pakej modul menggunakan "make dist"

· Pilih lesen yang sesuai (GPL/Artistic ialah lalai yang baik)

SEBELUM ANDA MULA MENJAGA A MODULE

Cuba untuk tidak melancarkan pembangunan modul anda tanpa meluangkan sedikit masa untuk berfikir
pertama. Sedikit pemikiran awal mungkin menjimatkan banyak usaha anda di kemudian hari.

Mempunyai it menjadi dilakukan sebelum?
Anda mungkin tidak perlu menulis modul. Semak sama ada ia telah dilakukan di Perl,
dan elakkan mencipta semula roda melainkan anda mempunyai alasan yang kukuh.

Tempat yang baik untuk mencari modul sedia ada termasukhttp://search.cpan.org/> dan
dan bertanya pada "[e-mel dilindungi]"
(<http://lists.perl.org/list/module-authors.html>).

Jika modul sedia ada hampir lakukan apa yang anda mahu, pertimbangkan untuk menulis tampalan, menulis a
subkelas, atau sebaliknya melanjutkan modul sedia ada dan bukannya menulis semula.

Do 1 perkara and do it baik
Dengan risiko menyatakan yang jelas, modul bertujuan untuk menjadi modular. Pembangun Perl
seharusnya boleh menggunakan modul untuk menyusun blok bangunan aplikasi mereka.
Walau bagaimanapun, adalah penting bahawa blok adalah bentuk yang betul, dan bahawa pembangun
tidak sepatutnya menggunakan blok besar sedangkan yang mereka perlukan hanyalah blok kecil.

Modul anda harus mempunyai skop yang jelas yang tidak lebih daripada satu ayat.
Bolehkah modul anda dipecahkan kepada kumpulan modul yang berkaitan?

Contoh buruk:

"FooBar.pm menyediakan pelaksanaan protokol FOO dan standard BAR yang berkaitan."

Contoh yang baik:

"Foo.pm menyediakan pelaksanaan protokol FOO. Bar.pm melaksanakan BAR berkaitan
protokol."

Ini bermakna jika pembangun hanya memerlukan modul untuk standard BAR, mereka tidak sepatutnya
terpaksa memasang perpustakaan untuk FOO juga.

Apa itu in a nama?
Pastikan anda memilih nama yang sesuai untuk modul anda lebih awal. Ini akan membantu orang ramai
cari dan ingat modul anda, dan buat pengaturcaraan dengan modul anda lebih intuitif.

Apabila menamakan modul anda, pertimbangkan perkara berikut:

· Bersifat deskriptif (iaitu menerangkan dengan tepat tujuan modul).

· Selaras dengan modul sedia ada.

· Mencerminkan kefungsian modul, bukan pelaksanaan.

· Elakkan memulakan hierarki peringkat atasan baharu, terutamanya jika hierarki yang sesuai sudah pun
wujud di mana anda boleh meletakkan modul anda.

Dapatkan maklum balas sebelum penerbitan
Jika anda tidak pernah memuat naik modul ke CPAN sebelum ini (dan walaupun anda ada), anda akan melakukannya
amat digalakkan untuk mendapatkan maklum balas mengenai PrePANhttp://prepan.org>. PrePAN ialah tapak
berdedikasi untuk membincangkan idea untuk modul CPAN dengan pembangun Perl yang lain dan ianya bagus
sumber untuk pembangun Perl baharu (dan berpengalaman).

Anda juga harus cuba mendapatkan maklum balas daripada orang yang sudah biasa dengan modul tersebut
domain aplikasi dan sistem penamaan CPAN. Pengarang modul atau modul yang serupa
dengan nama yang serupa, mungkin tempat yang baik untuk bermula, begitu juga tapak komuniti seperti Perl Monks
<http://www.perlmonks.org>.

MEREKA BENTUK DAN MENJAGA ANDA MODULE

Pertimbangan untuk reka bentuk modul dan pengekodan:

Untuk OO or tidak kepada OO?
Modul anda mungkin berorientasikan objek (OO) atau tidak, atau ia mungkin mempunyai kedua-dua jenis antara muka
tersedia. Terdapat kebaikan dan keburukan setiap teknik, yang harus dipertimbangkan apabila anda
reka bentuk API anda.

In Perl Best Amalan (hak cipta 2004, Diterbitkan oleh O'Reilly Media, Inc.), Damian Conway
menyediakan senarai kriteria untuk digunakan apabila memutuskan sama ada OO sesuai untuk masalah anda:

· Sistem yang direka bentuk adalah besar, atau berkemungkinan besar.

· Data boleh diagregatkan ke dalam struktur yang jelas, terutamanya jika terdapat besar
jumlah data dalam setiap agregat.

· Pelbagai jenis agregat data membentuk hierarki semula jadi yang memudahkan penggunaan
pewarisan dan polimorfisme.

· Anda mempunyai sekeping data di mana banyak operasi berbeza digunakan.

· Anda perlu melakukan operasi umum yang sama pada jenis data yang berkaitan, tetapi dengan
sedikit variasi bergantung pada jenis data tertentu operasi digunakan
kepada.

· Kemungkinan besar anda perlu menambah jenis data baharu kemudian.

· Interaksi tipikal antara kepingan data paling baik diwakili oleh pengendali.

· Pelaksanaan komponen individu sistem mungkin akan berubah
pada bila-bila masa.

· Reka bentuk sistem sudah berorientasikan objek.

· Sebilangan besar pengaturcara lain akan menggunakan modul kod anda.

Fikirkan dengan teliti sama ada OO sesuai untuk modul anda. Objek percuma
orientasi menghasilkan API kompleks yang sukar untuk pengguna modul purata
faham atau gunakan.

Merekabentuk Matlamat API
Antara muka anda harus difahami oleh pengaturcara Perl biasa. Yang berikut
garis panduan boleh membantu anda menilai sama ada API anda cukup mudah:

Tulis rutin mudah untuk melakukan perkara mudah.
Adalah lebih baik untuk mempunyai banyak rutin mudah daripada beberapa rutin yang monolitik. Jika anda
rutin mengubah tingkah lakunya dengan ketara berdasarkan hujahnya, ia adalah tanda bahawa
anda sepatutnya mempunyai dua (atau lebih) rutin yang berasingan.

Asingkan fungsi daripada output.
Kembalikan hasil anda dalam bentuk paling generik yang mungkin dan benarkan pengguna memilih caranya
untuk menggunakannya. Bentuk paling generik yang mungkin biasanya adalah struktur data Perl yang
kemudiannya boleh digunakan untuk menjana laporan teks, HTML, XML, pertanyaan pangkalan data, atau apa sahaja
lain yang diperlukan oleh pengguna anda.

Jika rutin anda berulang melalui beberapa jenis senarai (seperti senarai fail, atau
rekod dalam pangkalan data) anda boleh mempertimbangkan untuk menyediakan panggilan balik supaya pengguna boleh
memanipulasi setiap elemen senarai secara bergilir-gilir. File::Find menyediakan contoh ini
dengan sintaks "find(\&wanted, $dir)".

Sediakan pintasan dan lalai yang wajar.
Jangan memerlukan setiap pengguna modul untuk melompat melalui gelung yang sama untuk mencapai yang mudah
hasil. Anda sentiasa boleh memasukkan parameter atau rutin pilihan untuk lebih kompleks atau
tingkah laku tidak standard. Jika kebanyakan pengguna anda perlu menaip beberapa yang hampir sama
baris kod apabila mereka mula menggunakan modul anda, ini adalah tanda yang sepatutnya anda buat
tingkah laku itu lalai. Satu lagi penunjuk yang baik bahawa anda harus menggunakan lalai ialah jika
kebanyakan pengguna anda memanggil rutin anda dengan hujah yang sama.

Menamakan konvensyen
Penamaan anda harus konsisten. Sebagai contoh, lebih baik untuk mempunyai:

paparan_hari();
paparan_minggu();
paparan_tahun();

daripada

paparan_hari();
week_display();
show_year();

Ini terpakai sama pada nama kaedah, nama parameter, dan apa-apa lagi
kelihatan kepada pengguna (dan kebanyakan perkara yang tidak!)

Parameter melintas
Gunakan parameter bernama. Lebih mudah untuk menggunakan cincang seperti ini:

$obj->buat_sesuatu(
nama => "wibble",
taip => "teks",
saiz => 1024,
);

... daripada mempunyai senarai panjang parameter yang tidak dinamakan seperti ini:

$obj->do_something("wibble", "text", 1024);

Walaupun senarai hujah mungkin berfungsi dengan baik untuk satu, dua atau tiga hujah, mana-mana
lebih banyak hujah menjadi sukar untuk diingati oleh pengguna modul, dan sukar untuk modul
pengarang untuk mengurus. Jika anda ingin menambah parameter baharu, anda perlu menambahkannya pada
akhir senarai untuk keserasian ke belakang, dan ini mungkin akan menjadi senarai anda
perintah tidak intuitif. Selain itu, jika banyak elemen mungkin tidak ditentukan, anda mungkin melihat perkara berikut
panggilan kaedah yang tidak menarik:

$obj->do_something(undef, undef, undef, undef, undef, 1024);

Sediakan lalai yang wajar untuk parameter yang mempunyainya. Jangan jadikan pengguna anda
tentukan parameter yang hampir selalu sama.

Isu sama ada untuk meluluskan hujah dalam hash atau hashref sebahagian besarnya adalah masalah
gaya peribadi.

Penggunaan kekunci cincang bermula dengan tanda sempang ("-nama") atau sepenuhnya dalam huruf besar
("NAME") ialah peninggalan versi lama Perl dengan rentetan huruf kecil biasa
tidak dikendalikan dengan betul oleh pengendali "=>". Walaupun beberapa modul mengekalkan huruf besar
atau kunci hujah bersempang atas sebab sejarah atau sebagai soal gaya peribadi,
kebanyakan modul baharu harus menggunakan kekunci huruf kecil yang mudah. Apa sahaja yang anda pilih, jadilah
konsisten!

Ketegasan and amaran
Modul anda harus berjalan dengan jayanya di bawah pragma yang ketat dan harus berjalan tanpa
menghasilkan sebarang amaran. Modul anda juga harus mengendalikan pemeriksaan taint di mana sesuai,
walaupun ini boleh menyebabkan kesukaran dalam banyak kes.

Ke belakang keserasian
Modul yang "stabil" tidak boleh memecahkan keserasian ke belakang tanpa sekurang-kurangnya a
fasa peralihan yang panjang dan perubahan besar dalam nombor versi.

ralat mengendalikan and mesej
Apabila modul anda menghadapi ralat, ia harus melakukan satu atau lebih daripada:

· Kembalikan nilai yang tidak ditentukan.

· set $Module::errstr atau serupa ("errstr" ialah nama biasa yang digunakan oleh DBI dan lain-lain
modul popular; jika anda memilih sesuatu yang lain, pastikan anda mendokumentasikannya dengan jelas).

· "warn()" atau "carp()" mesej kepada STDERR.

· "croak()" hanya apabila modul anda tidak dapat mengetahui apa yang perlu dilakukan. ("Kuak()"
ialah versi "die()" yang lebih baik untuk digunakan dalam modul, yang melaporkan ralatnya daripada
perspektif pemanggil. Lihat Carp untuk butiran "croak()", "carp()" dan lain-lain
rutin yang berguna.)

· Sebagai alternatif kepada perkara di atas, anda mungkin lebih suka membuang pengecualian menggunakan Ralat
modul.

Pengendalian ralat boleh dikonfigurasikan boleh menjadi sangat berguna kepada pengguna anda. Pertimbangkan untuk menawarkan pilihan
tahap untuk mesej amaran dan nyahpepijat, pilihan untuk menghantar mesej ke fail berasingan, a
cara untuk menentukan rutin pengendalian ralat, atau ciri lain seperti itu. Pastikan anda lalai semua
pilihan ini untuk kegunaan yang paling biasa.

DOKUMENTASI ANDA MODULE

POD
Modul anda harus menyertakan dokumentasi yang ditujukan kepada pembangun Perl. Anda harus menggunakan Perl
"dokumentasi lama biasa" (POD) untuk dokumentasi teknikal am anda, walaupun anda boleh
ingin menulis dokumentasi tambahan (kertas putih, tutorial, dll) dalam beberapa dokumen lain
format. Anda perlu menguasai mata pelajaran berikut:

· Sinopsis kegunaan biasa modul

· Tujuan, skop dan aplikasi sasaran modul anda

· Penggunaan setiap kaedah atau subrutin yang boleh diakses secara umum, termasuk parameter dan
pulangan nilai

· Contoh penggunaan

· Sumber maklumat lanjut

· Alamat e-mel hubungan untuk pengarang/penyelenggara

Tahap perincian dalam dokumentasi modul Perl biasanya berubah daripada kurang terperinci kepada lebih
terperinci. Bahagian SINOPSIS anda harus mengandungi contoh penggunaan minimum (mungkin sebagai
sedikit sebagai satu baris kod; langkau kes penggunaan luar biasa atau apa-apa yang tidak diperlukan oleh kebanyakan orang
pengguna); DESCRIPTION harus menerangkan modul anda dalam istilah yang luas, secara amnya hanya dalam a
beberapa perenggan; lebih terperinci tentang rutin atau kaedah modul, contoh kod yang panjang, atau
bahan lain yang mendalam hendaklah diberikan dalam bahagian seterusnya.

Sebaik-baiknya, seseorang yang agak biasa dengan modul anda seharusnya dapat menyegarkan semula modul anda
ingatan tanpa menekan "halaman bawah". Semasa pembaca anda meneruskan melalui dokumen, mereka
harus menerima jumlah pengetahuan yang semakin bertambah.

Susunan bahagian yang disyorkan dalam dokumentasi modul Perl ialah:

· NAMA

· SINOPSIS

· PENERANGAN

· Satu atau lebih bahagian atau subseksyen memberikan perincian yang lebih terperinci tentang kaedah yang tersedia dan
rutin dan sebarang maklumat lain yang berkaitan.

· PEPIJAT/KAVEAT/dsb

· PENULIS

· LIHAT JUGA

· HAK CIPTA dan LESEN

Simpan dokumentasi anda berhampiran kod yang didokumenkan (dokumentasi "sebaris"). Sertakan POD
untuk kaedah tertentu betul-betul di atas subrutin kaedah itu. Ini menjadikannya lebih mudah untuk menyimpan
dokumentasi terkini, dan mengelak daripada mendokumentasikan setiap keping kod dua kali (sekali masuk
POD dan sekali dalam ulasan).

BACA SAYA, PASANG, melepaskan nota, changelog
Modul anda juga harus memasukkan fail README yang menerangkan modul dan memberi petunjuk kepada
maklumat lanjut (laman web, e-mel pengarang).

Fail INSTALL harus disertakan, dan harus mengandungi arahan pemasangan yang mudah.
Apabila menggunakan ExtUtils::MakeMaker ini biasanya:

perl Makefile.PL
membuat
membuat ujian
membuat memasang

Apabila menggunakan Module::Build, ini biasanya:

perl Build.PL
perl Build
ujian Binaan perl
perl Build install

Nota keluaran atau log perubahan hendaklah dihasilkan untuk setiap keluaran perisian anda
menerangkan perubahan yang boleh dilihat oleh pengguna pada modul anda, dari segi yang berkaitan dengan pengguna.

Melainkan anda mempunyai alasan kukuh untuk menggunakan beberapa format lain (contohnya, format yang digunakan
dalam syarikat anda), konvensyen ini adalah untuk menamakan fail changelog anda "Perubahan", dan kepada
ikut format ringkas yang diterangkan dalam CPAN::Change::Spec.

SIARAN KONSIDERASI

versi penomboran
Nombor versi hendaklah menunjukkan sekurang-kurangnya keluaran besar dan kecil, dan mungkin sub-kecil
keluaran. Keluaran utama ialah keluaran yang kebanyakan fungsi telah berubah, atau masuk
yang mana fungsi baharu utama ditambah. Keluaran kecil ialah keluaran di mana sejumlah kecil
fungsi telah ditambah atau diubah. Nombor versi sub-minor biasanya digunakan untuk
perubahan yang tidak menjejaskan fungsi, seperti tampung dokumentasi.

Skim penomboran versi CPAN yang paling biasa kelihatan seperti ini:

1.00, 1.10, 1.11, 1.20, 1.30, 1.31, 1.32

Nombor versi CPAN yang betul ialah nombor titik terapung dengan sekurang-kurangnya 2 digit selepas
perpuluhan. Anda boleh menguji sama ada ia mematuhi CPAN dengan menggunakan

perl -MExtUtils::MakeMaker -le 'print MM->parse_version(shift)' 'Foo.pm'

Jika anda ingin mengeluarkan versi modul 'beta' atau 'alfa' tetapi tidak mahu CPAN.pm
senaraikannya sebagai penggunaan terkini '_' selepas nombor versi biasa diikuti dengan sekurang-kurangnya 2
digit, cth. 1.20_01. Jika anda melakukan ini, simpulan bahasa berikut disyorkan:

$VERSION = "1.12_01" kami; # jadi pengedaran CPAN akan ada
# nama fail yang betul
$XS_VERSION kami = $VERSION; # hanya diperlukan jika anda mempunyai kod XS
$VERSION = eval $VERSION; # jadi "gunakan Modul 0.002" tidak akan memberi amaran
# garis bawah

Dengan helah itu MakeMaker hanya akan membaca baris pertama dan dengan itu membaca garis bawah,
manakala jurubahasa perl akan menilai $VERSION dan menukar rentetan menjadi a
nombor. Operasi kemudian yang menganggap $VERSION sebagai nombor kemudiannya akan dapat melakukannya
tanpa menimbulkan amaran tentang $VERSION bukan nombor.

Jangan sekali-kali mengeluarkan apa-apa (walaupun tampung dokumentasi satu perkataan) tanpa menambah
nombor. Malah tampung dokumentasi satu perkataan harus menghasilkan perubahan dalam versi di
peringkat bawahan.

Setelah dipilih, adalah penting untuk berpegang pada skema versi anda, tanpa mengurangkan bilangannya
daripada digit. Ini kerana pembungkus "hiliran", seperti sistem port FreeBSD,
mentafsir nombor versi dalam pelbagai cara. Jika anda menukar bilangan digit dalam anda
skema versi, anda boleh mengelirukan sistem ini supaya mereka mengeluarkan versi modul anda
tertib, yang jelas buruk.

Pra-syarat
Penulis modul harus mempertimbangkan dengan teliti sama ada untuk bergantung pada modul lain, dan yang mana
modul untuk bergantung.

Paling penting, pilih modul yang sestabil mungkin. Mengikut keutamaan:

· Modul Teras Perl

· Modul CPAN yang stabil

· Modul CPAN tidak stabil

· Modul tidak tersedia daripada CPAN

Nyatakan keperluan versi untuk modul Perl lain dalam pra-syarat dalam anda
Makefile.PL atau Build.PL.

Pastikan anda menyatakan keperluan versi Perl dalam Makefile.PL atau Build.PL dan dengan
"memerlukan 5.6.1" atau serupa. Lihat bahagian "gunakan VERSI" untuk "memerlukan" dalam perlfunc untuk
butiran.

Ujian
Semua modul harus diuji sebelum pengedaran (menggunakan "make disttest"), dan ujian
juga harus tersedia kepada orang yang memasang modul (menggunakan "membuat ujian"). Untuk
Modul::Bina anda akan menggunakan "membuat ujian" setara "perl Build test".

Kepentingan ujian ini adalah berkadar dengan kestabilan yang dikatakan modul. A
modul yang dikatakan stabil atau yang berharap untuk mencapai penggunaan yang meluas harus mematuhi sebagai
ketatkan rejim ujian yang mungkin.

Modul berguna untuk membantu anda menulis ujian (dengan impak minimum pada proses pembangunan anda atau
masa anda) sertakan Ujian::Simple, Carp::Assert and Test::Inline. Untuk lebih canggih
suite ujian terdapat Test::More dan Test::MockObject.

Sektor Pembungkusan
Modul hendaklah dibungkus menggunakan salah satu alat pembungkusan standard. Pada masa ini anda mempunyai
pilihan antara ExtUtils::MakeMaker dan lebih banyak platform bebas Modul::Build,
membenarkan modul dipasang dengan cara yang konsisten. Apabila menggunakan ExtUtils::MakeMaker,
anda boleh menggunakan "make dist" untuk membuat pakej anda. Alat wujud untuk membantu anda membina
modul dalam gaya mesra MakeMaker. Ini termasuk ExtUtils::ModuleMaker dan h2xs. Lihat
juga perlnewmod.

pelesenan
Pastikan modul anda mempunyai lesen dan teks penuhnya disertakan dalam
pengedaran (melainkan ia adalah yang biasa dan syarat lesen tidak memerlukan anda
sertakan).

Jika anda tidak tahu lesen apa yang hendak digunakan, pelesenan dwi di bawah lesen GPL dan Artistik
(sama seperti Perl sendiri) adalah idea yang bagus. Lihat perlgpl dan perlartistic.

SEMUA ORANG PITFALLS

Mengatur semula yang roda
Terdapat ruang aplikasi tertentu yang telah disediakan dengan sangat baik oleh CPAN.
Satu contoh ialah sistem templat, satu lagi ialah modul tarikh dan masa, dan terdapat banyak
lebih. Walaupun ia adalah satu upacara untuk menulis versi anda sendiri tentang perkara ini, sila
pertimbangkan dengan teliti sama ada dunia Perl benar-benar memerlukan anda untuk menerbitkannya.

cuba kepada do tinggi banyak
Modul anda akan menjadi sebahagian daripada kit alat pembangun. Ia tidak akan, dengan sendirinya, membentuk
keseluruhan kit alat. Sangat menggoda untuk menambah ciri tambahan sehingga kod anda menjadi monolitik
sistem dan bukannya satu set blok binaan modular.

Tidak sesuai dokumentasi
Jangan terjebak dalam perangkap menulis untuk khalayak yang salah. Khalayak utama anda ialah a
pembangun yang cukup berpengalaman dengan sekurang-kurangnya pemahaman sederhana tentang modul anda
domain aplikasi, yang baru memuat turun modul anda dan mahu mula menggunakannya sebagai
secepat mungkin.

Tutorial, dokumentasi pengguna akhir, kertas penyelidikan, Soalan Lazim dan lain-lain adalah tidak sesuai dalam a
dokumentasi utama modul. Jika anda benar-benar ingin menulis ini, masukkannya sebagai sub-
dokumen seperti "My::Module::Tutorial" atau "My::Module::FAQ" dan berikan pautan dalam
LIHAT JUGA bahagian dokumentasi utama.

Gunakan perlmodstyle dalam talian menggunakan perkhidmatan onworks.net