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 ;-)