6 ms·
Few random observations from my experience: - The docs and the code should live at different abstraction levels. Docs add most value when they explain things w
by branko_d 7y ago
Few random observations from my experience:
- The docs and the code should live at different abstraction levels. Docs add most value when they explain things which are not readily expressible in code.
- Docs are often written first, as a mental tool to fully understand the problem. In this context, if the docs and code differ, the bug is usually in the code.
- In rare, but highly valuable cases, docs can be non-textual. Database models (ER diagrams) are a prime example.
- With right tooling, docs become part of IDE experience. A popup shows not just the signature of the method under the cursor, but its doc comments as well. This means less jumping around and better "flow" when trying to comprehend somebody else's (or your own!) code.
- blackflame7000 7y agoI agree that docs and code comments should complement each other. As a visual learner, I find diagrams showing how classes/objects fit together to be much more helpful than reading the documentation. A picture can replace a thousand words and tools like Vizio/Yed are really helpful in my opinion while at the same time minimizing the amount of documentation.
- HighPlainsDrftr 7y agoI'm sort of the opposite. Diagrams just show an abstract to me. At a high level they are great, but I always find myself trying to dust off the diagram and figure out what really is happening underneath. Its always so damn complex!