perlmodstyle - ออนไลน์ในคลาวด์

โครงการ:

ชื่อ

perlmodstyle - คำแนะนำสไตล์โมดูล Perl

บทนำ

เอกสารนี้พยายามอธิบาย "แนวทางปฏิบัติที่ดีที่สุด" ของชุมชน Perl สำหรับการเขียน Perl
โมดูล มันขยายคำแนะนำที่พบใน perlstyle ซึ่งควรพิจารณา
ต้องอ่านก่อนอ่านเอกสารนี้

แม้ว่าเอกสารนี้มีจุดมุ่งหมายเพื่อเป็นประโยชน์ต่อผู้เขียนโมดูลทุกคน แต่ก็มีความพิเศษ
มุ่งเป้าไปที่ผู้เขียนที่ต้องการเผยแพร่โมดูลของตนบน CPAN

เน้นที่องค์ประกอบของสไตล์ที่ผู้ใช้โมดูลมองเห็นได้ มากกว่า
ส่วนเหล่านั้นที่นักพัฒนาของโมดูลเห็นเท่านั้น อย่างไรก็ตาม หลายๆ
แนวทางที่นำเสนอในเอกสารนี้สามารถคาดการณ์และนำไปใช้กับ .ได้สำเร็จ
ภายในของโมดูล

เอกสารนี้แตกต่างจาก perlnewmod ตรงที่มันเป็นคู่มือสไตล์มากกว่าการสอน
ในการสร้างโมดูล CPAN มีรายการตรวจสอบที่สามารถเปรียบเทียบโมดูลได้
เพื่อตรวจสอบว่าเป็นไปตามแนวปฏิบัติที่ดีที่สุดหรือไม่ โดยไม่จำเป็นต้องอธิบายใน
รายละเอียดวิธีการบรรลุเป้าหมายนี้

คำแนะนำทั้งหมดในเอกสารนี้รวบรวมมาจากการสนทนาที่กว้างขวาง
กับผู้เขียนและผู้ใช้ CPAN ที่มีประสบการณ์ ทุกคำแนะนำที่ให้ไว้นี้คือผลลัพธ์
ของความผิดพลาดครั้งก่อน ข้อมูลนี้มีไว้เพื่อช่วยให้คุณหลีกเลี่ยงข้อผิดพลาดเดียวกันและ
งานพิเศษที่จะต้องแก้ไขอย่างหลีกเลี่ยงไม่ได้

ส่วนแรกของเอกสารนี้มีรายการตรวจสอบแยกรายการ ตอนต่อไป
ให้การอภิปรายรายละเอียดเพิ่มเติมของรายการในรายการ ส่วนสุดท้าย "สามัญ
Pitfalls" อธิบายถึงข้อผิดพลาดที่ได้รับความนิยมมากที่สุดโดยผู้เขียน CPAN

QUICK รายการตรวจสอบ

สำหรับรายละเอียดเพิ่มเติมเกี่ยวกับแต่ละรายการในรายการตรวจสอบนี้ โปรดดูที่ด้านล่าง

ก่อน เธอ เริ่มต้น
· อย่าประดิษฐ์วงล้อขึ้นใหม่

· แพตช์ ขยายหรือคลาสย่อยของโมดูลที่มีอยู่หากเป็นไปได้

· ทำสิ่งใดสิ่งหนึ่งแล้วทำให้ดี

· เลือกชื่อที่เหมาะสม

·รับข้อเสนอแนะก่อนเผยแพร่

เค้ก API
· API ควรจะเข้าใจได้โดยโปรแกรมเมอร์ทั่วไป

· วิธีง่ายๆ สำหรับงานง่ายๆ

·แยกการทำงานออกจากเอาท์พุท

· การตั้งชื่อรูทีนหรือเมธอดย่อยอย่างสม่ำเสมอ

· ใช้พารามิเตอร์ที่มีชื่อ (hash หรือ hashref) เมื่อมีพารามิเตอร์มากกว่าสองตัว

Stability
· ตรวจสอบให้แน่ใจว่าโมดูลของคุณทำงานภายใต้ "ใช้เข้มงวด" และ "-w"

· โมดูลที่เสถียรควรรักษาความเข้ากันได้แบบย้อนหลัง

เอกสาร
· เขียนเอกสารใน POD

· เอกสารวัตถุประสงค์ ขอบเขต และการใช้งานเป้าหมาย

· จัดทำเอกสารแต่ละวิธีการเข้าถึงแบบสาธารณะหรือรูทีนย่อย รวมถึงพารามิเตอร์และการส่งคืน
ค่า

· ให้ตัวอย่างการใช้งานในเอกสารของคุณ

· จัดเตรียมไฟล์ README และอาจรวมถึงบันทึกประจำรุ่น บันทึกการเปลี่ยนแปลง ฯลฯ

