İtiraf etmeliyim ki diğer cevapların önerdiği bazı şeylerle aynı fikirde değilim, bu yüzden iki kuruş atacağım;
Yorumlar
Belgeler, kodunuzu okuyan yabancılar için son derece yararlıdır. Genellikle birçok şey derhal okunacak ve anlaşılacak kadar ayrıntılı olmayacaktır ve daha sonra ne yaptığınızı açıklamalısınız.
Düzenleme : Yorum bölümündeki tartışma, bir şeyin doğru olduğuna işaret etti - aşırı yorumlama genellikle kötü kod yazarken yapılır .
Çalışmanızın yorumlanması kesin ve asgari düzeyde olmalı, ancak bence kesinlikle mevcut olmalı. Her 15 kod satırı için en az bir yorum. Örneğin, koddaki blokların üstüne, ne yaptığınız hakkında bir satır ekleyin:
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
Neden ve ne yaptığınızı açıklayan çok az yorum , kod boyunca çok faydalıdır. Belirtilen cevaba katılmıyorum
Yorum içeren kodla karşılaşırsam en kötüsüne hazırlanırım: kodun kötü olması ve dürüst olmak gerekirse yorumların da kötü olması muhtemeldir.
Çoğu zaman, incelikle, iyi kod belgelenmiştir. Kötü programcıların "Tamam, benim kodum kötü, daha açık hale getirmek için birkaç cümle ekleyelim" gibi belgelerini gördükleri doğrudur.
Evet, bu oldukça fazla olsa da, temiz kod yazan iyi programcıların aynı zamanda kodlarına geri döndüklerinden ve işlevlerinin neden böyle davranmasını istediklerini veya neden ihtiyaç duyduklarını anlamalarını sağlamak istedikleri de doğru. biraz gereksiz görünen çizgi, vb ...
Evet, bariz şeyleri açıklayan yorumlar, net olmayan yorumlar, "bu kodun belgelenmesi, evet, her neyse", kod kokusu olduğundan emin olmak için bir araya getirilen yorumlar. Kodu okumayı zorlaştırıyor ve rahatsız ediyor. (Aşağıya bir örnek ekleme)
# Logging into Gmail when the module is imported
_client = login()
def get_client():
global _client
return _client
Örnek açıklama: "Hiçbir şey yok Sherlock. _client = login()Posta hizmetine giriş yapıyor mu? OMG!"
Daha fazla açıklama: login()Yöntemin login()yukarıdaki örnekteki yöntemle ilişkisi yoktur .
Ama bunu yorum, standartlarına uygun neden 's değil nasıl en açıklamak ve doğru soruları cevaplamak , çok çok ( çok yararlı).
Satır içi yorumlar
Bir şey yapmanız gerekir DEĞİL (ve bunu daha büyük, ben ederim yazabilirsiniz varsa) yapmak, kod aynı çizgide yorumlarınızı yazmaya. Kodunuzu yorumlamanın amacını tamamen özleyen yorumları çok çizgiye özgü kılar.
Örneğin, kötü satır içi yorumlar:
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
Bu kodu yorum yapmadan okumak ve anlamak daha kolay olurdu, bu da dağınık ve okunamaz hale getirir.
Bunun yerine, kodunuzun içindeki yorumlar kod üzerindeki blokların üstüne yerleştirilmeli ve kod bloğunu okurken ortaya çıkabilecek önemli soruları yanıtlamalıdır.
# 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)
Çok daha net, değil mi? Artık, login()işlevi kullanmanız ve send_mail()kullandığınız her şey için parametreleri sağlamanız gerektiğini de biliyorsunuz . Biraz yardımcı olur, ancak bir şey hala eksik.
İşlev dokümantasyonu
Yaygın bir şekilde tartışılmıştır. Her zaman okuyucularınızın, işlevinizin ne olduğunu, neden ve ne yaptığını bilmelerini sağlamalısınız. Bu nasıl yapılır, bu belgelere değil, fonksiyonun dipnotlarına da aittir.
Parametrelerinizin ne olacağını ve belirli bir yöntemle elde edilmelerini / oluşturulmalarını istiyorsanız açık bir şekilde tanımlamalısınız. İşlevin ne döndüreceğini, ne işe yaradığını vb.
Yine, kodumu yazarken bu benim fikrim ve metodoloji. Sadece onlar değil, bunlar hakkındaki diğer cevapları kabul edemediğim şeylerden sadece birkaçı. Tabii ki, sadece yorumlar kodunuzu değil, kodunuzun da kendisini okur. Anlaşılır ve bakımı yapılabilir temiz kod yazın . Kodlama yaparken geleceğin özünü düşün ;-)