Tôi phải thừa nhận rằng tôi không đồng ý với một số điều mà các câu trả lời khác đề nghị, vì vậy tôi sẽ ném hai xu của mình;
Bình luận
Tài liệu cực kỳ hữu ích cho những người lạ đọc mã của bạn. Thông thường nhiều thứ sẽ không đủ dài để được đọc và hiểu ngay lập tức, và sau đó bạn nên giải thích những gì bạn đang làm.
Chỉnh sửa : cuộc thảo luận trong phần bình luận đã chỉ ra điều gì đó đúng - bình luận quá mức thường được thực hiện khi viết mã xấu .
Nhận xét công việc của bạn nên chính xác và tối thiểu, nhưng, theo tôi, chắc chắn nên có mặt. Ít nhất là một nhận xét cho mỗi 15 dòng mã. Ví dụ: trên đầu các khối trên mã, hãy thêm một dòng về những gì bạn đang làm:
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
Nhận xét tối thiểu giải thích lý do và những gì bạn đang làm là rất hữu ích trong suốt mã. Tôi không đồng ý với câu trả lời rằng
Nếu tôi gặp phải mã chứa các bình luận, tôi sẽ chuẩn bị cho điều tồi tệ nhất: mã có khả năng là xấu và thành thật mà nói, các bình luận cũng có khả năng xấu.
Nhiều lần, duyên dáng, mã tốt được ghi lại. Đúng là các lập trình viên xấu nhìn thấy tài liệu của họ như "Được rồi, mã của tôi rất tệ, hãy thêm một vài câu để làm cho nó rõ ràng hơn".
Vâng, và trong khi điều này xảy ra khá nhiều, thì cũng đúng là các lập trình viên giỏi viết mã sạch cũng muốn đảm bảo rằng họ quay lại mã của họ và hiểu lý do tại sao họ muốn chức năng của họ hoạt động như vậy hoặc tại sao họ cần điều đó dòng có vẻ hơi dư thừa, v.v ...
Vâng, các bình luận giải thích những điều hiển nhiên, các bình luận không rõ ràng, các bình luận được đặt cùng nhau để đảm bảo rằng "mã này được ghi lại, yeah, sao cũng được", là mùi mã. Họ làm cho việc đọc mã khó khăn và khó chịu hơn. (Thêm một ví dụ dưới đây)
# Logging into Gmail when the module is imported
_client = login()
def get_client():
global _client
return _client
Ví dụ làm rõ: "Không shit, Sherlock. Có _client = login()đăng nhập vào dịch vụ thư không? OMG!"
Làm rõ hơn: login()phương thức không liên quan đến login()phương thức từ ví dụ trên.
Nhưng những bình luận không phù hợp với tiêu chuẩn, giải thích lý do tại sao chứ không phải như thế nào và trả lời đúng câu hỏi , rất hữu ích.
Nội dung bình luận
Một điều bạn nên KHÔNG (và nếu tôi có thể viết rằng lớn hơn, tôi sẽ) làm là viết bình luận của bạn trong cùng một dòng mã. Nó làm cho các bình luận rất cụ thể, mà hoàn toàn bỏ lỡ mục đích bình luận mã của bạn.
Ví dụ: bình luận nội tuyến xấu:
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
Sẽ dễ dàng hơn nhiều để đọc và hiểu mã này mà không có ý kiến, điều đó làm cho nó lộn xộn và không thể đọc được.
Thay vào đó, các bình luận bên trong mã của bạn nên được đặt phía trên các khối trên mã và chúng sẽ trả lời các câu hỏi quan trọng có thể phát sinh trong khi đọc khối mã.
# 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)
Rõ ràng hơn nhiều, phải không? Bây giờ bạn cũng biết rằng bạn phải sử dụng login()hàm và cung cấp các tham số cho send_mail()mọi thứ bạn đã sử dụng. Giúp một chút, nhưng một điều vẫn còn thiếu.
Tài liệu chức năng
Đã được thảo luận rộng rãi. Bạn nên luôn luôn cho độc giả của bạn biết chức năng của bạn là gì, tại sao và nó làm gì. Làm thế nào nó làm điều đó, điều này không thuộc về tài liệu, nhưng có thể là chú thích của chức năng.
Bạn nên mô tả rõ ràng những gì bạn mong đợi các tham số của mình và nếu bạn muốn chúng được lấy / tạo trong một phương thức cụ thể. Bạn nên khai báo chức năng của bạn sẽ trả về, công dụng của nó là gì, v.v.
Một lần nữa, đó là ý kiến và phương pháp của tôi trong khi viết mã của tôi. Không chỉ những điều đó, mà đó chỉ là một số điều tôi không thể đồng ý với các câu trả lời khác. Ồ, và tất nhiên, không chỉ các bình luận đọc mã của bạn, mà chính mã của bạn. Viết mã sạch, dễ hiểu và có thể duy trì . Nghĩ về bản thân tương lai của bạn trong khi viết mã ;-)