3 ms·
Nonsense. When you read the code you need to know what it does, not what the programmer had intended, then, and only then, will you stand any hope of fixing bug
by hnriot 13y ago
Nonsense. When you read the code you need to know what it does, not what the programmer had intended, then, and only then, will you stand any hope of fixing bugs.
well chosen function and variable names tell you the intention, if it's modular enough then it will all make sense when you read it.
If people could just get over this documentation phase that programming went through in the 80's and 90's due to languages containing obtuse syntax and being so low level you had to hold a dozen things in your head at once (I'm thinking of you COM) - but in this era, with languages that operate at a high level of abstraction the era of documenting the code is over.
"The code is the documentation only works if the code is immutable."
that's actually backwards. If you want to stand any chance of changing the code then it should be readable and well structured, not well documented.
- rikthevik 13y agoWhat I'm looking for in comments is the underlying assumptions and the "why" that was flying around in the author's head when they were doing it.
- wonderzombie 13y agoI'm skeptical. How do you know what's intended behavior and what isn't if you don't know why the code is structured the way it is? Understanding what it does is necessary but not sufficient. You risk introducing more bugs if you don't understand why the code does what it does. "well chosen function and variable names tell you the intention, if it's modular enough then it will all make sense when you read it." The two hardest things in computer science are concurrency and naming things. Oh, and off-by-one errors.
- PeterisP 13y agoIf the code doesn't match what's intended, it's most likely because the original implementator misunderstood it, or didn't think of a particular edge case - and thus the comments won't reflect that as well. You look at code to determine what exactly the system does, but in order to determine what exactly the system should do, you need to look at the users needs or the business process, the code+comments can't tell you that.
- hamburglar 13y ago> When you read the code you need to know what it does, not what the programmer had intended, then, and only then, will you stand any hope of fixing bugs. I'm talking about being a user/caller of code, not attempting to fix it. Of course you need to know the innards if you're going to fix it, but needing to know all the implementation details in order to even call a piece of code is counter-productive. It's needlessly time-consuming and it violates the concept of separation of concerns.
- nanidin 13y agoAny public API should be documented. I can spend all day reading your code trying to code against your API, or I can read the API docs & be on my merry way. When/if there is a bug, I can fix it so it adheres to the specified purpose/pre/post conditions.
- jheriko 13y ago> Any public API should be documented. very good point :)