เนื่องจากเรารู้วิธีเขียนความคิดเห็นแบบหลายบรรทัดแล้ว เราจึงอาจใช้เครื่องหมายคำพูดเดี่ยวสามคำหรือเครื่องหมายคำพูดคู่สามเท่าก็ได้ เราใช้สตริงเอกสารเมื่อเราต้องการอธิบายฟังก์ชันของเรา เพื่อให้เราได้รับเอกสารเมื่อเราต้องการ IDE บางตัวให้เอกสารแก่คุณโดยเพียงแค่วางเมาส์เหนือชื่อและบางส่วนเน้นคีย์เวิร์ดบางคำ แต่ความจริงก็คือว่า docstrings ใน NumPy นั้นมีความยืดหยุ่นมากกว่าในภาษาอื่นๆ Docstring เป็นสตริงตัวอักษรที่เกิดขึ้นที่จุดเริ่มต้นของการกำหนดฟังก์ชัน เราต้องระบุค่าเฉพาะในขณะที่ใช้ docstrings ในกรณีของฟังก์ชัน คลาส ฯลฯ
เมื่อใช้ docstrings กับฟังก์ชัน เราต้องส่งผ่านอาร์กิวเมนต์ เมื่อใช้กับคลาส เราส่งแอตทริบิวต์และเมธอด ในกรณีของโมดูล เราต้องจัดเตรียมรายการของคลาสและฟังก์ชัน ในกรณีของแพ็คเกจ เราส่งรายการโมดูลพร้อมฟังก์ชันการทำงาน โดยพื้นฐานแล้ว วัตถุประสงค์ของ docstring ก็คือ ตามชื่อที่อธิบาย ว่าช่วยในเรื่องเอกสารของโค้ดของเรา เราทำเอกสารเพื่อที่ว่าถ้ามีคนใช้รหัสของเราในอนาคต เขาจะสามารถเข้าใจรหัสของเราและตรรกะที่อยู่เบื้องหลังรหัสของเราด้วยความช่วยเหลือของ docstring ฟังก์ชันในตัวยังมี docstrings อยู่ด้วย เราสามารถใช้ฟังก์ชันของ help() เพื่อดู docstring ของฟังก์ชันในตัว
มีความแตกต่างเล็กน้อยระหว่างความคิดเห็นและเอกสารประกอบ ความคิดเห็นจะถูกละเว้นโดยล่าม แต่ docstrings จะไม่ละเว้นโดยล่าม มีการจัดสรรหน่วยความจำสำหรับเอกสาร ความคิดเห็นเป็นคำอธิบายของโค้ด แต่ในทางกลับกัน docstrings บอกเราถึงจุดประสงค์ของโค้ด
ไวยากรณ์:
ไวยากรณ์ในการเขียน docstrings ใน NumPy คือ:
'''ข้อความเอกสาร'''
หรือ
'''ข้อความเอกสาร'''
โปรดทราบว่า docstring ไม่ใช่ฟังก์ชันหรือวิธีการ ดังนั้นจึงไม่มีรูปแบบที่เหมาะสม สิ่งเดียวที่ควรทราบในที่นี้คือ เราเริ่ม docstring ด้วยเครื่องหมายอัญประกาศเดี่ยวสามอันหรืออัญประกาศคู่สามอัน เราเขียนคำอธิบายโค้ดของเราและปิดท้ายอีกครั้งด้วยเครื่องหมายคำพูดเดี่ยวสามคำหรือเครื่องหมายคำพูดคู่สามคำในตอนท้าย ไม่จำเป็นต้องเขียนเอกสารประกอบการ คุณเพียงแค่ใส่เครื่องหมายคำพูดเดี่ยวหรือคู่สามตัวก่อนและหลังคำอธิบายสตริงของคุณ
ตัวอย่างที่ 1:
เพื่อให้เข้าใจ docstrings ได้ดีขึ้น เรามาดูตัวอย่างกัน ในตัวอย่างนี้ หลังจากรวมไลบรารี NumPy แล้ว เราเพียงแค่ประกาศตัวแปร 'a' และตัวแปรอื่น 'b' หลังจากนั้น เราสร้าง docstring ซึ่งระบุว่า 'ให้เราเพิ่มตัวแปร 'a' และ 'b' ในกรณีของเรา นี่เป็นตัวอย่างง่ายๆ แต่ถ้าโค้ดของเราซับซ้อน จะช่วยให้ผู้เข้ารหัสเข้าใจโค้ดได้มาก หลังจากนั้น เราสรุปตัวแปร 'a' และ 'b' และเก็บผลลัพธ์ของผลลัพธ์ไว้ในตัวแปรอื่นซึ่งก็คือ 'c' สุดท้าย เราพิมพ์ค่าของตัวแปร 'c' ตอนนี้เรารันโค้ดของเรา
นำเข้า งี่เง่า เช่น เช่น.เอ = 1
ข = สอง
'''มาเพิ่มตัวแปร a และ b'''
ค = a+b
พิมพ์ ( ค )
นี่คือผลลัพธ์ของเราจากโค้ดที่กำหนด เราจะเห็นว่าระบบไม่ได้ให้ข้อผิดพลาดเกี่ยวกับไวยากรณ์ที่ไม่ถูกต้องหรืออะไรก็ตามสำหรับบรรทัดที่ 7 ของโค้ดของเรา นอกจากนี้ ระบบยังไม่ได้พิมพ์ docstring ของเรา แต่จะพิมพ์เฉพาะผลลัพธ์ของตัวแปร 'c' ซึ่งเราบอกให้ระบบพิมพ์เท่านั้น นี้แสดงให้เห็นว่าเอกสารทำงานอย่างไร ครั้งต่อไป เมื่อ coder ใหม่พยายามทำงานกับโค้ดของเรา เขาจะเข้าใจว่าเรากำลังทำอะไรอยู่ด้วยความช่วยเหลือจาก docstring ของเรา แต่จะไม่พิมพ์ออกมาเป็นเอาต์พุต ดังนั้นผู้ใช้โค้ดจะไม่ถูกรบกวน
ตัวอย่างที่ 2:
ตอนนี้ เราทำตัวอย่างที่ซับซ้อนเพื่อทำความเข้าใจการทำงานของ docstring ขั้นแรก เรารวมไลบรารี NumPy แล้วเขียนสตริง doc ซึ่งเราจะอธิบายโค้ดบรรทัดถัดไปที่เราอธิบายการเริ่มต้นของอาร์เรย์ นอกจากนี้เรายังเพิ่ม docstrings ในส่วนอื่น ๆ ของรหัส ตอนนี้ หากเราแชร์โค้ดนี้กับนักพัฒนา Python รายใหม่โดยไม่เพิ่ม docstrings เขาจะทราบการทำงานและวัตถุประสงค์ของโค้ดนี้ได้ยาก เขาต้องค้นหาฟังก์ชั่นที่เราใช้ก่อน แต่ถ้าเราเพิ่ม docstring ลงในโค้ดของเรา นักพัฒนาคนอื่นๆ จะเข้าใจโค้ดได้ง่ายโดยไม่ต้องศึกษาเพิ่มเติมเกี่ยวกับฟังก์ชันต่างๆ เราไม่ได้ถูกจำกัดให้เพิ่มความคิดเห็นในข้อจำกัดบางอย่าง ความคิดเห็นสามารถมีได้ตั้งแต่หนึ่งบรรทัดขึ้นไป นอกจากนี้ยังสามารถเพิ่มได้มากกว่าหนึ่งครั้งในรหัส จากนั้นนำเข้า NumPy เป็น np
'''การสร้างตัวแปรที่เราจะส่งผ่านอาร์เรย์ขนาด 1x6'''อาร์เรย์ = เช่น. อาร์เรย์ ( [ สิบเอ็ด , 22 , 33 , 44 , 55 , 66 ] )
'''การกำหนดอาร์เรย์ให้กับฟังก์ชัน tofile() เพื่อให้บันทึกลงในไฟล์ชื่อ arr''
อาร์เรย์ . tofile ( 'arr.bin' )
'' 'แสดงไฟล์โดยใช้ฟังก์ชัน fromfile'''
พิมพ์ ( เช่น. จากไฟล์ ( 'arr.bin' , dtype = int ) )
ดังที่แสดงในตัวอย่างต่อไปนี้ docstrings จะไม่แสดงในเอาต์พุต ซึ่งหมายความว่าจะไม่มีผลกับเอาต์พุตหรือการรวบรวมโค้ด Docstrings จะถูกละเว้นในระหว่างกระบวนการคอมไพล์
บทสรุป
ในคู่มือนี้ เราได้เรียนรู้เกี่ยวกับ docstrings ใน NumPy เราเปรียบเทียบเอกสารกับความคิดเห็นและอธิบายความแตกต่างระหว่างทั้งสองข้อ เราได้เรียนรู้ไวยากรณ์ของ docstrings และวิธีเขียน docstrings ในโค้ดของเรา นอกจากนี้เรายังพยายามอธิบายว่า docstrings ใน NumPy คืออะไรและทำงานอย่างไรโดยใช้ตัวอย่าง สุดท้าย เราตั้งข้อสังเกตว่าสิ่งเหล่านี้จำเป็นสำหรับผู้เขียนโค้ด เราจะไม่ย้ำความสำคัญของ docstrings ใน NumPy เราจะบอกว่าคุณควรใช้ docstrings ในโค้ดของคุณ ใน NumPy รูปแบบการเขียน docstrings เป็นที่นิยมมากที่สุด มีการใช้กันอย่างแพร่หลายในชุมชนการเขียนโปรแกรมเพื่อให้กันและกันทราบเกี่ยวกับการทำงานและการทำงานของรหัสของพวกเขา คู่มือนี้จะช่วยคุณเริ่มต้นใช้งานเอกสาร NumPy เราพยายามครอบคลุมสิ่งที่คุณต้องการส่วนใหญ่โดยใช้เอกสารประกอบใน NumPy