Hacker News Reader

Comment by Carpetsmoker | Hacker News Reader

The rules in your last paragraph make perfect sense; documenting the purpose of the code is probably the most important.

I think what is intended in general are comments in the form of:

    // Start the loop.
    while ( have_posts() ) : the_post();

    [..]

    // End the loop.
    endwhile;

And yes, that is an actual example from a real codebase.

This is an extreme example, but quite a few of comments I see are very redundant. Sometimes comments are useful to split stuff up, but stuff like "start loop", yeh nah. It's just a random stray comment, probably as an artefact from when the author was gathering their thoughts and/or took a break.

Even worse are comments that are just confusing, or don't match the code.

I've done some literate programming, and I find it interesting for certain types of programs and/or if you're struggling with something. But I think that for a lot of stuff it's redundant.

View on HN

This is actually a bad example. "The Loop" is a concrete concept within WordPress: it's a global loop (shared across scripts) that represents the portion of the request processing spent looping through the posts that need to get rendered to the page. There are a number of WordPress API calls that only make sense when called from "in the loop", since they rely on global variables that get set in each iteration. Whether or not this is actually a good request handling model is much more debatable, but the comments in your example are meant to communicate that any code which needs to be called from The Loop should get called between them.

If I understand what the Loop is, then I know what endwhile does.

Not really, because there could be any number of "whiles" in between unrelated to the main capital-L Loop (e.g. to loop over the tags of each single post).

> It's just a random stray comment, probably as an artefact from when the author was gathering their thoughts and/or took a break.

In my highschool introduction to programing class, we were for a long time required to comment every line of code. Examples given by the teacher were all this type of comment.

I've no doubt it put the wrong idea into some students' heads.

> Sometimes comments are useful to split stuff up

So often when I see this I wish people would have used another function. Its hard to argue that a function which requires splitting things up using comments is "doing one thing".

It's supposed to do one thing at some level of abstraction/encapsulation. It can do multiple lower-level things in the service of that.

Function calls have clutter overhead.

Comments are for when you do something that looks obviously stupid, and you need to justify your failure.

Way too many people here are confusing comments with documentation.

We have a winner.

A great approach to this is Python's docstrings, which parse to the naked eye as comments but can be rendered into proper documentation.

Reply on news.ycombinator.com