Useful Source Code Documentation
-
I'm leaving my current employer and have been tasked with doing handover documentation for projects I've worked on. I have the /// style comments on my methods and could generate documentation using something like Doxygen. I'm just not sure that the kind of documentation generated by this is any more useful than looking at the code... ? What would actually be useful for someone to be able to get an understanding of the source code? Class diagrams maybe? Edit: These may be useful: [Visualize dependencies with code maps - Visual Studio (Windows) | Microsoft Docs](https://docs.microsoft.com/en-us/visualstudio/modeling/map-dependencies-across-your-solutions?view=vs-2022) [Quick Diagram Tool for C# - Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=FerencVizkeleti.QuickDiagramToolforC)
Documentation of "what" (such as that generated by Doxygen) is happening is not always that useful. I find an explanation of "why" is much more helpful. Unfortunately there is no tool that can do that for you.
- I would love to change the world, but they won’t give me the source code.
-
I'm leaving my current employer and have been tasked with doing handover documentation for projects I've worked on. I have the /// style comments on my methods and could generate documentation using something like Doxygen. I'm just not sure that the kind of documentation generated by this is any more useful than looking at the code... ? What would actually be useful for someone to be able to get an understanding of the source code? Class diagrams maybe? Edit: These may be useful: [Visualize dependencies with code maps - Visual Studio (Windows) | Microsoft Docs](https://docs.microsoft.com/en-us/visualstudio/modeling/map-dependencies-across-your-solutions?view=vs-2022) [Quick Diagram Tool for C# - Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=FerencVizkeleti.QuickDiagramToolforC)
-
I write technical articles on using my code, with code examples. On top of that, I often generate reference docs using a tool like doxygen. I find that creating a technical article not only makes it easier for people to get their feet under them using it (at least I think so), it also helps me later to flesh out an outline of the major components of the software, which then evolves into a table contents. Finally that becomes master documentation. Tools like Doxygen can only supplement. They don't generate useful enough documentation on their own, except maybe if you use all of the tags, like <example> which is at least as much work as doing the above I think. Edit: In practice, at least in my own experience, I find that class diagrams aren't very useful, UML can be especially for large systems, but the way it's used it often isn't.
To err is human. Fortune favors the monsters.
honey the codewitch wrote:
I find that creating a technical article not only makes it easier for people to get their feet under them using it (at least I think so), it also helps me later to flesh out an outline of the major components of the software, which then evolves into a table contents. Finally that becomes master documentation.
I agree 100%. I'm always interested in how to communicate technical details to an audience without confusing or boring them. What makes it better? Mostly, I mean shorter when I say better. After reading numerous brain books I discovered something that is interesting. Almost everything you know & think about has been learned through Context. The easiest example here is you need to remember a list of 15 things. If you simply attempt to remember them you will get 5 +/- 2. However, if you build a story around those 15 things it is quite likely you will remember them. Humans need context. And so it is with documentation (IMO). A lot of documentation is simply a list of technical details. However, if you provide Context -- think of communicating how the thing works as if it is a story to a listener who is somewhat interested. This does generally mean documentation is longer but if you do it right it will be so much better it will seem shorter (in most cases).
-
I'm leaving my current employer and have been tasked with doing handover documentation for projects I've worked on. I have the /// style comments on my methods and could generate documentation using something like Doxygen. I'm just not sure that the kind of documentation generated by this is any more useful than looking at the code... ? What would actually be useful for someone to be able to get an understanding of the source code? Class diagrams maybe? Edit: These may be useful: [Visualize dependencies with code maps - Visual Studio (Windows) | Microsoft Docs](https://docs.microsoft.com/en-us/visualstudio/modeling/map-dependencies-across-your-solutions?view=vs-2022) [Quick Diagram Tool for C# - Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=FerencVizkeleti.QuickDiagramToolforC)
I'm in the situation now where I have to take over an array of projects without any help from the original programmer. Here's what I want to know: HOW DO I RUN THIS STUFF LOCALLY!? Any configuration I need to know about? Also, how do I deploy!? Do I have to copy some files, run database scripts, do a VS deploy, run a pipeline? When "the business" talks about an application, what Git repositories do I need? Also, are there any projects that should be changed together, which is not obvious from the code (for example, because they share a database dependency). I'm rarely interested in documentation about the code. I can read the code. I can click a button/call an endpoint and set a breakpoint to follow through the code. The things I want to know are the things I can't know without knowing (this sounds more profound than I had meant it to be :laugh: ).
Best, Sander Azure DevOps Succinctly (free eBook) Azure Serverless Succinctly (free eBook) Migrating Apps to the Cloud with Azure arrgh.js - Bringing LINQ to JavaScript
-
honey the codewitch wrote:
I find that creating a technical article not only makes it easier for people to get their feet under them using it (at least I think so), it also helps me later to flesh out an outline of the major components of the software, which then evolves into a table contents. Finally that becomes master documentation.
I agree 100%. I'm always interested in how to communicate technical details to an audience without confusing or boring them. What makes it better? Mostly, I mean shorter when I say better. After reading numerous brain books I discovered something that is interesting. Almost everything you know & think about has been learned through Context. The easiest example here is you need to remember a list of 15 things. If you simply attempt to remember them you will get 5 +/- 2. However, if you build a story around those 15 things it is quite likely you will remember them. Humans need context. And so it is with documentation (IMO). A lot of documentation is simply a list of technical details. However, if you provide Context -- think of communicating how the thing works as if it is a story to a listener who is somewhat interested. This does generally mean documentation is longer but if you do it right it will be so much better it will seem shorter (in most cases).
-
Best documentation I see explains "Why?" Ask why the code exists, and sometimes for why the design was used vs other alternatives. The level of explanation depends on the complexity of the project.
The why often depends on how something fits into the bigger picture. The rationale can be anything from architectural to it had to be done this way to mesh with some PoS that we didn't have the time to rewrite. These things would usually be described in a the HLD, but the discipline to make those living documents is rare.
Robust Services Core | Software Techniques for Lemmings | Articles
The fox knows many things, but the hedgehog knows one big thing. -
I'm in the situation now where I have to take over an array of projects without any help from the original programmer. Here's what I want to know: HOW DO I RUN THIS STUFF LOCALLY!? Any configuration I need to know about? Also, how do I deploy!? Do I have to copy some files, run database scripts, do a VS deploy, run a pipeline? When "the business" talks about an application, what Git repositories do I need? Also, are there any projects that should be changed together, which is not obvious from the code (for example, because they share a database dependency). I'm rarely interested in documentation about the code. I can read the code. I can click a button/call an endpoint and set a breakpoint to follow through the code. The things I want to know are the things I can't know without knowing (this sounds more profound than I had meant it to be :laugh: ).
Best, Sander Azure DevOps Succinctly (free eBook) Azure Serverless Succinctly (free eBook) Migrating Apps to the Cloud with Azure arrgh.js - Bringing LINQ to JavaScript
That I have documented for the most part on one of the projects so far :) We're putting some effort into documenting a lot of our processes and info now. Previously it had been in emails, some documents, etc. but now it's getting combined into Confluence. Finally... now that I'm leaving :laugh:
-
I'm leaving my current employer and have been tasked with doing handover documentation for projects I've worked on. I have the /// style comments on my methods and could generate documentation using something like Doxygen. I'm just not sure that the kind of documentation generated by this is any more useful than looking at the code... ? What would actually be useful for someone to be able to get an understanding of the source code? Class diagrams maybe? Edit: These may be useful: [Visualize dependencies with code maps - Visual Studio (Windows) | Microsoft Docs](https://docs.microsoft.com/en-us/visualstudio/modeling/map-dependencies-across-your-solutions?view=vs-2022) [Quick Diagram Tool for C# - Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=FerencVizkeleti.QuickDiagramToolforC)
Pretentious: Good code doesn't need documenting, it is self explanatory. Reality: I am lazy In practice, I try to minimize in-code documentation to reduce clutter and limit it to "magic" code, where I have used an unconventional technique that might confuse a lesser mortal.
Nothing succeeds like a budgie without teeth. To err is human, to arr is pirate.
-
Pretentious: Good code doesn't need documenting, it is self explanatory. Reality: I am lazy In practice, I try to minimize in-code documentation to reduce clutter and limit it to "magic" code, where I have used an unconventional technique that might confuse a lesser mortal.
Nothing succeeds like a budgie without teeth. To err is human, to arr is pirate.
-
I'm leaving my current employer and have been tasked with doing handover documentation for projects I've worked on. I have the /// style comments on my methods and could generate documentation using something like Doxygen. I'm just not sure that the kind of documentation generated by this is any more useful than looking at the code... ? What would actually be useful for someone to be able to get an understanding of the source code? Class diagrams maybe? Edit: These may be useful: [Visualize dependencies with code maps - Visual Studio (Windows) | Microsoft Docs](https://docs.microsoft.com/en-us/visualstudio/modeling/map-dependencies-across-your-solutions?view=vs-2022) [Quick Diagram Tool for C# - Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=FerencVizkeleti.QuickDiagramToolforC)
I think it's more your "experience" knowledge that will be useful for the next person - so I would argue that a document explaining the domain knowledge and why certain APIs and code work they way they do may be of far more use than code documentation. I say this because I spend a lot of time reading code and the most useful information I get from other developers is information like "yeah, this is what can go wrong and this is how the customer uses the API".
“That which can be asserted without evidence, can be dismissed without evidence.”
― Christopher Hitchens
-
I'm leaving my current employer and have been tasked with doing handover documentation for projects I've worked on. I have the /// style comments on my methods and could generate documentation using something like Doxygen. I'm just not sure that the kind of documentation generated by this is any more useful than looking at the code... ? What would actually be useful for someone to be able to get an understanding of the source code? Class diagrams maybe? Edit: These may be useful: [Visualize dependencies with code maps - Visual Studio (Windows) | Microsoft Docs](https://docs.microsoft.com/en-us/visualstudio/modeling/map-dependencies-across-your-solutions?view=vs-2022) [Quick Diagram Tool for C# - Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=FerencVizkeleti.QuickDiagramToolforC)
You asked for advice and are getting a whole range from a diverse set of viewpoints! I will say that some of the most important things to document are: 1) Dependencies/Build/install/setup 2) Validation. How do you test/validate (or who else is responsible). Built in Testing? 3) Deployment Guidelines 4) Risks, Previous issues, and the most problematic code 5) The overall architecture, and a "Metaphor" for how to view the system 6) Any indication of how they might locate something (or the logic of the structure choosen) Look at it this way. Assume YOU were walking in on day 1. The new developer to replace the previous. You have NO CLUE what this system does. How to build it or test it. If you are even using the latest source. Your confidence is in the toilet, and they need you to get up to speed. What type of information would increase your confidence, and get you able to BUILD and VALIDATE the build the quickest? Then what information would allow you to NAVIGATE the code logically? Finally, assuming you only fixed a Typo... On your first day. What would make you feel okay to publish that change??? Document those things. NOT the code, per se. IMHO
-
I'm leaving my current employer and have been tasked with doing handover documentation for projects I've worked on. I have the /// style comments on my methods and could generate documentation using something like Doxygen. I'm just not sure that the kind of documentation generated by this is any more useful than looking at the code... ? What would actually be useful for someone to be able to get an understanding of the source code? Class diagrams maybe? Edit: These may be useful: [Visualize dependencies with code maps - Visual Studio (Windows) | Microsoft Docs](https://docs.microsoft.com/en-us/visualstudio/modeling/map-dependencies-across-your-solutions?view=vs-2022) [Quick Diagram Tool for C# - Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=FerencVizkeleti.QuickDiagramToolforC)
Sometimes the best coding dramas are written in the comments. (aside from some funny jokes) But sometimes a good laugh is the best way to make people remember the oddities of certain hacks or unusual algorithms. If I ever see Windows ME's source code, I'd expect to see shitfaced comments all over the people (evidence of Balmer's Peak)
-
I'm leaving my current employer and have been tasked with doing handover documentation for projects I've worked on. I have the /// style comments on my methods and could generate documentation using something like Doxygen. I'm just not sure that the kind of documentation generated by this is any more useful than looking at the code... ? What would actually be useful for someone to be able to get an understanding of the source code? Class diagrams maybe? Edit: These may be useful: [Visualize dependencies with code maps - Visual Studio (Windows) | Microsoft Docs](https://docs.microsoft.com/en-us/visualstudio/modeling/map-dependencies-across-your-solutions?view=vs-2022) [Quick Diagram Tool for C# - Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=FerencVizkeleti.QuickDiagramToolforC)
