

Yes, your code does need comments. - __hudson__
http://mikegrouchy.com/blog/2013/03/yes-your-code-does-need-comments.html

======
h2s
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>

------
Hermel
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.

~~~
Joeri
I don't agree with this definition of intent. For me _intent_ is about why a
piece of code is written the way that it is, which is also what the article
itself equates it to.

Also, I don't think you can write many useful comments when returning to a
piece of already written code. The only way to understand the why of a piece
of code is to trace all its implications, and it is not efficient to make that
sort of investment after the fact. The easiest way to produce high quality
comments is to write them during the act of programming.

------
178
So, when thought through, what he is proposing is just "Literate Programming"
<[http://en.wikipedia.org/wiki/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.

