4 ms·
> if the Markdown file is not near the code in question, it's a 100% guarantee you've wasted time writing it because nobody is going to read it. This ignores h
by MaxBarraclough 7y ago
> if the Markdown file is not near the code in question, it's a 100% guarantee you've wasted time writing it because nobody is going to read it.
This ignores hyperlinks. Why not use in-code comments for explaining nuts-and-bolts matters (for example, to explain strange-looking platform-sensitive code using #ifdef), and use links to wiki pages for descriptions of high-level design decisions?
- dharmab 7y agoThis isn't for comments directly on the source code, it's for higher level stuff like "These are the three services that interact to provide such-and-such functionality. Here's their basic architecture, their dependencies and some basic troubleshooting knowledge/tips."
- MaxBarraclough 7y agoRight, but isn't that what I said?
- m0zg 7y agoI meant that I do documentation on the side, not in code. In code, I do human readable comments (using a restricted subset of markdown) where things would otherwise be very difficult to understand. All of this applies uniformly for the code I write for others, as well as code I write for myself.