[sankyo]

The comments that he shows are pretty worthless. However, comments are often necessary to explain WHY we are doing something.

oven.setTemp(350) // 400 will burn them, 300 they will be mushy

fluxCapacitor.setOption(THRESHOLD, 1.21E9) // lower thresholds will prevent return from time travel. Please see http://en.wikipedia.org/wiki/DeLorean_time_machine to review the physics

[kondro]

Both these are fixed by method extraction though.

  function setTemperatureToCookPerfectly() {
    oven.setTemp(350);
  }

  function ensureReturnFromTimeTravelPossible() {
    fluxCapacitor.setOption(THRESHOLD, 1.21E9)
  }

Now wherever you see these lines in your code, you know exactly what they are for.

To quote one of the Ruby Rogues, "A comment is a lie waiting to happen."

[katbyte]

In both those examples information about why the variable needs to be set to that specific value is lost. At some point the variable needs to be set and the more information on why it needs to be set to a particular value the better. You can't pack all the required information into a function name and i would dare say you shouldn't.

Granted I would personally do:

    const int perfecttemperature = 350; // 400 will burn them, 300 they will be mushy
    .....
    oven.setTemp(brownie.perfecttemperature);

but still comment it as to why i picked 350. Comments are for the why, and the why is the most thing to understand.

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

[shrub]

Until you change what those functions do, and then the function name lies.