4 ms·

That's because if the code is over some quality level (which can be measured with bugs count) then the source itself is implementation documentation. And system

That's because if the code is over some quality level (which can be measured with bugs count) then the source itself is implementation documentation. And systemd contains the more classic documentation of its behaviour for its end users.

simoncion 11y ago
> ...if the code is over some quality level (which can be measured with bugs count) then the source itself is implementation documentation. Oh, you summer child. In any complex software project, there's always a difference between the contract described by the system's specification and the contract described by the software as implemented. The big difference between the explicit contract of the documentation and implicit contract of the code is that -in areas on which the documentation is silent- the contract described by the code is subject to change at any time, without warning. Raymond Chen [0] has spilled much ink over customers who have gotten badly burned by changes in the implicit contract some time after they made use of something that the code permitted, but the documentation did not describe as possible and/or supported. [0] Microsoft most notable backwards-compatibility guru
- mateuszf 11y ago
  > In any complex software project, there's always a difference between the contract described by the system's specification and the contract described by the software as implemented. That's exactly the reason why source itself is better than implementation documentation - because it is always "current".
  - simoncion 11y ago
    You managed to miss the larger point. Perhaps these resources will be helpful. http://thecodelesscode.com/case/16 http://thecodelesscode.com/case/16 http://thecodelesscode.com/case/69 http://thecodelesscode.com/case/69
    - mateuszf 11y ago
      In the second story: The scribe showed that source code may be too detailed, but at the same time he showed that past view of the system will not accurate now if not updated constantly. Which is the point I'm making.
- mateuszf 11y ago
  Regarding allowed changes in implementation: If user behaviour doesn't change - why changes in implementation are wrong? Reimplementations can use the source code at one place in time and use that as a reference.

simoncion 11y ago

> ...if the code is over some quality level (which can be measured with bugs count) then the source itself is implementation documentation. Oh, you summer child. In any complex software project, there's always a difference between the contract described by the system's specification and the contract described by the software as implemented. The big difference between the explicit contract of the documentation and implicit contract of the code is that -in areas on which the documentation is silent- the contract described by the code is subject to change at any time, without warning. Raymond Chen [0] has spilled much ink over customers who have gotten badly burned by changes in the implicit contract some time after they made use of something that the code permitted, but the documentation did not describe as possible and/or supported. [0] Microsoft most notable backwards-compatibility guru

mateuszf 11y ago
> In any complex software project, there's always a difference between the contract described by the system's specification and the contract described by the software as implemented. That's exactly the reason why source itself is better than implementation documentation - because it is always "current".
- simoncion 11y ago
  You managed to miss the larger point. Perhaps these resources will be helpful. http://thecodelesscode.com/case/16 http://thecodelesscode.com/case/16 http://thecodelesscode.com/case/69 http://thecodelesscode.com/case/69
  - mateuszf 11y ago
    In the second story: The scribe showed that source code may be too detailed, but at the same time he showed that past view of the system will not accurate now if not updated constantly. Which is the point I'm making.
mateuszf 11y ago
Regarding allowed changes in implementation: If user behaviour doesn't change - why changes in implementation are wrong? Reimplementations can use the source code at one place in time and use that as a reference.