News for hackers. Stuff that matters.
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:

    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

There are no comments on this comment yet.