4 ms·

The fatal problem with the notion that the code is the documentation is the fact that the code only tells you what the code does, as opposed to what it's design

The fatal problem with the notion that the code is the documentation is the fact that the code only tells you what the code does, as opposed to what it's designed to do. How do you know a behavior you observe by reading the code isn't a bug which is going to be fixed next week? Or an arbitrary implementation detail that isn't guaranteed? That is what docs and interfaces and specs are for. "The code is the documentation" only works if the code is immutable.

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 ago
  What 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 ago
  I'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 ago
    If 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 ago
  Any 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 :)
benjiweber 13y ago
Tests tell you what the intended behaviours are. If there is no test then it is not intended. Tests are also both code and documentation.
- ArbitraryLimits 13y ago
  > Tests tell you what the intended behaviours Or, you know, the design can also. If you're into having that.
- kansface 13y ago
  This is a rather extreme opinion. I find tests to provide less value than they create most of the time. I think regression tests and integration tests are quite valuable. The former are created after the fact, and the later are often so difficult to do correctly that they are never made. Of course, this difficulty is the same reason why they are valuable.

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 ago
What 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 ago
I'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 ago
  If 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 ago
Any 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 :)

benjiweber 13y ago

Tests tell you what the intended behaviours are. If there is no test then it is not intended. Tests are also both code and documentation.

ArbitraryLimits 13y ago
> Tests tell you what the intended behaviours Or, you know, the design can also. If you're into having that.
kansface 13y ago
This is a rather extreme opinion. I find tests to provide less value than they create most of the time. I think regression tests and integration tests are quite valuable. The former are created after the fact, and the later are often so difficult to do correctly that they are never made. Of course, this difficulty is the same reason why they are valuable.