Those comments won't match the code in 6 months.
Edit to add: and in 6 months, instead of being one short page of code, it'll be 600 lines long and impossible to understand or modify safely
Edit to add: and in 6 months, instead of being one short page of code, it'll be 600 lines long and impossible to understand or modify safely
Yes, maybe it's the wrong abstraction or it won't match in 6 months because people will start calling Hats Pizzas and the logic will be different. Maybe I'll be dead tomorrow. I don't concern myself with what-ifs over unknowns.
I want correctness and some assurance of it. I don't think writing 50? tests to cover this thing is a good way to spend my time (or someone else's). I'll write the left hand side first. When I'm looking at writing tests, it will become something like the right hand side.
Yes linear code is more readable. That's something to consider, but it's not my primary consideration.
I've used many code review tools, all suffered from that. (the only exception wasn't a tool: print out of all the code to physical paper and then we all went into a meeting room to review for several hours - this was the best type of code review for finding things wrong, but it was also extremely expensive so I've only done that once in my life)
You are putting something in there that turns out to be disinformation.
I used to believe as you did, but then I started actually looking at old code.
I stored many examples, but I'll give you one to indicate just how bad most comments are:
//Add 1 to x x:=x+2;
Now why the original author thought it was important to explain in English what the next line of code was going to do in the programming language I am not sure.
I am sure that someone figured out that it was a mistake and did the least they could possibly do to fix the mistake.
Something like 80% or more of the comments I've seen have been misleading, wrong, or useless.
If you do your own survey of someone else's old code so that your ego doesn't get in the way you will probably find something similar.
Although I did talk with people working at NASA and they had someone on their code reviews who was specifically looking at comments. If you are that disciplined then your code will not be that bad, probably.
This is to avoid the introduction of bugs by tempting someone to refactor or "fix" your code.
A properly written code, with good naming conventions for parameters, variables and functions should be easy to understand without comments.
I should not need anyone to tell me the next few lines will
//Heat oven
That should be self explanatory by just looking at the code itself.