· ระบุลิงก์ไปยังข้อมูลเพิ่มเติม (URL, อีเมล)

ปล่อย การพิจารณา
· ระบุข้อกำหนดเบื้องต้นใน Makefile.PL หรือ Build.PL

· ระบุข้อกำหนดเวอร์ชัน Perl ด้วย "ใช้"

· รวมการทดสอบกับโมดูลของคุณ

· เลือกรูปแบบการกำหนดหมายเลขรุ่นที่สมเหตุสมผลและสอดคล้องกัน (X.YY คือ Perl . ทั่วไป
รูปแบบการนับโมดูล)

· เพิ่มหมายเลขเวอร์ชันสำหรับทุกการเปลี่ยนแปลง ไม่ว่าจะเล็กน้อยเพียงใด

· บรรจุโมดูลโดยใช้ "make dist"

· เลือกใบอนุญาตที่เหมาะสม (GPL/Artistic เป็นค่าเริ่มต้นที่ดี)

ก่อน คุณ เริ่มต้น การเขียน A โมดูล

พยายามอย่าเริ่มหัวร้อนในการพัฒนาโมดูลของคุณโดยไม่ได้ใช้เวลาคิดนาน
แรก. การคิดล่วงหน้าเล็กน้อยอาจช่วยคุณประหยัดความพยายามได้มากในภายหลัง

มี it รับ ทำ ก่อน?
คุณอาจไม่จำเป็นต้องเขียนโมดูลด้วยซ้ำ ตรวจสอบว่าได้ทำไปแล้วใน Perl หรือไม่
และหลีกเลี่ยงการประดิษฐ์วงล้อขึ้นใหม่เว้นแต่คุณจะมีเหตุผลที่ดี

