5 ms·

There's a common refrain that internal documentation never gets updated and so it's better to just look at the code. IMHO outdated docs are still better than n

There's a common refrain that internal documentation never gets updated and so it's better to just look at the code. IMHO outdated docs are still better than no docs, you just have to approach them with an appropriate level of skepticism and archaeologist mindset. At the base level of course the code is the ultimate source of truth, and being able to navigate code history quickly (via something like the Fugitive vim plugin) is incredibly valuable, but higher levels of documentation such as code comments, commit messages, tech specs, product specs, and user documentation can give richer clues into the mindset of the team at the time. As such, I believe the single highest ROI thing you can do is to choose tools that automatically maintains history/edit timestamps for all docs (git obviously does this, but Google Docs and Quip also do quite well here).

FooBarWidget 6y ago
> you just have to approach them with an appropriate level of skepticism and archaeologist mindset The problem is most people don't have this mindset. They expect documentation to be right, and when it isn't, they become frustrated and learn to avoid documentation.
MereInterest 6y ago
I think the big difference is what type of information you're looking for. The code is the final arbiter on what the program does, but gives incredibly little information about why it is designed that way. * Can be learned from the code: Function A accepts a C-style pointer to a data array. * Can be inferred from the code: Function A is called in an inner loop, and so it probably accepts that data array to avoid doing any memory allocation. * Cannot be known from the code: Even though the data array is initialized to 0 in the current code, function A should not assume that will always be the case. That data array is intended to be used as persistent storage in a future version. The first one is kind of pointless to document beyond what doxygen already gives you. The second is useful, but not necessary. The third is absolutely essential, because nothing in the current code can possibly tell you about the future intents for changes in the code.
- TeMPOraL 6y ago
  * Cannot be known from the code: The intent to use the array as persistent storage in the future is driven by the ongoing work around feature F. * Cannot be known from the code: Feature F morphed into feature Q, and the function A doesn't really need that array anymore. Since nobody could tell why it was there in the first place, nobody removed it afterwards. The next time someone has to make changes to function A, they'll be thankful for a comment or commit message that explains the first point above - as it'll let them complete the picture and realize it's no longer needed, so they don't have to worry whether their change is impacting anything else in the program through (mis)use of that array, but they can instead just go ahead and delete it.

FooBarWidget 6y ago

> you just have to approach them with an appropriate level of skepticism and archaeologist mindset The problem is most people don't have this mindset. They expect documentation to be right, and when it isn't, they become frustrated and learn to avoid documentation.

MereInterest 6y ago

I think the big difference is what type of information you're looking for. The code is the final arbiter on what the program does, but gives incredibly little information about why it is designed that way. * Can be learned from the code: Function A accepts a C-style pointer to a data array. * Can be inferred from the code: Function A is called in an inner loop, and so it probably accepts that data array to avoid doing any memory allocation. * Cannot be known from the code: Even though the data array is initialized to 0 in the current code, function A should not assume that will always be the case. That data array is intended to be used as persistent storage in a future version. The first one is kind of pointless to document beyond what doxygen already gives you. The second is useful, but not necessary. The third is absolutely essential, because nothing in the current code can possibly tell you about the future intents for changes in the code.

TeMPOraL 6y ago
* Cannot be known from the code: The intent to use the array as persistent storage in the future is driven by the ongoing work around feature F. * Cannot be known from the code: Feature F morphed into feature Q, and the function A doesn't really need that array anymore. Since nobody could tell why it was there in the first place, nobody removed it afterwards. The next time someone has to make changes to function A, they'll be thankful for a comment or commit message that explains the first point above - as it'll let them complete the picture and realize it's no longer needed, so they don't have to worry whether their change is impacting anything else in the program through (mis)use of that array, but they can instead just go ahead and delete it.