3 ms·
> In the world of programming, where “it depends” is often the best answer and everything is based on trade-offs, writing becomes that much harder. It needs to
by xg15 6y ago
> In the world of programming, where “it depends” is often the best answer and everything is based on trade-offs, writing becomes that much harder. It needs to set the context, justify the decisions, and then power the low-level thinking leading into the code.
Might be that the author is talking about a different kind of documentation, but I believe describing the behaviour of a program in sufficiently detailed fashion and justifying why the program behaves like it does are two very different things.
The former is the task of the programmer and the audience is likely other programmers while the latter is the task of a product manager and the audience is likely higher-ups.
As a programmer who needs to interface with a particular API, I will be very thankful for a documentation that tells me exactly how the data to pass to the endpoint has to look and what kind of responses I have to handle. If there are any particular quirks, constraints or special cases I have to be aware of when using the API, the documentation must explain those as well.
But to be able to use an API, it's not necessary to know the exact decisions and tradeoffs that explain why the quirks and special cases are as they are.
- chaosite 6y agoProgrammers don't need documentation to describe what the program does, the code is already a perfect description of what it does. You need documentation to describe the intent that is not present in the code, i.e., why something is the way it is.
- xg15 6y ago> the code is already a perfect description of what it does. No it isn't. Code is a series of steps that in the right environment will lead to a particular behaviour. Code doesn't (automatically) tell you what that behaviour is - even less if that behaviour is also the intended behaviour. You can have "self-documenting code" to some extent, but even this code is often low-level, spread out over dozens of files and has to handle various cross-cutting concerns which are usually not of interest to you. This is why command line tools have manpages, even if the audience are programmers and the code is open source, so a user could theoretically learn everything by looking through the code.