Design Document From Code

Question

I am not much familiar with documenting/System designing stuff.

I have to maintain an application written in C# - working as windows service.
However there is no documentation for this system which makes it really pathetic to find where some problem (conceptually) occurred.

I would like to know the best way to design/document it (using current code) manually or preferably automatically so that I can identify the exact problems.

Like I feel as if sequence diagram won't much help probably.
Also, please guide me if I am taking it on wrong side?

• yannis: manually or preferrably automatically Replacing "or" with "and" answers your question.
• UmerK: but which diagrams describe such systems better???
• Doc Brown: @Umerk: the type of design documents which helps you best is always depending on the application and the inner structure of the code. You need to make use of your brain to get through this, there is no magic "automatic shortcut" to this.
• yannis: I have no idea. As @DocBrown writes, there's no single answer to this. Since you mostly write the docs for you, use the ones that you feel are more helpful - those diagrams you find particularly helpful in other docs, they are probably the ones you'll find most helpful in your own. Going from no documentation to some documentation is extremely important, going from some documentation to better documentation is another, less important step.
• UmerK: @YannisRizos probably you quoted something important. nice comment indeed :)

Answer 1

Do you have appropriate testing (including, but not only, unit tests) for the system? It seems like you don't, in which case I would start by adding enough tests to be sure that the application behaves as expected (since it fails to fulfill the requirements for the moment, if I understand well your question).

Then, documentation's purpose is to introduce the code to the new developer who doesn't know anything about the architecture of the existent codebase. It means that documentation is not really intended to find where a problem occurred.

When the piece of code behaves unexpectedly, you often start reading code, not the actual documentation, which can be obsolete, or just totally wrong or misleading. In practice, when systems I debugged had documentation, it was obsolete or wrong all the time (concerning the debugged point). No exceptions. Either the documentation was written from requirements and the error was introduced in the code, without reflecting the documentation, or the error was the consequence of slight changes at code level, while documentation stayed the same.

---

Following the comments, I see that I slightly misunderstood your question, which is more about "How I understand the existent codebase which has no documentation at all". It depends. In my case for example, generating class diagrams is something precious. This is the first thing I do before starting to work on someone else's code, and sometimes the only thing. But I also know people who don't bother generating those diagrams, because they find it totally unhelpful.

• UmerK: initially, i was supposed to add/change some small tweaks to the existing application. But right now i happen to face the new additions to systems. i made those changes and when i plug in my changes, the system behaves abnormally (which surely occurs if i don't know existing system). I thought there might be some handy way to model it on paper so that i can save my time by not reading the code (or debugging it)
• UmerK: one more thing. i felt that existing system misuses objects by adding irrelevant information to its holders, calling function before then are supposed to be called and like that.
• Arseni Mourzenko: "which surely occurs if i don't know existing system": no, this occurs exactly because the previous developer forgot to add unit tests.
• UmerK: to some extent i agree with your answer because there has never been any unit testing done...every time i want to test, i can only test it with a production run.

Answer 2

For automated documentation there is XML comments for C# (like javadoc). However this only makes the documentation as good as your comments. Also there are debuggers out there that try to visualise stuff, but I haven't found them to be that useful.

As for design document, I think it helps to have use cases or stories on how a user will use a system. This leads very well in BDD (behaviour driven dev), which sounds like it will suit you more than trying to write up some long IEEE standardised spec/test plan.

However it did sound like you might have some fundamental issues. (from the Joel Test:) 1. Do you use source control? 4. Do you have a bug database? 7. Do you have a spec? 10. Do you have testers? A 'no' on any of those questions will make your life difficult.

Answer 3

I find Doxygen very useful for extracting information from raw source code. Methods, arguments, types, variables, dependency trees, call and caller trees... All of that in hypertexted HTML for jumping between code elements.

Moreover, if during your maintenance activities you insert tagged comments, you can get that documentation more and more useful.

Answer 4

Business rules, data model, class diagrams,setup parameters for production/test/development, security details in test/dev/production, source control process (where is the last good version!), method documentation, business classes and issue logs (with resolution) are all good information that would help people manage an application. As you said, a sequence diagram is not enough.