ฉันต้องยอมรับว่าฉันไม่เห็นด้วยกับสิ่งที่คำตอบอื่น ๆ แนะนำดังนั้นฉันจะโยนสองเซ็นต์ของฉัน
ความคิดเห็น
เอกสารมีประโยชน์อย่างยิ่งสำหรับคนแปลกหน้าที่อ่านรหัสของคุณ โดยปกติหลายสิ่งหลายอย่างจะไม่เพียงพอที่จะอ่านและเข้าใจได้ในทันทีและจากนั้นคุณควรอธิบายสิ่งที่คุณกำลังทำ
แก้ไข : การสนทนาในส่วนความคิดเห็นได้ชี้ให้เห็นสิ่งที่ถูกต้อง - โดยทั่วไปแล้วการแสดงความคิดเห็นมักจะทำเมื่อเขียนโค้ดไม่ดี
การแสดงความคิดเห็นงานของคุณควรแม่นยำและน้อยที่สุด แต่ในความคิดของฉันควรนำเสนอแน่นอน อย่างน้อยความคิดเห็นสำหรับรหัส 15 บรรทัดทุกบรรทัด ตัวอย่างเช่นด้านบนของบล็อกในรหัสเพิ่มบรรทัดเกี่ยวกับสิ่งที่คุณกำลังทำ:
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
ความคิดเห็นขั้นต่ำที่อธิบายว่าทำไมและสิ่งที่คุณทำมีประโยชน์มากตลอดทั้งรหัส ฉันไม่เห็นด้วยกับคำตอบที่ระบุ
หากฉันเจอโค้ดที่มีความคิดเห็นฉันจะเตรียมตัวสำหรับสิ่งที่แย่ที่สุด: โค้ดน่าจะแย่และความจริงแล้วความคิดเห็นนั้นก็น่าจะแย่เช่นกัน
มีการบันทึกไว้ในรหัสที่ดีหลายครั้ง เป็นเรื่องจริงที่โปรแกรมเมอร์ที่ไม่ดีจะเห็นเอกสารของพวกเขาเช่น "เอาล่ะโค้ดของฉันไม่ดีลองเพิ่มประโยคสองสามประโยคเพื่อให้ชัดเจนขึ้น"
ใช่และในขณะที่สิ่งนี้เกิดขึ้นค่อนข้างมากก็เป็นความจริงที่โปรแกรมเมอร์ที่ดีที่เขียนโค้ดสะอาดต้องการให้แน่ใจว่าพวกเขากลับไปที่รหัสของพวกเขาและเข้าใจว่าทำไมพวกเขาต้องการให้ฟังก์ชันของพวกเขาทำงานเช่นนั้นหรือทำไมพวกเขาต้องการ บรรทัดที่ดูเหมือนซ้ำซ้อนเล็กน้อย ฯลฯ ...
ใช่ความคิดเห็นที่อธิบายสิ่งที่ชัดเจนความคิดเห็นที่ไม่ชัดเจนความคิดเห็นที่รวบรวมไว้เพื่อให้แน่ใจว่า "รหัสนี้มีการบันทึกไว้ไม่ว่าอะไรก็ตาม" เป็นกลิ่นรหัส พวกเขาทำให้การอ่านรหัสยากขึ้นและน่ารำคาญ (การเพิ่มตัวอย่างด้านล่าง)
# Logging into Gmail when the module is imported
_client = login()
def get_client():
global _client
return _client
ตัวอย่างคำอธิบาย: "ไม่น่ากลัว Sherlock จะ_client = login()เข้าสู่บริการอีเมลหรือไม่ OMG!"
การชี้แจงเพิ่มเติม: login()วิธีการไม่มีความสัมพันธ์กับlogin()วิธีการจากตัวอย่างข้างต้น
แต่ความคิดเห็นที่ตรงกับมาตรฐานอธิบายว่าทำไมและไม่ใช่วิธีการและตอบคำถามที่ถูกต้องมีประโยชน์มาก ( มาก )
ความคิดเห็นแบบอินไลน์
สิ่งหนึ่งที่คุณไม่ควร(และถ้าฉันสามารถเขียนสิ่งที่ใหญ่กว่าได้) ฉันจะเขียนความคิดเห็นของคุณในบรรทัดเดียวกันของรหัส มันทำให้ความคิดเห็นที่เฉพาะเจาะจงมากบรรทัดซึ่งพลาดจุดประสงค์ในการแสดงความคิดเห็นรหัสของคุณอย่างสมบูรณ์
ตัวอย่างเช่นความคิดเห็นแบบอินไลน์ที่ไม่ดี:
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
จะง่ายต่อการอ่านและทำความเข้าใจกับรหัสนี้มากขึ้นโดยไม่ต้องแสดงความคิดเห็นที่ทำให้ยุ่งและอ่านไม่ได้
แต่ความคิดเห็นภายในโค้ดของคุณควรอยู่เหนือบล็อคของโค้ดและควรตอบคำถามสำคัญที่อาจเกิดขึ้นขณะอ่านบล็อคโค้ด
# 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)
ชัดเจนกว่านี้ใช่ไหม ตอนนี้คุณก็รู้ว่าคุณต้องใช้login()ฟังก์ชั่นและให้พารามิเตอร์send_mail()กับทุกสิ่งที่คุณใช้ ช่วยเล็กน้อย แต่มีสิ่งหนึ่งที่ขาดหายไป
เอกสารประกอบการใช้งาน
ได้มีการพูดคุยกันอย่างกว้างขวาง คุณควรแจ้งให้ผู้อ่านของคุณรู้ว่าหน้าที่ของคุณคืออะไรทำไมและทำอะไร มันทำอย่างไรสิ่งนี้ไม่ได้อยู่ในเอกสาร แต่อาจเป็นเชิงอรรถของฟังก์ชัน
คุณควรอธิบายอย่างชัดเจนถึงสิ่งที่คุณคาดหวังว่าพารามิเตอร์ของคุณจะเป็นและถ้าคุณต้องการให้พวกเขาได้รับ / สร้างในวิธีการเฉพาะ คุณควรประกาศสิ่งที่ฟังก์ชั่นของคุณควรกลับมาสิ่งที่มันใช้คืออะไรเป็นต้น
อีกครั้งนั่นคือความคิดเห็นและวิธีการของฉันในขณะที่เขียนรหัสของฉัน ไม่เพียงเท่านั้น แต่เป็นเพียงบางสิ่งที่ฉันไม่สามารถเห็นด้วยกับคำตอบอื่น ๆ โอ้และแน่นอนว่าไม่ใช่แค่ความคิดเห็นที่อ่านรหัสของคุณ แต่รหัสของคุณเอง เขียนโค้ดสะอาดเข้าใจและบำรุงรักษาได้ คิดเกี่ยวกับตนเองในอนาคตของคุณในขณะที่เข้ารหัส ;-)