Lima petua penting untuk meningkatkan kebolehbacaan kod Python

Penterjemah |. Zhao Qingqi

Pengulas | orang lain dan tidak tahu di mana hendak bermula? Terdapat banyak kaedah dalam Python yang membantu kami memahami cara kerja dalaman kod, jadi apabila anda melihat kod dari awal atau menulis kod, lebih mudah untuk meneruskan dari tempat anda berhenti.

Di sini saya akan berikan anda satu contoh Kami mungkin mendapat kod seperti yang ditunjukkan di bawah. Ini bukan yang paling teruk, tetapi ada beberapa perkara yang perlu kami sahkan, seperti:

Apakah maksud f dan d dalam fungsi load_las_file?

• Mengapa kita perlukan untuk melakukannya dalam fungsi tanah liat?
• Apakah jenis yang diperlukan oleh fungsi ini?

Dalam artikel ini saya akan membincangkan 5 petua asas tentang cara meningkatkan kebolehbacaan apl/skrip anda melalui dokumentasi, input segera dan nama pembolehubah yang betul .

1. Komen

Perkara pertama yang boleh kita lakukan pada kod tersebut ialah menambahkan ulasan pada baris tertentu, tetapi berhati-hati untuk mengelak daripada mengulas terlalu banyak. Komen perlu menjelaskan mengapa kod itu berfungsi, atau mengapa sesuatu dilakukan dengan cara tertentu, dan bukannya cara ia dilaksanakan. Komen dalam Python biasanya dilengkapkan menggunakan tanda paun (#), yang boleh menjangkau satu baris atau berbilang baris.

Untuk ulasan berbilang baris, kami juga boleh menggunakan petikan berganda.

# Comment using the hashtag
# Another comment using the hashtag

Dalam contoh di bawah, beberapa ulasan telah ditambahkan pada kod untuk menerangkan cara baris kod tertentu berfungsi dan sebab:

"""
This is an example of
a multi-line comment
"""

2 . Penaipan eksplisit

Bahasa Python ditaip secara dinamik, yang bermaksud jenis pembolehubah hanya disemak semasa masa jalan. Selain itu, pembolehubah boleh menukar jenis semasa pelaksanaan kod. Penaipan statik, sebaliknya, melibatkan pengisytiharan jenis pembolehubah secara eksplisit dan tidak boleh berubah semasa pelaksanaan kod.

Pada 2014, PEP 484 memperkenalkan konsep pembayang jenis, yang kemudiannya diperkenalkan ke dalam Python 3.5. Ini membolehkan anda mengisytiharkan jenis pembolehubah secara eksplisit. Dengan menambahkan petunjuk jenis, anda boleh meningkatkan kebolehbacaan kod anda dengan ketara. Dalam contoh berikut, kita boleh lihat:

memerlukan dua parameter

• Jenis nama fail parameter ialah rentetan
• Jenis parameter start_depth ialah jenis apungan , dan nilai lalai parameter ini ialah Tiada
• Fungsi ini akan mengembalikan objek DataFrame panda

Mengikut pembayang jenis, kita boleh tahu dengan tepat fungsi Apa yang diperlukan, dan apa yang akan dikembalikan.

3. Rentetan dokumentasi

Rentetan dokumentasi ialah rentetan yang mengikuti fungsi atau definisi kelas. Docstrings ialah cara yang bagus untuk menerangkan secara terperinci fungsi fungsi, hujah yang diperlukan, pengecualian yang akan dibuang, nilai pulangannya dan banyak lagi. Selain itu, jika anda menggunakan alat seperti Sphinx untuk membuat dokumentasi dalam talian untuk kod anda, docstrings akan diekstrak secara automatik dan ditukar kepada dokumentasi yang sesuai. Contoh berikut menunjukkan docstring untuk fungsi bernama clay_volume. Di sini kita boleh menentukan maksud setiap parameter. Ini menjadikannya lebih terperinci daripada pembayang jenis asas. Anda juga boleh memasukkan lebih banyak maklumat tentang metodologi di sebalik fungsi, seperti rujukan akademik atau persamaan.

Rentetan dokumen juga sangat membantu apabila kita memanggil fungsi di tempat lain dalam kod. Sebagai contoh, semasa menulis kod menggunakan Visual Studio, anda boleh menuding pada panggilan fungsi dan melihat pop timbul yang menunjukkan fungsi dan perkara yang diperlukan oleh fungsi tersebut.

Jika anda menggunakan Visual Studio Code (VS Code) untuk mengedit kod Python anda, anda boleh menggunakan sambungan seperti autoDocstring untuk memudahkan proses mencipta docstrings. Anda boleh memasukkan tiga petikan berganda dan templat yang lain akan diisi secara automatik. Anda hanya perlu mengisi butiran.

Petua: Jika anda telah mengisytiharkan jenis dalam parameter, ia akan dipilih secara automatik.

4. Nama pembolehubah yang boleh dibaca

Kadangkala, apabila anda menulis kod, anda tidak terlalu mengambil berat tentang nama pembolehubah, terutamanya apabila masa sempit. Walau bagaimanapun, jika anda kembali dan melihat kod tersebut dan anda menemui satu siri pembolehubah bernama x1 atau var123, anda mungkin tidak faham pada pandangan pertama apa yang diwakilinya. Dalam contoh di bawah, terdapat dua pembolehubah f dan d. Kita boleh meneka maksud pembolehubah tersebut dengan melihat bahagian lain kod, tetapi ini boleh mengambil masa, terutamanya jika kod itu panjang.

Jika kita memberikan pembolehubah ini nama yang sesuai, kita akan dapat mengetahui bahawa salah satu pembolehubah ialah data_file yang dibaca oleh panggilan lasio.read() dan kemungkinan besar data asal. Pembolehubah data memberitahu kami bahawa ini adalah data sebenar yang kami hadapi.

5. Elakkan nombor ajaib

Nombor ajaib ialah nilai dalam kod yang mempunyai makna yang tidak dapat dijelaskan di belakangnya dan boleh menjadi pemalar. Menggunakan ini dalam kod boleh menyebabkan kekaburan, terutamanya jika anda tidak biasa menggunakan nombor dalam pengiraan. Selain itu, jika kita mempunyai nombor ajaib yang sama di beberapa tempat, apabila ia perlu dikemas kini, kita perlu mengemas kini setiap kejadiannya. Walau bagaimanapun, jika nombor tersebut diberikan pembolehubah dinamakan yang sesuai, proses penggantian menjadi lebih mudah. Dalam contoh di bawah, kita mempunyai fungsi yang mengira nilai yang dipanggil hasil dan mendarabkannya dengan 0.6. Apakah maksudnya? Adakah faktor penukaran itu Skalar? Dalam kes ini, nisbah tanah liat kepada syal digunakan untuk menukar indeks sinar gamma kepada isipadu tanah liat.

6. Kod Akhir

Selepas menggunakan petua di atas, kod akhir kami kini kelihatan lebih bersih dan lebih mudah difahami.

7. Ringkasan

Menambah penjelasan pada kod anda melalui ulasan dan docstrings boleh membantu anda dan orang lain memahami perkara yang dilakukan oleh kod tersebut. Ia mungkin terasa seperti tugas pada mulanya, tetapi dengan penggunaan alat dan latihan biasa, ia akan menjadi sifat kedua.

Pautan asal: https://towardsdatascience.com/5-essential-tips-to-improve-the-readability-of-your-python-code-a1d5e62a4bf0

Pengenalan Penterjemah

Zhao Qingyu, editor komuniti 51CTO, telah terlibat dalam pembangunan pemandu selama bertahun-tahun. Minat penyelidikannya termasuk OS selamat dan bidang keselamatan rangkaian, dan dia telah menerbitkan paten berkaitan rangkaian.

Atas ialah kandungan terperinci Lima petua penting untuk meningkatkan kebolehbacaan kod Python. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!