Re:Yes, your code does need comments.
by h2s on Thursday March 07, 2013 @03:50PM
(#5340152)
The example given is an example of using comments very effectively as a countermeasure against the confusion caused by imperfect code. Look what it actually uses that oh-so-well-documented ssl variable for:
Half the constructor parameters and the entire configure_relay function could be ditched completely if this class stuck to a single responsibility and instead allowed the configured smtplib object on which it depends to be injected.
Here's some more comments from that class:
def send(self, To, From, Subject, Body):
"""
Does what it says, sends an email. If you need something more
complex then look at lamson.mail.MailResponse.
"""
Look at that comment: "Does what it says, sends an email". It's a terrible comment. The method should be called send_email, and that sentence should be deleted.
This codebase is a poor example of how to use comments, overall.
def process_message(self, Peer, From, To, Data):
"""
Called by smtpd.SMTPServer when there's a message received.
"""
The above comment simply reiterates what happens in some unknown distant piece of code. This is a classic example of bad commenting: somebody could very easily change the behaviour of the referenced code without updating this comment.
Here's some more comments from that class:
Look at that comment: "Does what it says, sends an email". It's a terrible comment. The method should be called send_email, and that sentence should be deleted.This codebase is a poor example of how to use comments, overall.
The above comment simply reiterates what happens in some unknown distant piece of code. This is a classic example of bad commenting: somebody could very easily change the behaviour of the referenced code without updating this comment.http://www.informit.com/articles/article.aspx?p=1326509