วิธีที่เหมาะสมในการแสดงความคิดเห็นฟังก์ชั่นใน Python คืออะไร?

มีวิธียอมรับฟังก์ชั่นใน Python หรือไม่? ยอมรับได้ดังต่อไปนี้หรือไม่?

#########################################################
# Create a new user
#########################################################
def add(self):

วิธีที่ถูกต้องที่จะทำคือการให้ docstring ด้วยวิธีนี้help(add)จะคายความคิดเห็นของคุณ

def add(self):
    """Create a new user.
    Line 2 of comment...
    And so on... 
    """

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

ดู: PEP 257

ใช้ docstring ตามที่คนอื่นเขียนไปแล้ว

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

ใช้docstring :

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

โดยปกติโมดูลทั้งหมดควรมีเอกสารและฟังก์ชั่นและคลาสทั้งหมดที่ส่งออกโดยโมดูลควรมีเอกสารด้วย วิธีการสาธารณะ (รวมถึงตัว__init__สร้าง) ควรมีเอกสาร แพคเกจอาจได้รับการบันทึกไว้ใน docstring โมดูลของ__init__.pyไฟล์ในไดเรกทอรีแพคเกจ

ตัวอักษรสตริงที่เกิดขึ้นที่อื่นในรหัสหลามอาจทำหน้าที่เป็นเอกสาร พวกเขาไม่ได้รับการยอมรับจากคอมไพเลอร์ Python bytecode และไม่สามารถเข้าถึงได้เป็นคุณลักษณะวัตถุรันไทม์ (เช่นไม่ได้กำหนดให้__doc__) แต่ docstrings พิเศษสองประเภทอาจถูกดึงออกมาโดยเครื่องมือซอฟต์แวร์:

1. สตริงตัวอักษรที่เกิดขึ้นทันทีหลังจากการมอบหมายอย่างง่ายที่ระดับบนสุดของโมดูลคลาสหรือ__init__วิธีการที่เรียกว่า "attribute docstrings"
2. สตริงตัวอักษรที่เกิดขึ้นทันทีหลังจาก docstring อื่นเรียกว่า "docstrings เพิ่มเติม"

โปรดดูPEP 258 , "Docutils Design Specification" [2] , สำหรับคำอธิบายโดยละเอียดของคุณสมบัติและเอกสารเพิ่มเติม ...

หลักการของการแสดงความคิดเห็นที่ดีมีความเป็นส่วนตัว แต่นี่คือแนวทางบางประการ:

• ความคิดเห็นเกี่ยวกับฟังก์ชันควรอธิบายถึงเจตนาของฟังก์ชั่นไม่ใช่การใช้งาน
• สรุปสมมติฐานใด ๆ ที่ฟังก์ชันของคุณทำเกี่ยวกับสถานะของระบบ ถ้ามันใช้ตัวแปรทั่วโลก (tsk, tsk) รายการเหล่านั้น
• ระวังมากเกินไปศิลปะ ASCII การมีแฮชที่มีสายยาวอาจทำให้อ่านง่ายขึ้น แต่มันอาจสร้างความรำคาญให้กับเมื่อความคิดเห็นเปลี่ยนไป
• ใช้ประโยชน์จากคุณสมบัติด้านภาษาที่มี 'เอกสารอัตโนมัติ' เช่น docstrings ใน Python, POD ใน Perl และ Javadoc ใน Java

อ่านเกี่ยวกับการใช้docstringsในรหัสหลามของคุณ

ตามระเบียบของdocstring Python :

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

จะไม่มีกฎทองคำ แต่ให้ความเห็นที่มีความหมายกับนักพัฒนาคนอื่น ๆ ในทีมของคุณ (ถ้าคุณมี) หรือแม้แต่กับตัวคุณเองเมื่อคุณกลับมาใช้มันอีกหกเดือน

ฉันจะไปหาเอกสารการปฏิบัติที่ทำงานร่วมกับเครื่องมือเอกสารเช่นสฟิงซ์

ขั้นตอนแรกคือการใช้docstring:

def add(self):
 """ Method which adds stuff
 """

ฉันจะไปอีกขั้นมากกว่าแค่พูดว่า "ใช้ docstring" เลือกเครื่องมือสร้างเอกสารเช่น pydoc หรือ epydoc (ฉันใช้ epydoc ใน pyparsing) และใช้ไวยากรณ์มาร์กอัปที่เครื่องมือดังกล่าวรู้จัก เรียกใช้เครื่องมือนั้นบ่อยครั้งขณะที่คุณทำการพัฒนาเพื่อระบุช่องโหว่ในเอกสารของคุณ ในความเป็นจริงคุณอาจได้รับประโยชน์จากการเขียนเอกสารสำหรับสมาชิกของชั้นเรียนก่อนที่จะดำเนินการชั้นเรียน

ใช้docstrings

นี่คือการประชุมที่แนะนำในตัวในPyCharmสำหรับความคิดเห็นคำอธิบายฟังก์ชัน:

def test_function(p1, p2, p3):
    """
    my function does blah blah blah

    :param p1: 
    :param p2: 
    :param p3: 
    :return: 
    """

ขณะที่ฉันเห็นว่าเรื่องนี้ไม่ควรที่จะแสดงความคิดเห็น แต่ docstring เป็นส่วนใหญ่ (ทั้งหมด?) คำตอบที่แนะนำให้ผมต้องการที่จะเพิ่มnumpydoc (เป็นคู่มือสไตล์ docstring)

หากคุณทำสิ่งนี้คุณสามารถ (1) สร้างเอกสารโดยอัตโนมัติและ (2) คนรู้จักและอ่านรหัสของคุณได้ง่ายขึ้น

คุณสามารถใช้สามคำพูดเพื่อทำมัน

คุณสามารถใช้เครื่องหมายคำพูดเดี่ยว:

def myfunction(para1,para2):
  '''
  The stuff inside the function
  '''

หรือเครื่องหมายคำพูดคู่:

def myfunction(para1,para2):
  """
  The stuff inside the function
  """