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 use

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: if self.ssl: relay_host = smtplib.SMTP_SSL(hostname, self.port) else: relay_host = smtplib.SMTP(hostname, self.port) 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. http://www.informit.com/articles/article.aspx?p=1326509 http://www.informit.com/articles/article.aspx?p=1326509