Yes, your code does need comments.

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

by __hudson__ • 13 years ago

15 4 13 years ago

Hermel• 13 years ago

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• 13 years ago

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.

h2s• 13 years ago

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

178• 13 years ago

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.

Yes, your code does need comments.

Related Stories