Apa cara yang tepat untuk mengomentari fungsi dalam Python?

Apakah ada cara yang diterima secara umum untuk mengomentari fungsi dalam Python? Apakah yang berikut ini dapat diterima?

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

Cara yang benar untuk melakukannya adalah dengan menyediakan dokumen. Dengan begitu, help(add)juga akan memuntahkan komentar Anda.

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

Itu tiga tanda kutip ganda untuk membuka komentar dan tiga tanda kutip ganda untuk mengakhirinya. Anda juga dapat menggunakan string Python yang valid. Tidak perlu multiline dan tanda kutip ganda dapat diganti dengan tanda kutip tunggal.

Lihat: PEP 257

Gunakan docstring, seperti yang sudah ditulis orang lain.

Anda bahkan dapat melangkah lebih jauh dan menambahkan doctest ke docstring Anda, membuat pengujian otomatis fungsi Anda menjadi mudah.

Gunakan docstring :

String literal yang muncul sebagai pernyataan pertama dalam modul, fungsi, kelas, atau definisi metode. Dokumen semacam itu menjadi __doc__atribut khusus dari objek itu.

Semua modul biasanya harus memiliki dokumen, dan semua fungsi dan kelas yang diekspor oleh modul juga harus memiliki dokumen. Metode publik (termasuk __init__konstruktor) juga harus memiliki dokumen. Paket dapat didokumentasikan dalam modul modul __init__.pyfile dalam direktori paket.

Literal string yang terjadi di tempat lain dalam kode Python juga dapat bertindak sebagai dokumentasi. Mereka tidak dikenali oleh kompiler bytecode Python dan tidak dapat diakses sebagai atribut objek runtime (yaitu tidak ditugaskan untuk __doc__), tetapi dua jenis dokumen tambahan dapat diekstraksi oleh alat perangkat lunak:

1. Literal string yang terjadi segera setelah penugasan sederhana di tingkat atas modul, kelas, atau __init__metode disebut "atribut docstrings".
2. String literal yang muncul segera setelah docstring lain disebut "docstring tambahan".

Silakan lihat PEP 258 , "Spesifikasi Desain Docutils" [2] , untuk deskripsi terperinci tentang atribut dan dokumen tambahan ...

Prinsip-prinsip komentar yang baik cukup subjektif, tetapi berikut adalah beberapa pedoman:

• Komentar fungsi harus menggambarkan maksud suatu fungsi, bukan implementasi
• Buat garis besar asumsi yang dibuat fungsi Anda terkait dengan status sistem. Jika ia menggunakan variabel global apa pun (tsk, tsk), buat daftar.
• Watch out for seni ASCII yang berlebihan . Memiliki hash yang panjang sepertinya membuat komentar lebih mudah dibaca, tetapi bisa mengganggu jika komentar berubah
• Manfaatkan fitur bahasa yang menyediakan 'dokumentasi otomatis', yaitu, dokumentasi dengan Python, POD dalam Perl, dan Javadoc di Jawa

Baca tentang cara menggunakan dokumen dalam kode Python Anda.

Sesuai dengan konvensi dokumentasi Python :

Dokumen untuk suatu fungsi atau metode harus meringkas perilakunya dan mendokumentasikan argumennya, nilai balik, efek samping, pengecualian yang muncul, dan batasan kapan dapat dipanggil (semua jika berlaku). Argumen opsional harus ditunjukkan. Ini harus didokumentasikan apakah argumen kata kunci adalah bagian dari antarmuka.

Tidak akan ada aturan emas, melainkan memberikan komentar yang berarti bagi pengembang lain di tim Anda (jika Anda memilikinya) atau bahkan untuk diri sendiri ketika Anda kembali ke sana enam bulan kemudian.

Saya akan pergi untuk praktik dokumentasi yang terintegrasi dengan alat dokumentasi seperti Sphinx .

Langkah pertama adalah menggunakan docstring:

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

Saya akan melangkah lebih jauh dari sekedar mengatakan "gunakan docstring". Pilih alat pembuat dokumentasi, seperti pydoc atau epydoc (saya menggunakan epydoc di pyparsing), dan gunakan sintaks markup yang dikenali oleh alat itu. Jalankan alat itu sesering mungkin saat Anda melakukan pengembangan, untuk mengidentifikasi lubang dalam dokumentasi Anda. Bahkan, Anda mungkin mendapat manfaat dari menulis dokumen untuk anggota kelas sebelum mengimplementasikan kelas.

Gunakan dokumen .

Ini adalah konvensi bawaan yang disarankan di PyCharm untuk komentar uraian fungsi:

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

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

Meskipun saya setuju bahwa ini bukan komentar, tetapi saran seperti yang disarankan sebagian besar (semua?), Saya ingin menambahkan numpydoc (panduan gaya docstring) .

Jika Anda melakukannya seperti ini, Anda dapat (1) secara otomatis menghasilkan dokumentasi dan (2) orang-orang mengenali ini dan memiliki waktu yang lebih mudah untuk membaca kode Anda.

Anda dapat menggunakan tiga kutipan untuk melakukannya.

Anda dapat menggunakan tanda kutip tunggal:

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

Atau kutipan ganda:

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