Debo admitir que no estoy de acuerdo con algunas de las cosas que recomiendan las otras respuestas, así que voy a tirar mis dos centavos;
Comentarios
La documentación es extremadamente útil para los extraños que leen su código. Por lo general, muchas cosas no serán lo suficientemente detalladas como para ser leídas y entendidas de inmediato, y luego debe explicar lo que está haciendo.
Editar : la discusión en la sección de comentarios ha señalado algo correcto: los comentarios excesivos generalmente se realizan al escribir código incorrecto .
Comentar tu trabajo debe ser preciso y mínimo, pero, en mi opinión, definitivamente debe estar presente. Al menos un comentario por cada 15 líneas de código. Por ejemplo, encima de los bloques en el código, agregue una línea sobre lo que está haciendo:
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
Los comentarios mínimos que explican por qué y qué está haciendo son muy útiles en todo el código. No estoy de acuerdo con la respuesta que dice
Si me encuentro con un código que contiene comentarios, me preparo para lo peor: es probable que el código sea malo y, para ser sincero, es probable que los comentarios también sean malos.
Muchas veces, con gracia, se documenta un buen código. Es cierto que los programadores malos ven su documentación como "Muy bien, mi código es malo, agreguemos algunas oraciones para aclararlo".
Sí, y aunque esto ocurre bastante, también es cierto que los buenos programadores que escriben código limpio también quieren asegurarse de que regresen a su código y entiendan por qué quieren que su función se comporte así, o por qué lo necesitaban. línea que parece un poco redundante, etc.
Sí, los comentarios que explican cosas obvias, los comentarios que no están claros, los comentarios que se reunieron para asegurarse de que "este código está documentado, sí, lo que sea", son olores de código. Hacen que leer el código sea más difícil e irritante. (Añadiendo un ejemplo a continuación)
# Logging into Gmail when the module is imported
_client = login()
def get_client():
global _client
return _client
Ejemplo de aclaración: "No hay mierda, Sherlock. ¿Se _client = login()conecta al servicio de correo?
Más aclaraciones: el login()método no tiene relación con el login()método del ejemplo anterior.
Pero los comentarios que coinciden con las normas, explican las de por qué y no el cómo, y responder a las preguntas correctas , son muy, muy ( muy ) votos.
Comentarios en línea
Una cosa que NO debe hacer (y si pudiera escribir más grande, lo haría) es escribir sus comentarios en la misma línea del código. Hace comentarios muy específicos de línea, lo que pierde por completo el propósito de comentar su código.
Por ejemplo, malos comentarios en línea:
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
Sería mucho más fácil leer y comprender este código sin los comentarios, que lo hacen desordenado e ilegible.
En cambio, los comentarios dentro de su código deben colocarse sobre los bloques en el código, y deben responder las preguntas importantes que pueden surgir al leer el bloque de código.
# 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)
Mucho más claro, ¿verdad? Ahora también sabe que debe usar la login()función y proporcionar los parámetros send_mail()con todo lo que usó. Ayuda un poco, pero aún falta una cosa.
Documentación de la función
Ha sido ampliamente discutido. Siempre debe informar a sus lectores de qué se trata su función, por qué y para qué sirve. Cómo lo hace, esto no pertenece a la documentación, sino quizás a las notas al pie de la función.
Debe describir claramente lo que espera que sean sus parámetros, y si desea que se obtengan / creen en un método específico. Debe declarar qué debe devolver su función, cuál es su uso, etc.
Nuevamente, esa es mi opinión y metodología al escribir mi código. No solo esos, sino que son solo algunas de las cosas sobre las que no podría estar de acuerdo con las otras respuestas. Ah, y por supuesto, no solo los comentarios leen su código, sino su propio código. Escriba código limpio, comprensible y mantenible . Piensa en tu futuro mientras codificas ;-)