Devo admitir que não concordo com algumas das coisas que as outras respostas recomendaram, então vou jogar meus dois centavos;
Comentários
A documentação é extremamente útil para estranhos que leem seu código. Geralmente, muitas coisas não serão detalhadas o suficiente para serem lidas e entendidas imediatamente, e você deverá explicar o que está fazendo.
Edit : a discussão na seção de comentários apontou algo certo - o excesso de comentários geralmente é feito ao escrever um código incorreto .
Comentar o seu trabalho deve ser preciso e mínimo, mas, na minha opinião, definitivamente deve estar presente. Pelo menos um comentário para cada 15 linhas de código. Por exemplo, além dos blocos de código, adicione uma linha sobre o que você está fazendo:
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
Comentários mínimos que explicam o motivo e o que você está fazendo são muito úteis em todo o código. Eu não concordo com a resposta que afirma
Se eu encontrar um código contendo comentários, me preparo para o pior: o código provavelmente será ruim e, para ser honesto, os comentários provavelmente também serão ruins.
Muitas vezes, graciosamente, um bom código é documentado. É verdade que programadores ruins veem sua documentação como "Tudo bem, meu código é ruim, vamos adicionar algumas frases para deixar mais claro".
Sim, e embora isso ocorra bastante, também é verdade que bons programadores que escrevem código limpo também querem ter certeza de que retornam ao código e entendem por que desejam que sua função se comporte dessa maneira ou por que eles precisam disso. linha que parece um pouco redundante, etc ...
Sim, comentários que explicam coisas óbvias, comentários que não são claros, comentários que foram reunidos para garantir que "este código esteja documentado, sim, seja o que for", tem cheiro de código. Eles tornam a leitura do código mais difícil e irritante. (Adicionando um exemplo abaixo)
# Logging into Gmail when the module is imported
_client = login()
def get_client():
global _client
return _client
Exemplo de esclarecimento: "Merda, Sherlock. Efetua _client = login()login no serviço de correio? OMG!"
Mais esclarecimentos: o login()método não tem relação com o login()método do exemplo acima.
Mas os comentários que fazem corresponder aos padrões, explicar o porquê de, e não o how da, e responder as perguntas certas , são muito, muito ( muito ) votos.
Comentários embutidos
Uma coisa que você NÃO deveria (e se eu pudesse escrever isso maior, faria) é escrever seus comentários na mesma linha do código. Faz comentários muito específicos de linha, o que perde completamente o objetivo de comentar seu código.
Por exemplo, comentários inline incorretos:
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
Seria muito mais fácil ler e entender esse código sem os comentários, que o tornam confuso e ilegível.
Em vez disso, os comentários dentro do seu código devem ser colocados acima dos blocos do código e devem responder às perguntas importantes que podem surgir durante a leitura do bloco 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)
Muito mais claro, certo? Agora você também sabe que precisa usar a login()função e fornecer os parâmetros send_mail()com tudo o que usou. Ajuda um pouco, mas ainda falta uma coisa.
Documentação de função
Tem sido amplamente discutido. Você deve sempre informar seus leitores sobre o que é sua função, por que e o que ela faz. Como isso acontece, isso não pertence à documentação, mas talvez às notas de rodapé da função.
Você deve descrever claramente o que espera que seus parâmetros sejam e se deseja que eles sejam obtidos / criados em um método específico. Você deve declarar qual deve ser a sua função, qual é o seu uso, etc.
Novamente, essa é minha opinião e metodologia ao escrever meu código. Não apenas essas, mas essas são apenas algumas das coisas com as quais não concordo com as outras respostas. Ah, e é claro, não apenas os comentários leem seu código, mas também o próprio código. Escreva um código limpo, compreensível e sustentável . Pense em seu futuro enquanto codifica ;-)