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
function setTemperatureToCookPerfectly() {
oven.setTemp(350);
}
function ensureReturnFromTimeTravelPossible() {
fluxCapacitor.setOption(THRESHOLD, 1.21E9)
}
To quote one of the Ruby Rogues, "A comment is a lie waiting to happen."
Granted I would personally do:
const int perfecttemperature = 350; // 400 will burn them, 300 they will be mushy
.....
oven.setTemp(brownie.perfecttemperature);
What if later it is determined that the proper temperature should instead be 375 because at 350 they aren't quite cooked enough?
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?
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).