Saya ingin mendokumentasikan kode saya sehingga ada kebutuhan minimum untuk membaca dan menelusuri kode lagi beberapa bulan kemudian.

Saya tahu bahwa ada berbagai jenis dokumentasi (dalam kode sumber dan di luar, diagram urutan, dan sebagainya).

Saya hanya ingin tahu apa cara yang efisien untuk mendokumentasikan kode saya sehingga, ketika beberapa bulan kemudian saya ingin melihat kode saya, saya menghabiskan lebih sedikit waktu untuk membaca kode dan memahami aliran kode.

Saya harus mengakui bahwa saya tidak setuju dengan beberapa hal yang direkomendasikan oleh jawaban yang lain, jadi saya akan melemparkan dua sen saya;

Komentar

Dokumentasi sangat membantu bagi orang asing yang membaca kode Anda. Biasanya banyak hal tidak cukup verbal untuk dibaca dan dipahami dengan segera, dan Anda harus menjelaskan apa yang Anda lakukan.

Sunting : diskusi di bagian komentar menunjukkan sesuatu yang benar - komentar berlebihan biasanya dilakukan saat menulis kode yang buruk .

Mengomentari pekerjaan Anda harus tepat dan minimal, tetapi, menurut saya, pasti harus ada. Setidaknya komentar untuk setiap 15 baris kode. Misalnya, di atas blok pada kode, tambahkan baris tentang apa yang Anda lakukan:

def login(username: str, password: str, create_session: bool = True):

    # Filter the user we need from the database
    hash = md5(password)
    users = db.table("users", db_entities.USER)
    results = [x for x in users.query(lambda c: c.get("username") == username and c.get("password_hash") == hash)]


    if len(results) == 0:
        return None, None
    else:
        # Create a login session record in the database.
        if create_session:
            sessions = db.table("sessions", db_entities.SESSION)
            ses = sessions.new()
            ses.set("username", username) \
                .set("expiery", 31536000 + time.time())
            sessions.update(ses)
            return results[0], ses
        else:
            return results[0], None

Komentar minimal yang menjelaskan mengapa dan apa yang Anda lakukan sangat membantu di seluruh kode. Saya tidak setuju dengan jawaban yang menyatakan

Jika saya menemukan kode yang berisi komentar, saya bersiap untuk yang terburuk: kode kemungkinan besar akan buruk, dan jujur ​​komentar cenderung juga buruk.

Sering kali, dengan anggun, kode yang baik didokumentasikan. Benar bahwa programmer yang buruk melihat dokumentasi mereka seperti "Baiklah, kode saya jelek, mari kita tambahkan beberapa kalimat untuk membuatnya lebih jelas".

Ya, dan sementara ini terjadi cukup banyak, juga benar bahwa programmer yang baik yang menulis kode bersih juga ingin memastikan bahwa mereka kembali ke kode mereka dan memahami mengapa mereka ingin fungsi mereka berperilaku seperti itu, atau mengapa mereka membutuhkannya garis yang sepertinya agak berlebihan, dll ...

Ya, komentar yang menjelaskan hal-hal yang jelas, komentar yang tidak jelas, komentar yang hanya disatukan untuk memastikan bahwa "kode ini didokumentasikan, ya, apa pun", adalah kode bau. Mereka membuat membaca kode lebih sulit dan menjengkelkan. (Menambahkan contoh di bawah)

# Logging into Gmail when the module is imported
_client = login()
def get_client():
    global _client
    return _client

Klarifikasi contoh: "Tidak apa-apa, Sherlock. Apakah _client = login()masuk ke layanan surat? OMG!"

Klarifikasi lebih lanjut: login()metode ini tidak ada hubungannya dengan login()metode dari contoh di atas.

Tetapi komentar yang sesuai dengan standar, menjelaskan mengapa dan bukan bagaimana, dan menjawab pertanyaan yang benar , sangat ( sangat ) sangat membantu.

Komentar sebaris

