5 ms·

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 ar

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.

VBprogrammer 8y ago
> 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".
- AlexCoventry 8y ago
  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.
- hopler 8y ago
  Function calls have clutter overhead.
jdormit 8y ago
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.
- hopler 8y ago
  If I understand what the Loop is, then I know what endwhile does.
  - coldtea 8y ago
    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).
diminoten 8y ago
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.
- thanatropism 8y ago
  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.
Izkata 8y ago
> 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.

VBprogrammer 8y ago

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

AlexCoventry 8y ago
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.
hopler 8y ago
Function calls have clutter overhead.

jdormit 8y ago

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.

hopler 8y ago
If I understand what the Loop is, then I know what endwhile does.
- coldtea 8y ago
  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).

diminoten 8y ago

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.

thanatropism 8y ago
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.

Izkata 8y ago

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