3 ms·
Something he misses is that good documentation isn't just an English translation of what the source code does, it's also a contract that describes what the sour
by btn 14y ago
Something he misses is that good documentation isn't just an English translation of what the source code does, it's also a contract that describes what the source code may or may not do now and in the future.
If "the source code is the ultimate truth", then your source code is indelible---you can never change your implementation because you've given users freedom to depend upon the behaviour produced by any line of it. If you don't want people depending on implementation details, then you need documentation to hide those away.
- elviejo 14y agoAgain go to the source... design by contract is a way to embed and execute the contracts in the source code is a great way to increase code quality. Take a look at the Eiffel programming language is impressive what having contracts in the code gives you.
- gbog 14y agoHum, in my world (Python) things that are implementation details and suggest to change are clearly marked by the underscore prefix. Test cases do show the interfaces and probe them. Thus reading the code give the clearest idea on the intended usage off three code .