สถานที่ที่ดีในการมองหาโมดูลที่มีอยู่แล้ว ได้แก่http://search.cpan.org/> และ
และถามต่อ "[ป้องกันอีเมล]"
(<http://lists.perl.org/list/module-authors.html>).

หากโมดูลที่มีอยู่ เกือบจะ ทำในสิ่งที่คุณต้องการ พิจารณาเขียนแพตช์ เขียน a
คลาสย่อยหรือขยายโมดูลที่มีอยู่แทนที่จะเขียนใหม่

Do หนึ่ง สิ่ง และ do it ดี
โมดูลต่างๆ ได้รับการออกแบบให้เป็นโมดูลโดยมีความเสี่ยงที่จะระบุสิ่งที่ชัดเจน นักพัฒนา Perl
ควรจะสามารถใช้โมดูลต่างๆ เพื่อรวบรวมหน่วยการสร้างของแอปพลิเคชันได้
อย่างไรก็ตาม สิ่งสำคัญคือบล็อกต้องมีรูปร่างที่เหมาะสม และนักพัฒนา
ไม่ควรใช้บล็อกขนาดใหญ่เมื่อต้องการเพียงบล็อกขนาดเล็ก

โมดูลของคุณควรมีขอบเขตที่กำหนดไว้อย่างชัดเจนซึ่งไม่เกินประโยคเดียว
โมดูลของคุณสามารถแบ่งออกเป็นกลุ่มโมดูลที่เกี่ยวข้องได้หรือไม่

ตัวอย่างที่ไม่ดี:

"FooBar.pm จัดให้มีการใช้งานโปรโตคอล FOO และมาตรฐาน BAR ที่เกี่ยวข้อง"

ตัวอย่างที่ดี:

"Foo.pm จัดเตรียมการใช้งานโปรโตคอล FOO Bar.pm ใช้งาน BAR . ที่เกี่ยวข้อง
มาตรการ."

ซึ่งหมายความว่าหากนักพัฒนาต้องการเพียงโมดูลสำหรับมาตรฐาน BAR เท่านั้น พวกเขาไม่ควร
ถูกบังคับให้ติดตั้งไลบรารี่สำหรับ FOO เช่นกัน

มีอะไร in a ชื่อ?
ตรวจสอบให้แน่ใจว่าคุณได้เลือกชื่อที่เหมาะสมสำหรับโมดูลของคุณตั้งแต่เนิ่นๆ สิ่งนี้จะช่วยผู้คน
ค้นหาและจดจำโมดูลของคุณ และทำให้การเขียนโปรแกรมด้วยโมดูลของคุณใช้งานง่ายขึ้น

เมื่อตั้งชื่อโมดูลของคุณ ให้พิจารณาสิ่งต่อไปนี้:

· เป็นคำอธิบาย (เช่น อธิบายวัตถุประสงค์ของโมดูลอย่างถูกต้อง)

· สอดคล้องกับโมดูลที่มีอยู่

· สะท้อนการทำงานของโมดูล ไม่ใช่การนำไปใช้

· หลีกเลี่ยงการเริ่มลำดับชั้นระดับบนสุดใหม่ โดยเฉพาะหากลำดับชั้นที่เหมาะสมอยู่แล้ว
อยู่ภายใต้ซึ่งคุณสามารถวางโมดูลของคุณ

เข้ามา ข้อเสนอแนะ ก่อน การประกาศ
หากคุณไม่เคยอัปโหลดโมดูลไปยัง CPAN มาก่อน (และแม้ว่าคุณจะมี) คุณจะ
ขอแนะนำให้รับข้อเสนอแนะเกี่ยวกับPrePANhttp://prepan.org>. PrePAN เป็นไซต์
ทุ่มเทเพื่อหารือเกี่ยวกับแนวคิดสำหรับโมดูล CPAN กับนักพัฒนา Perl คนอื่น ๆ และดีมาก
ทรัพยากรสำหรับนักพัฒนา Perl ใหม่ (และมีประสบการณ์)

คุณควรลองรับคำติชมจากผู้ที่คุ้นเคยกับโมดูลของ .แล้ว
โดเมนแอปพลิเคชันและระบบการตั้งชื่อ CPAN ผู้เขียนโมดูลที่คล้ายกันหรือโมดูล
ที่มีชื่อคล้ายกันอาจเป็นจุดเริ่มต้นที่ดี เช่นเดียวกับเว็บไซต์ชุมชนอย่าง Perl Monks
<http://www.perlmonks.org>.

การออกแบบ AND การเขียน ของคุณ โมดูล

ข้อควรพิจารณาสำหรับการออกแบบโมดูลและการเข้ารหัส:

ไปยัง OO or ไม่ ไปยัง โอ?
โมดูลของคุณอาจเป็นเชิงวัตถุ (OO) หรือไม่หรืออาจมีอินเทอร์เฟซทั้งสองแบบ
มีอยู่. มีข้อดีข้อเสียของแต่ละเทคนิค ซึ่งควรพิจารณาเมื่อคุณ
ออกแบบ API ของคุณ

In Perl ดีที่สุด การปฏิบัติ (ลิขสิทธิ์ 2004 เผยแพร่โดย O'Reilly Media, Inc. ), Damian Conway
จัดทำรายการเกณฑ์ที่จะใช้ในการตัดสินใจว่า OO เหมาะสมกับปัญหาของคุณหรือไม่:

· ระบบที่กำลังออกแบบมีขนาดใหญ่หรือมีแนวโน้มว่าจะใหญ่ขึ้น

· ข้อมูลสามารถรวมเป็นโครงสร้างที่ชัดเจน โดยเฉพาะอย่างยิ่งหากมีขนาดใหญ่
ปริมาณข้อมูลในแต่ละส่วนรวม

· การรวมข้อมูลประเภทต่างๆ ในรูปแบบลำดับชั้นตามธรรมชาติที่อำนวยความสะดวกในการใช้งาน
ของมรดกและความหลากหลาย

· คุณมีข้อมูลบางส่วนที่ใช้การดำเนินการต่างๆ

· คุณต้องดำเนินการทั่วไปแบบเดียวกันกับประเภทข้อมูลที่เกี่ยวข้อง แต่ด้วย
ความผันแปรเล็กน้อยขึ้นอยู่กับประเภทของข้อมูลที่ใช้การดำเนินการ
ไปยัง

· มีแนวโน้มว่าคุณจะต้องเพิ่มประเภทข้อมูลใหม่ในภายหลัง

· การโต้ตอบโดยทั่วไประหว่างส่วนต่างๆ ของข้อมูลจะแสดงโดยโอเปอเรเตอร์ได้ดีที่สุด

· การนำส่วนประกอบแต่ละส่วนของระบบไปใช้มีแนวโน้มที่จะเปลี่ยนแปลงไป
เวลา

· การออกแบบระบบเป็นแบบเชิงวัตถุอยู่แล้ว

· โปรแกรมเมอร์อื่นๆ จำนวนมากจะใช้โมดูลโค้ดของคุณ

คิดให้รอบคอบว่า OO เหมาะสมกับโมดูลของคุณหรือไม่ วัตถุมงคล
การวางแนวส่งผลให้ API ที่ซับซ้อนซึ่งยากสำหรับผู้ใช้โมดูลโดยเฉลี่ย
เข้าใจหรือนำไปใช้

การออกแบบ ธุรกิจ API
อินเทอร์เฟซของคุณควรเข้าใจได้โดยโปรแกรมเมอร์ Perl ทั่วไป ต่อไปนี้
หลักเกณฑ์อาจช่วยให้คุณตัดสินได้ว่า API ของคุณตรงไปตรงมาเพียงพอหรือไม่:

เขียนกิจวัตรง่าย ๆ เพื่อทำสิ่งง่าย ๆ
การมีกิจวัตรง่ายๆ หลายๆ อย่างจะดีกว่าการทำแบบเสาหินสองสามแบบ ถ้าคุณ
กิจวัตรจะเปลี่ยนพฤติกรรมอย่างมากตามข้อโต้แย้ง มันเป็นสัญญาณว่า
คุณควรมีกิจวัตรสองอย่าง (หรือมากกว่า) แยกกัน

แยกการทำงานออกจากเอาต์พุต
ส่งคืนผลลัพธ์ของคุณในรูปแบบทั่วไปที่สุดเท่าที่จะเป็นไปได้และให้ผู้ใช้เลือกวิธี
เพื่อใช้พวกเขา รูปแบบทั่วไปที่เป็นไปได้มากที่สุดคือโครงสร้างข้อมูล Perl ซึ่ง
จากนั้นสามารถใช้เพื่อสร้างรายงานข้อความ, HTML, XML, การสืบค้นฐานข้อมูลหรืออะไรก็ได้
อื่นๆ ที่ผู้ใช้ของคุณต้องการ

หากกิจวัตรของคุณวนซ้ำผ่านรายการบางประเภท (เช่น รายการไฟล์ หรือ
บันทึกในฐานข้อมูล) คุณอาจพิจารณาให้โทรกลับเพื่อให้ผู้ใช้สามารถ
จัดการแต่ละองค์ประกอบของรายการในทางกลับกัน File::Find ให้ตัวอย่างของ this
ด้วยรูปแบบ "find(\&wanted, $dir)"

จัดเตรียมทางลัดและค่าเริ่มต้นที่เหมาะสม
ไม่ต้องการให้ผู้ใช้โมดูลทุกคนกระโดดผ่านห่วงเดียวกันเพื่อให้ได้สิ่งที่เรียบง่าย
ผลลัพธ์. คุณสามารถใส่พารามิเตอร์เสริมหรือรูทีนสำหรับความซับซ้อนหรือ
พฤติกรรมที่ไม่ได้มาตรฐาน หากผู้ใช้ส่วนใหญ่ของคุณต้องพิมพ์ข้อความที่เกือบเหมือนกันเล็กน้อย
บรรทัดของรหัสเมื่อพวกเขาเริ่มใช้โมดูลของคุณ เป็นสัญญาณว่าคุณควรทำ
พฤติกรรมนั้นเป็นค่าเริ่มต้น ตัวบ่งชี้ที่ดีอีกอย่างหนึ่งที่คุณควรใช้ค่าเริ่มต้นคือ if
ผู้ใช้ส่วนใหญ่ของคุณเรียกกิจวัตรของคุณด้วยอาร์กิวเมนต์เดียวกัน

แบบแผนการตั้งชื่อ
ชื่อของคุณควรสอดคล้องกัน ตัวอย่างเช่น ควรมี:

display_day();
display_week();
display_ปี();

กว่า

display_day();
week_display();
show_ปี();

สิ่งนี้ใช้อย่างเท่าเทียมกันกับชื่อเมธอด ชื่อพารามิเตอร์ และสิ่งอื่นใดซึ่งก็คือ
ให้ผู้ใช้มองเห็นได้ (และส่วนใหญ่ที่มองไม่เห็น!)

ผ่านพารามิเตอร์
ใช้พารามิเตอร์ที่มีชื่อ ใช้แฮชได้ง่ายขึ้นดังนี้:

$obj->do_something(
ชื่อ => "เหวี่ยง",
พิมพ์ => "ข้อความ",
ขนาด => 1024,
);

... กว่าจะมีรายการพารามิเตอร์ที่ไม่มีชื่อยาว ๆ เช่นนี้:

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

แม้ว่ารายการอาร์กิวเมนต์อาจใช้ได้ดีสำหรับอาร์กิวเมนต์หนึ่ง สองหรือสามอาร์กิวเมนต์ any
อาร์กิวเมนต์มากขึ้นกลายเป็นเรื่องยากสำหรับผู้ใช้โมดูลที่จะจำ และยากสำหรับโมดูล
ผู้เขียนในการจัดการ หากคุณต้องการเพิ่มพารามิเตอร์ใหม่ คุณจะต้องเพิ่มลงใน
ท้ายรายการเพื่อความเข้ากันได้แบบย้อนหลัง และนี่อาจทำให้รายการของคุณ
สั่งโดยสัญชาตญาณ นอกจากนี้ หากองค์ประกอบหลายอย่างไม่ได้กำหนดไว้ คุณอาจเห็นสิ่งต่อไปนี้
วิธีการโทรไม่สวย:

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

ระบุค่าเริ่มต้นที่เหมาะสมสำหรับพารามิเตอร์ที่มี อย่าทำให้ผู้ใช้ของคุณ
ระบุพารามิเตอร์ที่จะเหมือนกันเกือบทุกครั้ง

ประเด็นว่าจะส่งผ่านอาร์กิวเมนต์ในแฮชหรือแฮชรีฟนั้นเป็นเรื่องส่วนใหญ่
ของสไตล์ส่วนตัว

การใช้แฮชคีย์ที่ขึ้นต้นด้วยยัติภังค์ ("-name") หรือทั้งหมดเป็นตัวพิมพ์ใหญ่
("NAME") เป็นที่ระลึกของ Perl เวอร์ชันเก่าซึ่งมีสตริงตัวพิมพ์เล็กธรรมดา
ไม่ได้รับการจัดการอย่างถูกต้องโดยโอเปอเรเตอร์ "=>" ในขณะที่บางโมดูลยังคงเป็นตัวพิมพ์ใหญ่
หรือคีย์อาร์กิวเมนต์ที่มีเครื่องหมายยัติภังค์ด้วยเหตุผลทางประวัติศาสตร์หรือตามสไตล์ส่วนตัว
โมดูลใหม่ส่วนใหญ่ควรใช้ปุ่มตัวพิมพ์เล็กอย่างง่าย สิ่งที่คุณเลือกจะเป็น
สม่ำเสมอ!

ความเข้มงวด และ คำเตือน
โมดูลของคุณควรทำงานสำเร็จภายใต้ Pragma ที่เข้มงวดและควรทำงานโดยไม่มี
สร้างคำเตือนใด ๆ โมดูลของคุณควรจัดการกับการตรวจสอบมลทินตามความเหมาะสม
แม้ว่าสิ่งนี้อาจทำให้เกิดปัญหาได้ในหลายกรณี

ย้อนกลับ ความเข้ากันได้
โมดูลที่ "เสถียร" ไม่ควรทำลายความเข้ากันได้แบบย้อนหลังโดยไม่มี a . เป็นอย่างน้อย
ระยะการเปลี่ยนภาพที่ยาวนานและการเปลี่ยนแปลงครั้งสำคัญในหมายเลขเวอร์ชัน

ความผิดพลาด การจัดการ และ ข้อความ
เมื่อโมดูลของคุณพบข้อผิดพลาด ควรทำอย่างน้อยหนึ่งอย่าง:

· ส่งกลับค่าที่ไม่ได้กำหนด

· ตั้งค่า $Module::errstr หรือคล้ายกัน ("errstr" เป็นชื่อสามัญที่ใช้โดย DBI และอื่นๆ
โมดูลยอดนิยม หากคุณเลือกอย่างอื่น โปรดจัดทำเอกสารให้ชัดเจน)

· ข้อความ "warn()" หรือ "carp()" ถึง STDERR

· "croak()" เฉพาะเมื่อโมดูลของคุณไม่สามารถเข้าใจได้ว่าต้องทำอย่างไร ("บ่น()"
เป็นเวอร์ชันที่ดีกว่าของ "die()" สำหรับใช้ภายในโมดูล ซึ่งรายงานข้อผิดพลาดจาก
มุมมองของผู้โทร ดูปลาคาร์พสำหรับรายละเอียดของ "croak()", "carp()" และอื่นๆ
กิจวัตรที่เป็นประโยชน์)

· คุณอาจต้องการส่งข้อยกเว้นโดยใช้ Error . แทน
โมดูล.

การจัดการข้อผิดพลาดที่กำหนดค่าได้จะมีประโยชน์มากสำหรับผู้ใช้ของคุณ พิจารณาเสนอทางเลือก
ของระดับสำหรับข้อความเตือนและดีบัก, ตัวเลือกในการส่งข้อความไปยังไฟล์แยกต่างหาก, a
วิธีระบุรูทีนการจัดการข้อผิดพลาด หรือคุณลักษณะอื่นๆ อย่าลืมตั้งค่าเริ่มต้นทั้งหมด
ตัวเลือกเหล่านี้เพื่อการใช้งานทั่วไป

เอกสาร ของคุณ โมดูล

POD
โมดูลของคุณควรมีเอกสารประกอบสำหรับนักพัฒนา Perl คุณควรใช้ Perl's
"เอกสารเก่าธรรมดา" (POD) สำหรับเอกสารทางเทคนิคทั่วไปของคุณ แม้ว่าคุณอาจจะ
ต้องการเขียนเอกสารเพิ่มเติม (เอกสารไวท์เปเปอร์ แบบฝึกหัด ฯลฯ) ในส่วนอื่นๆ
รูปแบบ. คุณต้องครอบคลุมหัวข้อต่อไปนี้:

· สรุปการใช้งานทั่วไปของโมดูล

· วัตถุประสงค์ ขอบเขต และการใช้งานเป้าหมายของโมดูลของคุณ

· การใช้วิธีการหรือรูทีนย่อยที่เข้าถึงได้แบบสาธารณะ รวมถึงพารามิเตอร์และ
ส่งคืนค่า

· ตัวอย่างการใช้งาน

·ที่มาของข้อมูลเพิ่มเติม

· ที่อยู่อีเมลสำหรับติดต่อผู้เขียน/ผู้ดูแล

ระดับของรายละเอียดในเอกสารประกอบโมดูล Perl โดยทั่วไปจะเปลี่ยนจากรายละเอียดน้อยไปเป็นรายละเอียดเพิ่มเติม
รายละเอียด ส่วนเรื่องย่อของคุณควรมีตัวอย่างการใช้งานเพียงเล็กน้อย (อาจเป็น
โค้ดเพียงบรรทัดเดียว ข้ามกรณีการใช้งานที่ผิดปกติหรืออะไรก็ได้ที่คนส่วนใหญ่ไม่ต้องการ
ผู้ใช้); DESCRIPTION ควรอธิบายโมดูลของคุณในแง่กว้าง โดยทั่วไปใน a
ไม่กี่ย่อหน้า; รายละเอียดเพิ่มเติมเกี่ยวกับรูทีนหรือวิธีการของโมดูล ตัวอย่างโค้ดที่มีความยาว หรือ
เนื้อหาเชิงลึกอื่น ๆ ควรระบุไว้ในตอนต่อไป

ตามหลักการแล้ว คนที่คุ้นเคยกับโมดูลของคุณเพียงเล็กน้อยควรสามารถรีเฟรช . ของพวกเขาได้
หน่วยความจำโดยไม่ต้องกดปุ่ม "page down" ในขณะที่ผู้อ่านของคุณอ่านเอกสารต่อไป พวกเขา
ควรได้รับความรู้เพิ่มขึ้นเรื่อยๆ

ลำดับของส่วนที่แนะนำในเอกสารประกอบโมดูล Perl คือ:

· ชื่อ

· เรื่องย่อ

· คำอธิบาย

· หนึ่งส่วนขึ้นไปหรือส่วนย่อยที่ให้รายละเอียดของวิธีการที่มีอยู่และ
กิจวัตรและข้อมูลอื่น ๆ ที่เกี่ยวข้อง

· BUGS / CAVEATS / ฯลฯ

· ผู้เขียน

· ดูสิ่งนี้ด้วย

·ลิขสิทธิ์และใบอนุญาต

เก็บเอกสารของคุณไว้ใกล้กับรหัสเอกสาร (เอกสาร "อินไลน์") รวม POD
สำหรับวิธีการที่กำหนดด้านบนรูทีนย่อยของวิธีการนั้น ทำให้ง่ายต่อการเก็บ
เอกสารเป็นปัจจุบันและหลีกเลี่ยงการบันทึกแต่ละส่วนของรหัสสองครั้ง (ครั้งเดียวใน
POD และอีกครั้งในความคิดเห็น)

รี้ดมี ติดตั้ง, ปล่อย บันทึก บันทึกการเปลี่ยนแปลง
โมดูลของคุณควรรวมไฟล์ README ที่อธิบายโมดูลและให้ตัวชี้ไปที่
ข้อมูลเพิ่มเติม (เว็บไซต์ อีเมลผู้เขียน)

ควรรวมไฟล์ INSTALL และควรมีคำแนะนำในการติดตั้งอย่างง่าย
เมื่อใช้ ExtUtils::Maker โดยปกติจะเป็น:

เพิร์ล Makefile.PL
ทำ
ทำแบบทดสอบ
ให้ติดตั้ง

เมื่อใช้ Module::Build โดยปกติจะเป็น:

Perl Build.PL
Perl สร้าง
การทดสอบ Perl Build
การติดตั้ง Perl Build

ควรจัดทำบันทึกประจำรุ่นหรือบันทึกการเปลี่ยนแปลงสำหรับซอฟต์แวร์แต่ละรุ่น
อธิบายการเปลี่ยนแปลงที่ผู้ใช้มองเห็นได้ในโมดูลของคุณ ในแง่ที่เกี่ยวข้องกับผู้ใช้

เว้นแต่คุณจะมีเหตุผลที่ดีในการใช้รูปแบบอื่น (เช่น รูปแบบที่ใช้
ภายในบริษัทของคุณ) แบบแผนคือการตั้งชื่อไฟล์บันทึกการเปลี่ยนแปลงของคุณว่า "การเปลี่ยนแปลง" และ to
ทำตามรูปแบบอย่างง่ายที่อธิบายไว้ใน CPAN::Changes::Spec

ปล่อย ที่ต้องคำนึงถึง

เวอร์ชั่น การนับ
หมายเลขเวอร์ชันควรระบุอย่างน้อยรุ่นหลักและรุ่นรอง และอาจเป็นรุ่นรองลงมา
เผยแพร่ รุ่นใหญ่เป็นรุ่นหนึ่งที่ฟังก์ชันส่วนใหญ่มีการเปลี่ยนแปลงหรือใน
ซึ่งมีการเพิ่มฟังก์ชันการทำงานใหม่ที่สำคัญ การปล่อยตัวเล็กน้อยคือการปล่อยตัวจำนวนเล็กน้อย
มีการเพิ่มหรือเปลี่ยนแปลงฟังก์ชันการทำงาน มักจะใช้หมายเลขรุ่นรองลงมาสำหรับ
การเปลี่ยนแปลงที่ไม่ส่งผลต่อการทำงาน เช่น แพตช์เอกสาร

รูปแบบการกำหนดหมายเลขเวอร์ชัน CPAN ที่พบบ่อยที่สุดมีลักษณะดังนี้:

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

หมายเลขเวอร์ชัน CPAN ที่ถูกต้องคือเลขทศนิยมที่มีตัวเลขหลัง . อย่างน้อย 2 หลัก
ทศนิยม. คุณสามารถทดสอบว่าเป็นไปตาม CPAN หรือไม่โดยใช้

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

หากคุณต้องการปล่อยโมดูลรุ่น 'เบต้า' หรือ 'อัลฟ่า' แต่ไม่ต้องการให้ CPAN.pm
ระบุว่าเป็นการใช้ '_' ล่าสุดหลังหมายเลขเวอร์ชันปกติตามด้วยอย่างน้อย 2
ตัวเลข เช่น 1.20_01. หากคุณทำเช่นนี้ แนะนำให้ใช้สำนวนต่อไปนี้:

$VERSION ของเรา = "1.12_01"; # ดังนั้นการกระจาย CPAN จะมี
#ชื่อไฟล์ขวา
$XS_VERSION ของเรา = $VERSION; # จำเป็นเฉพาะถ้าคุณมีรหัส XS
$VERSION = ประเมิน $VERSION; # ดังนั้น "ใช้โมดูล 0.002" จะไม่เตือน
#ขีดเส้นใต้

ด้วยเคล็ดลับนั้น MakeMaker จะอ่านเฉพาะบรรทัดแรกและอ่านขีดล่างเท่านั้น
ในขณะที่ล่าม Perl จะประเมิน $VERSION และแปลงสตริงเป็นa
ตัวเลข. การดำเนินการภายหลังที่ถือว่า $VERSION เป็นตัวเลขก็จะสามารถทำได้
โดยไม่เตือนว่า $VERSION ไม่ใช่ตัวเลข

อย่าปล่อยสิ่งใดๆ (แม้แต่แพตช์เอกสารประกอบหนึ่งคำ) โดยไม่เพิ่มค่า
ตัวเลข. แม้แต่โปรแกรมแก้ไขเอกสารคำเดียวก็ควรส่งผลให้เกิดการเปลี่ยนแปลงในเวอร์ชันที่
ระดับรองลงมา

เมื่อเลือกแล้ว ให้ยึดติดกับรูปแบบเวอร์ชันของคุณโดยไม่ลดจำนวนลง
ของตัวเลข นี่เป็นเพราะผู้ทำแพ็คเกจ "ดาวน์สตรีม" เช่นระบบพอร์ต FreeBSD
ตีความหมายเลขรุ่นด้วยวิธีต่างๆ หากคุณเปลี่ยนจำนวนหลักใน .ของคุณ
รูปแบบเวอร์ชัน คุณสามารถสร้างความสับสนให้กับระบบเหล่านี้ เพื่อให้ระบบเหล่านี้นำเวอร์ชันของโมดูลของคุณออกมาได้
ของระเบียบซึ่งเห็นได้ชัดว่าไม่ดี

requisites ก่อน
ผู้เขียนโมดูลควรพิจารณาอย่างรอบคอบว่าจะต้องพึ่งพาโมดูลอื่นหรือไม่ และอะไร
โมดูลที่ต้องพึ่งพา

ที่สำคัญที่สุด ให้เลือกโมดูลที่มีความเสถียรมากที่สุด ตามลำดับความชอบ:

· โมดูล Core Perl หลัก

· โมดูล CPAN ที่เสถียร

· โมดูล CPAN ที่ไม่เสถียร

· โมดูลไม่พร้อมใช้งานจาก CPAN

ระบุข้อกำหนดเวอร์ชันสำหรับโมดูล Perl อื่นๆ ในข้อกำหนดเบื้องต้นใน your
Makefile.PL หรือ Build.PL

อย่าลืมระบุข้อกำหนดเวอร์ชัน Perl ทั้งใน Makefile.PL หรือ Build.PL และ with
"ต้องการ 5.6.1" หรือคล้ายกัน ดูหัวข้อ "ใช้เวอร์ชัน" ของ "ต้องการ" ใน perlfunc สำหรับ
รายละเอียด

การทดสอบ
โมดูลทั้งหมดควรได้รับการทดสอบก่อนแจกจ่าย (โดยใช้ "make disttest") และการทดสอบ
ควรมีให้สำหรับผู้ที่ติดตั้งโมดูลด้วย (โดยใช้ "ทำการทดสอบ") สำหรับ
โมดูล :: Build คุณจะใช้ "ทำการทดสอบ" ที่เทียบเท่ากับ "การทดสอบ Perl Build"

ความสำคัญของการทดสอบเหล่านี้แปรผันตามความเสถียรของโมดูลที่ถูกกล่าวหา อา
โมดูลที่อ้างว่ามีเสถียรภาพหรือหวังว่าจะบรรลุการใช้งานในวงกว้างควรยึดตาม
เข้มงวดระบบการทดสอบให้มากที่สุด

โมดูลที่มีประโยชน์เพื่อช่วยคุณเขียนการทดสอบ (โดยมีผลกระทบน้อยที่สุดต่อกระบวนการพัฒนาของคุณหรือ
เวลาของคุณ) รวมถึง Test::Simple, Carp::Asert และ Test::Inline เพื่อความซับซ้อนยิ่งขึ้น
ชุดทดสอบมี Test::More และ Test::MockObject

บรรจุภัณฑ์
โมดูลควรได้รับการบรรจุโดยใช้เครื่องมือบรรจุภัณฑ์มาตรฐานอย่างใดอย่างหนึ่ง ขณะนี้คุณมี
ตัวเลือกระหว่าง ExtUtils::Maker และโมดูลอิสระของแพลตฟอร์มเพิ่มเติม :: Build,
อนุญาตให้ติดตั้งโมดูลในลักษณะที่สอดคล้องกัน เมื่อใช้ ExtUtils::Maker,
คุณสามารถใช้ "make dist" เพื่อสร้างแพ็คเกจของคุณ มีเครื่องมือที่จะช่วยคุณสร้าง
โมดูลในรูปแบบที่เป็นมิตรต่อ MakerMaker ซึ่งรวมถึง ExtUtils::ModuleMaker และ h2xs ดู
ยัง perlnewmod

ลิขสิทธิ์
ตรวจสอบให้แน่ใจว่าโมดูลของคุณมีใบอนุญาต และข้อความทั้งหมดของโมดูลนั้นรวมอยู่ใน
การแจกจ่าย (เว้นแต่จะเป็นเรื่องปกติและข้อกำหนดของใบอนุญาตไม่จำเป็นต้องให้คุณ
รวมไว้ด้วย)

หากคุณไม่ทราบว่าจะใช้ใบอนุญาตใด ให้สิทธิ์ใช้งานแบบคู่ภายใต้ใบอนุญาต GPL และใบอนุญาตศิลปะ
(เช่นเดียวกับ Perl เอง) เป็นความคิดที่ดี ดู perlgpl และ perlartistic

ทั่วไป หลุมพราง

reinventing ล้อ
มีบางพื้นที่แอปพลิเคชันที่ CPAN ให้บริการเป็นอย่างดีอยู่แล้ว
ตัวอย่างหนึ่งคือระบบเทมเพลต อีกอันคือโมดูลวันที่และเวลาและมีจำนวนมาก
มากกว่า. แม้ว่าจะเป็นพิธีทางที่จะเขียนสิ่งเหล่านี้ในแบบของคุณเอง ได้โปรด
พิจารณาอย่างรอบคอบว่าโลกของ Perl ต้องการให้คุณเผยแพร่หรือไม่

พยายาม ไปยัง do เกินไป มาก
โมดูลของคุณจะเป็นส่วนหนึ่งของชุดเครื่องมือของนักพัฒนา ตัวมันเองจะไม่ก่อให้เกิด
ทั้ง ชุดเครื่องมือ เป็นการดึงดูดที่จะเพิ่มคุณสมบัติพิเศษจนกว่าโค้ดของคุณจะเป็นเสาหิน
ระบบแทนที่จะเป็นชุดหน่วยการสร้างแบบแยกส่วน

ไม่เหมาะสม เอกสาร
อย่าตกหลุมพรางของการเขียนสำหรับผู้ฟังที่ผิด ผู้ชมหลักของคุณคือ a
นักพัฒนาที่มีประสบการณ์พอสมควรและมีความเข้าใจโมดูลของคุณในระดับปานกลางอย่างน้อย
โดเมนแอปพลิเคชันที่เพิ่งดาวน์โหลดโมดูลของคุณและต้องการเริ่มใช้งานเป็น
โดยเร็วที่สุด

บทช่วยสอน เอกสารสำหรับผู้ใช้ปลายทาง เอกสารการวิจัย คำถามที่พบบ่อย ฯลฯ ไม่เหมาะสมใน
เอกสารหลักของโมดูล หากคุณต้องการเขียนสิ่งเหล่านี้จริงๆ ให้รวมเป็น sub-
เอกสารเช่น "My::Module::Tutorial" หรือ "My::Module::FAQ" และระบุลิงก์ใน
ดูส่วนเอกสารหลักด้วย

ใช้ perlmodstyle ออนไลน์โดยใช้บริการ onworks.net