Yes, your code does need comments.

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

Generally, he is right. But he gets this point wrong:

> Comments are the only way to capture the intent of the code at the time of writing.

The main and most important way to express intent is meaningful naming of variables, fields, and methods. A declaration like "String username" conveys much more intent than "String x". Similarily, if you have a block of code that needs a comment, you should first move it into a separate method with a good name. Then, if it still needs commenting, you should comment on that method.

Also, with comments, it is like everything that improves your code: there is a tradeoff between effort and effect. If you have one hour to improve your code, where do you invest it? Cleaner structure? Better namings? More comments? More tests? UML-Diagrams? Flow charts? Other documentation? Adding features? Something else? Comments are unlikely to take the top spot here.

So, when thought through, what he is proposing is just "Literate Programming" <http://en.wikipedia.org/wiki/Literate_programming>.

It has been around since Knuth coined it in the seventies, but I guess it is one of those concepts just bound to be "reinvented" by every new generation.