3 ms·

Did anyone ever read the documentation? Serious question. I've spent a lot of effort writing internal and external documentation for various systems over the y

Did anyone ever read the documentation? Serious question. I've spent a lot of effort writing internal and external documentation for various systems over the years, and I'm not sure anybody ever read any of it.

tigroferoce 6y ago
I think that clean code is more useful than documentation. However in some cases it's not clear why some code was written that way, more than how it was written. In that case a couple of lines of documentation helps IMO. Also, if you write relatively small and short functions and you document the goal, the inputs and the result, then the code is quite self explanatory.
- nicklecompte 6y ago
  It really depends on the domain. I think your comment is generally true for “most code,” since most code involves relatively simple concepts familiar to most programmers, and is performing a fairly clear task. But there are many functions where it is reasonable to have even hundreds of words worth of comments: - anything that heavily uses intrinsics and requires the programmer to have a detailed mental model of the CPU in order to analyze (e.g. making an ASCII table of the register state at each major step of the program). Likewise with assembly programming, though obviously that’s a special case. - a particularly sophisticated graph-theoretic algorithm, for which the “comment” might be essentially a short CS paper explaining how the algorithm works, giving its time/space complexity, and proving correctness - the “main function” for simulating a physical or financial system, which might required detailed descriptions of the equations, parameters, and various options I am working on some compiler stuff and have taken to literate programming for basically everything that’s not a simple utility.
nicklecompte 6y ago
Yes - often a question would be answered just by pointing to the documentation or relevant comments in the code and I am sure my coworkers read the docs independently as needed. Though especially at my last job the domain logic was especially tricky (health research informatics / HIPAA stuff / etc) so that might mean documentation was unusually valuable in that particular job.
Igelau 6y ago
I read it, and I read its absence as well. If there is no (insert interface commenting format that your IDE can parse), that's a code smell. Too often the preceding devs didn't explain themselves because they couldn't.
Kluny 6y ago
No, but you can answer their question by linking to the doc or telling them the title of the doc to google it themselves.

tigroferoce 6y ago

I think that clean code is more useful than documentation. However in some cases it's not clear why some code was written that way, more than how it was written. In that case a couple of lines of documentation helps IMO. Also, if you write relatively small and short functions and you document the goal, the inputs and the result, then the code is quite self explanatory.

nicklecompte 6y ago
It really depends on the domain. I think your comment is generally true for “most code,” since most code involves relatively simple concepts familiar to most programmers, and is performing a fairly clear task. But there are many functions where it is reasonable to have even hundreds of words worth of comments: - anything that heavily uses intrinsics and requires the programmer to have a detailed mental model of the CPU in order to analyze (e.g. making an ASCII table of the register state at each major step of the program). Likewise with assembly programming, though obviously that’s a special case. - a particularly sophisticated graph-theoretic algorithm, for which the “comment” might be essentially a short CS paper explaining how the algorithm works, giving its time/space complexity, and proving correctness - the “main function” for simulating a physical or financial system, which might required detailed descriptions of the equations, parameters, and various options I am working on some compiler stuff and have taken to literate programming for basically everything that’s not a simple utility.

nicklecompte 6y ago

Yes - often a question would be answered just by pointing to the documentation or relevant comments in the code and I am sure my coworkers read the docs independently as needed. Though especially at my last job the domain logic was especially tricky (health research informatics / HIPAA stuff / etc) so that might mean documentation was unusually valuable in that particular job.

Igelau 6y ago

I read it, and I read its absence as well. If there is no (insert interface commenting format that your IDE can parse), that's a code smell. Too often the preceding devs didn't explain themselves because they couldn't.

Kluny 6y ago

No, but you can answer their question by linking to the doc or telling them the title of the doc to google it themselves.