[talmand]

Wouldn't that function name have to be more like setTemperatureTo350ToCookPerfectly400WillBurn300WillMush to match what the comment is saying?

What if later it is determined that the proper temperature should instead be 375 because at 350 they aren't quite cooked enough?

[kondro]

And what would happen in the original?

People have a tendency to believe what the comment says, even when the code says something completely different.

It's easy to say that you would update both the comment and the value at the same time. But I've seen mismatched comments in code all the time for even a contrived example like this. And then what do you believe? Is the comment right with an incorrect implementation, or is the implementation right with an incorrect comment?

[NateDad]

Never replicate the code in the comment, then the comment won't be lying when the code changes.

This is a poor example to work off of. You'd probably have something like RECIPE_TEMPERATURE = 350, which you could then tweak to 375 if you needed to...

A more effective example would be

oven.Temp = RECIPE_TEMPERATURE

// we have to wait for the oven to preheat

thread.sleep(time.Minutes * 5)

oven.contents += cookies

Could you make that second line of code into a function preheatOven()? Sure. And your code would be less readable, because you have to break context to go see what the function does... only to find it's one stupid line.

Method names are not comments. They are hints at what the code does. They should not explain why the code is doing it (because the why almost always requires a lot more space than you can fit into a reasonably sized method name).