Satu hal yang TIDAK BISA (dan jika saya bisa menulis yang lebih besar, saya akan) lakukan, adalah menulis komentar Anda di baris kode yang sama. Itu membuat komentar sangat spesifik untuk baris, yang benar-benar kehilangan tujuan mengomentari kode Anda.

Misalnya, komentar sebaris yang buruk:

outer = MIMEText(details["message"]) # Constructing a new MIMEText object
outer["To"] = details["to"] # Setting message recipient
outer["From"] = "xAI No-Reply" # Setting message sender
outer["Subject"] = details["subject"] # Setting message subject
outer.preamble = "You will not see this in a MIME-aware mail reader.\n" # I don't know what I'm doing here, I copied this from SO.
msg = outer.as_string() # Getting the string of the message
_client = details["client"] # Assigning the client
_client.sendmail(SENDER, details["to"], msg) # Sending the mail

Akan jauh lebih mudah untuk membaca dan memahami kode ini tanpa komentar, yang membuatnya berantakan dan tidak dapat dibaca.

Sebaliknya, komentar di dalam kode Anda harus ditempatkan di atas blok pada kode, dan mereka harus menjawab pertanyaan-pertanyaan penting yang mungkin timbul saat membaca blok kode.

# Constructing the email object with the values 
# we received from the parameter of send_mail(details)
outer = MIMEText(details["message"])
outer["To"] = details["to"]
outer["From"] = "xAI No-Reply"
outer["Subject"] = details["subject"]
outer.preamble = "You will not see this in a MIME-aware mail reader.\n"
msg = outer.as_string()

# Sending the mail using the global client (obtained using login())
_client = details["client"]
_client.sendmail(SENDER, details["to"], msg)

Jauh lebih jelas, bukan? Sekarang Anda juga tahu bahwa Anda harus menggunakan login()fungsi dan memberikan parameter untuk send_mail()semua yang Anda gunakan. Membantu sedikit, tetapi satu hal masih hilang.

Dokumentasi fungsi

Telah banyak dibahas. Anda harus selalu memberi tahu pembaca tentang fungsi Anda, mengapa dan apa fungsinya. Bagaimana cara melakukannya, ini bukan milik dokumentasi, tetapi mungkin catatan kaki dari fungsi.

Anda harus dengan jelas menggambarkan apa yang Anda harapkan dari parameter Anda, dan jika Anda menginginkannya diperoleh / dibuat dengan metode tertentu. Anda harus menyatakan apa fungsi Anda harus dikembalikan, apa fungsinya, dll.

Sekali lagi, itulah pendapat dan metodologi saya saat menulis kode saya. Bukan hanya itu, tetapi itu hanya beberapa hal yang saya tidak setuju dengan jawaban lain tentang. Oh, dan tentu saja, bukan hanya komentar yang membaca kode Anda, tetapi kode Anda sendiri. Tulis kode yang bersih, dapat dimengerti dan dipelihara . Pikirkan tentang masa depan Anda sendiri saat coding ;-)

IMO dokumentasi terbaik adalah dokumentasi yang sebenarnya tidak Anda butuhkan. Saya juga benci menulis dokumentasi dan komentar.

Dengan itu dikatakan:

• Pilih nama yang dapat dibaca dan berbicara. Jangan gunakan n, melainkan sebagai numberOfItemsFoundcontoh.
• Jangan menghindar untuk menyimpan bagian dari perhitungan dalam variabel konstan daripada mendorong semuanya menjadi satu baris.
• Pindahkan sebagian tugas dari cabang ke fungsi (inline) mereka sendiri, jika Anda menggunakannya kembali atau fungsi induk menjadi panjang dan membosankan untuk diikuti.
• Lebih rumit dan hanya mengoptimalkan kode lebih dari keterbacaan di mana itu benar-benar diperlukan.

Perlakukan kode Anda sebagai dokumentasi

Kode Anda adalah dokumentasi utama Anda. Ini persis menggambarkan apa yang dihasilkan aplikasi, perpustakaan atau apa pun, sebenarnya. Dengan demikian, setiap upaya untuk mempercepat pemahaman kode itu harus dimulai dengan kode itu sendiri.

