[ithkuil]

yeah. I've seen a lot of comments like:

    // Sleep for 10 minutes
    sleep(15*60)

Unfortunately, the compiler cannot check your comments. Don't put facts that are better looked up in the actual code and that they only risk getting out of sync with the code.

[athenot]

That's a useless comment. A better one would be:

    // Prevent the two tasks from running right after each other,
    // to reduce load when this is run frequently
    sleep(15*60)

Even the most junior dev can infer that a multiplication by 60 for a sleep function probably means the unit is seconds and we want 15 minutes. No need to spell that out. But why sleep for 15 minutes and not just carry on to the next task? THAT is what the comment is for.

[Clubber]

Exactly. Comments are for intent, not what the code does. If I want to know what the code does, I can just read the code.

[crdoconnor]

I've found a better approach to comments is not to put them in at all.

Then, you raise a PR, have a code review, and whatever the other developer is confused about that you had to explain to them - that's where you needed a comment and what you explained to them is what the comment should be.

Developers who have their "head in the code" will almost always (unless they are very smart and very empathetic) fail to realize what is hard for other developers to understand because they will fail to accurately model to context which the other developer has.

[BoorishBears]

And to keep with the theme of self-documenting, the self-documenting version of that would be:

    NAP_LENGTH_MINUTES = 15;
    ...
    sleep(NAP_LENGTH_MINUTES*60);

[Clubber]

Still not good enough. Why is this nap function in there? If I want to make it faster and didn't know, I would just remove all references to it. What did I break? Can't tell by that variable name.

[BoorishBears]

a) Self documenting doesn't mean no comments

b) I didn't give enough context for your specific commentary to really make sense. I mean, when did I even say this is a function? It's a snippet of pseudo-code not a code sample.

c) Are you really running around programs ripping out references because you don't know what they do? I'd advise working on your definition of optimization before worrying about whether your code documents itself.

[Clubber]

>Self documenting doesn't mean no comments

Agree. I assumed you were giving an example of self documenting code that doesn't require comments.

>I didn't give enough context for your specific commentary to really make sense. I mean, when did I even say this is a function? It's a snippet of pseudo-code not a code sample.

Yes, sorry. I've just spend the last month digging into shitty code, so I'm in dealing with shitty code mode. My point was the name you gave it didn't give any intent as to why the application would be napping, which is probably the most important information. Of course, as you said, the owner function could be named properly in that way.

>Are you really running around programs ripping out references because you don't know what they do? I'd advise working on your definition of optimization before worrying about whether your code documents itself.

It's pretty common for developers to try to figure out why an application is running slow. If I saw that (sleep function), it would be an obvious sign of why it's slow. If I saw that I would immediately see it as a potential target of improvement. Unfortunately with just the label you provided and a poorly named owning function, I wouldn't have enough information to determine if it was removable because, again, I don't know why it is napping. I would then have to spend several minutes/hours/days ($$$) determine what the hell that nap was for. This could all be solved by a comment providing intent.

I would suggest instead of NAP_LENGTH_MINUTES, it would be NAP_TO_AVOID_PROCESS_COLLISION_LENGTH_MINUTES or something. Of course, naming things properly is one of the hardest things in computer science. :)

There are only two hard things in Computer Science: cache invalidation and naming things.

-- Phil Karlton