Specification and Source Link

Question

I am trying to find some solution that will provide some type of connection between software documentation and source code. I mean, it’s quite difficult to maintain some old software solution that is poorly documented, and it would be great to associate a specific part of the code with its implementation (specific condition, loop, etc.). Does anyone use something like this? thank you

Answer 1

I think this has more to do with discipline than with a process or tool.

Large IT companies have processes and tools that help people achieve this, but you will still find many cases where documents are not synchronized with the source, for example, a design document is created after a requirement and is not updated after testing. The phase is completed. Bug fixes / improvements that occur during code development are not synchronized in documents such as project documents, test scripts, user manuals, etc. Therefore, when the application goes into production, it is mainly code that remains active, and other artifacts passive mode, as a result of which artifacts are not synchronized.

If you look at the full life cycle of the application, the application spends more time at the maintenance / support stage, therefore, it is more to update documents at the support stage.

Most support organizations use some kind of problem tracker or ticket system for requests or a ticket or ticket support system. This tool will help you keep track of application changes that have occurred due to any problem.

I would not mention expensive tools that have the ability to design both ways between the model, document and code, but try to offer an easy way to deal with this with some discipline.

Use a tool that can make your design and other documents alive artifact, for example, use the wiki

. Updating a wiki and linking to another document is much easier in HTML than creating a cross reference document in MS word. For any upgrade / upgrade ticket / feature, update the wiki and link to the source code using any of the following methods.

• Changed source code comment section may include hyperlink to wiki section
• When executing any modified source code in the source code, the repository placed a hyperlink for some reason as a comment.

Answer 2

I think you want to have documentation containing links to the source code (and possibly vice versa), do I understand this correctly?

Following this thought, I would say that there is nothing to do with it. For certain languages, there may be tools for this kind of thing.

For example, Kohana (PHP framework) has created a documentation tool for itself that shows the source code. This uses PHPdoc to mark the source code with special tags for customizing metadata, so Kodoc (the tool) knows what it is.

In MS Visual Studio, you also mark the XML source code, so InteliSense will show a description of the code you are using. You can also use Sandcastle to create the right documentation based on these tags.

It is impossible to find more general agnostic language tools. You can try Doxygen , which was created for C ++, but work with other languages, although I can’t say if it does what you want.

Note: none of these links are source related. And I have never seen such a tool. Kodoc only shows the source code and at the most, what I can think of.

Answer 3

Hi, I understand your problem very deeply, as far as I deal with such problems every day.

I found that for GUI applications, the easiest way for me is:

• web: place a custom help icon on each screen;
• desktop: use the F1 key or any other key combination if your application uses F1;