Ada banyak tulisan tentang cara menulis kode yang dapat dibaca, tetapi beberapa poin utama adalah:

• jangan mengandalkan komentar untuk menjelaskan kode buruk, buat kode lebih baik dan singkirkan komentar,
• tulis fungsi, metode, kelas pendek dll,
• gunakan nama yang sesuai dengan konteks (mis. nbaik untuk satu lingkaran, nama deskriptif yang lebih panjang diperlukan untuk item dengan cakupan lebih besar),
• memperlakukan nama fungsi seolah-olah itu adalah komentar, mis. jangan gunakan UpdtTbldengan komentar yang menjelaskan pembaruan tabel dengan aturan yang disediakan saat UpdateTableContentsWithSuppliedRulesdapat digunakan sebagai namanya,
• menghindari mutabilitas. Setiap kali Anda mengubah konten variabel, Anda menambah kompleksitas kode. Tetapkan nilai baru itu ke variabel baru (dengan nama baik) jika memungkinkan.
• terakhir, dan yang paling penting, hindari kode "pintar". Satu-satunya kode pintar yang nyata adalah kode yang mudah dibaca. Jika Anda menulis sedikit kode kompleks dan mendapati diri Anda berpikir "wow, bukankah saya pandai di sini?", Jawabannya hampir dijamin "tidak, Anda tidak".

Menjadi lebih baik dalam membaca kode

Membaca kode, terlepas dari betapa sederhananya, adalah keterampilan yang dipelajari. Tidak seorang pun yang pandai membaca kode. Dibutuhkan latihan; banyak latihan. Jadi, misalnya, buka Github atau apa pun dan baca kode perpustakaan yang Anda gunakan, daripada hanya menggunakan perpustakaan itu. Temukan kode untuk dibaca dan dibaca.

Komentar adalah bau kode

Hanya dengan begitu kita sampai pada jenis dokumentasi lain. Pertama, seperti yang dinyatakan sebelumnya, hindari komentar. Jika saya menemukan kode yang berisi komentar, saya bersiap untuk yang terburuk: kode kemungkinan besar akan buruk, dan jujur ​​komentar cenderung juga buruk. Seseorang yang tidak dapat berkomunikasi dengan baik melalui kode tidak mungkin dapat berkomunikasi dengan lebih baik melalui bahasa alami.

Waspadai dokumentasi API yang dibuat secara otomatis

Juga, berhati-hatilah dokumentasi API yang dibuat secara otomatis. Jika saya terpaksa membaca dokumen seperti itu, itu karena kode Anda sangat sulit dibaca. Sekali lagi, buat kodenya sederhana dan saya bisa membacanya langsung.

Tes juga dokumen

Tes juga merupakan dokumentasi. Jadi jangan anggap tes unit Anda sebagai tugas. Perlakukan mereka sebagai cara berkomunikasi dengan orang lain (enam bulan kemudian Anda termasuk di sini) tentang bagaimana kode bekerja dan dimaksudkan untuk digunakan.

Buat gambar jika itu membantu

Jika Anda menyukai UML, berarti Anda mendapatkan alat yang bagus dan menghasilkan diagram UML dari kode Anda. Tidak pernah mencoba menggunakannya untuk menghasilkan kode. Ini tidak baik sebagai alat desain dan Anda akan berakhir dengan kode yang mengerikan sebagai hasilnya.

Memiliki dokumen tampilan "1000ft"

Terakhir, tulis sendiri dokumen ikhtisar. Apa yang dilakukan aplikasi? Bagaimana cara melakukannya? Sistem lain apa yang terhubung? Hal-hal seperti itu. Jangan mencoba menggambarkan struktur kode di sini. Biarkan kode melakukan itu. Biarkan dokumen ini mengingatkan Anda mengapa Anda menulis kode di tempat pertama.

Berikan surat pengantar

Kecuali jika Anda berada dalam domain yang sangat teknis, sebagian besar pertanyaan seputar kode tidak akan mengenai 'bagaimana' tetapi tentang 'mengapa' atau 'apa'.

Dengan demikian, cara untuk mengurangi orang dari harus melihat kode Anda, adalah dengan menulis deskripsi singkat tentangnya. Keuntungan dari ini adalah Anda dapat menyusun ikhtisar deskripsi dengan cukup mudah, dan ini jauh lebih mudah diakses. (Bahkan kepada orang-orang yang tidak akan / tidak diizinkan melihat kode).

Bahkan jika orang teknis, surat pengantar harus menawarkan panduan di mana mereka harus mencari sesuatu.

Poin sederhana yang sangat minimalis:

1. Pendahuluan, mengapa kode ini (basis) ada
2. Fungsi apa yang dipenuhi oleh subset kode
3. Di mana kodenya (nama skrip misalnya)

Contoh

1. Rangkaian skrip ini mengikis StackOverflow dan mengungguli jawaban oleh Dennis Jaheruddin
2. Sebuah. Skrip ini bertanggung jawab untuk menguraikan html, dan menganalisis apakah itu pengguna yang tepat
3. Sebuah. Script ini ditemukan di: ScrapeAndVote / RecognizeDennis.scr

Keuntungan kecepatan terbesar yang biasanya saya dapatkan dari membangun komit terpisah yang masing-masing mewakili langkah perantara yang mengkompilasi dan bekerja.

Jadi jika saya harus memperkenalkan parameter baru ke fungsi untuk mengimplementasikan fitur tertentu, maka ada satu komit yang tidak melakukan apa-apa selain menambahkan parameter dalam deklarasi, dalam definisi dan di semua situs panggilan. Kemudian, komit berikutnya memperkenalkan fungsionalitas, dan yang ketiga memperbarui situs panggilan yang memanfaatkan fitur baru.

Ini mudah ditinjau, karena perubahan mekanis murni dapat dilirik dengan cepat, dan kemudian menyingkir.

Demikian pula, jika Anda memformat ulang kode, itu harus selalu berupa komit terpisah.

Meskipun ada satu atau dua poin ketidaksepakatan di antara jawaban yang ada, jika hanya dalam penekanan, saya akan mencoba merangkum saran yang biasa dengan cara yang menjelaskan dari mana semua orang berasal:

1. Pertama, tulis kode bersih; "dokumentasi" lainnya akan mengurus dirinya sendiri setelah itu. Kode bersih adalah seperangkat prinsip untuk dipelajari di tempat pertama: kelas tanggung jawab tunggal, metode pendek yang melakukan satu hal, nama variabel dan metode yang baik , nama kelas / tipe yang lebih baik daripada ini dengan berfokus pada metafora (mis. Sebut MultiButtSupporter a soda), unit test untuk menunjukkan persyaratan, KERING, SOLID, paradigma yang konsisten dan sebagainya.
2. Kode mengungkapkan cara kerja kode; komentar mengungkapkan mengapa kode berfungsi. Misalnya, jelaskan +1 dengan "mencegah kesalahan karena kesalahan 1", atau rumus rumit dengan "yang diturunkan dalam buku pelajaran atau halaman web ini".
3. Apa pun yang Anda lakukan dengan komentar, poin 1 di atas mungkin dapat mencapainya dalam kode bersih. Lihat komentar sebagai kegagalan / kejahatan yang diperlukan, atau bahkan kebohongan jika seiring waktu mereka tidak sinkron dengan kode karena keduanya diedit. Komentar tidak boleh mengkompensasi kode yang ditulis dengan buruk, karena mengapa komentar ditulis dengan talenta atau perhatian lebih daripada kode itu?

Di sisi lain, jika ada sesuatu yang saya mungkin salah terlalu jauh, hampir tidak pernah menggunakan komentar. Peninjau kode Anda akan memberi tahu Anda jika Anda mendapatkan keseimbangan di tempat yang salah untuk mereka, tetapi jika Anda secara sadar mengikuti rencana 3 poin di atas, Anda mungkin akan tetap mendekati yang optimal.