Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

I will be leaving my current project in a few days, and as part of securing my knowledge I have been asked to add comments to the code wherever I feel that can add value.

The problem I am running into now is that the comments I want to write are not really suitable as comments, because they do not pertain to a single entity in the code (a few lines, a function, a class or even a file), but they are more about how two or more entities interact with each other or about a feature whose implementation is spread over multiple entities.

So, how do you go about documenting the stuff that does not belong to a single entity but is important to know to understand the bigger picture?

And also: Where do you document it? In the source file or in an external document?

As an example, we have a client-server architecture in C (with the client and server both running on the same embedded device). To avoid flooding the server, the client has a mechanism to throttle the sending of similar requests to the server such that a request can only be sent if the previous one has been answered.

The innards of this mechanism are spread over multiple functions.

Where would you place the documentation of such a feature, especially if the file with the functionality also has some other, unrelated, functions?

Edit: Extended the question a bit.

share|improve this question
    
possible duplicate of What should you leave behind for your successors? –  gnat Feb 11 at 8:48
add comment

5 Answers

You can probably utilise simple UML diagrams to highlight the high-level concepts.

share|improve this answer
    
I was about to answer the same. Thanks for saving my efforts :P. –  Manoj R Dec 14 '10 at 11:09
add comment

Describe the system through tech articles which address certain scenarios, depict problem solving ways and so on.

Install a wiki and put the articles online so that the other team members can edit them later.

share|improve this answer
    
I would think a Wiki to document this higher level stuff would be a good way of representing that. –  glenatron Dec 14 '10 at 11:23
add comment

I've been using TiddlyWiki to gather some ideas that would not necessarily make a coherent text... This gets you a single HTML file that contains a Wiki that anyone can edit.

Compared to a real Wiki, this is much easier to setup, and it can be stored in your source tree so that it 'follows' the branches and the changes between them. On the other hand, it's not something that can be edited by several person simultaneously.

share|improve this answer
add comment

+1 for Wiki.

If it is a message passing system then I suggest generating sequence diagrams to show the interaction between the different components. I have used the following website to generate diagrams from simple text so no need to fiddle with any tools.

http://www.websequencediagrams.com/

One thing we have found useful is to ask the person leaving (you in this case) to come up with a quiz related to your area of expertise and then have a separate session to go over the questions and the answers.

HTH

share|improve this answer
add comment

I suggest to keep the code intact and describe your design in MS Word with referenes to source code and supporting UML diagrams. Don't spend you efforts on wiki - you don't have neither time nor incentive for real cross referenced documentation. The real power of wiki is semantic network built around some topic and writing wiki with one page is poor style.

Any documentation that is written after project is finished tends to be official statement rather than guidence for supporter/maintainer. This is similar to writing unit tests after the module is implemented. Although they are still useful but they are much less detailed then if you write tests first.

Design decisions have to be pronounced before you started implementing something. It may be simple note like "Ok guys, I have an idea, what do you think about it?" or formal proposal with UML diagrams and meetings. Whenever I start new task/component I try to announce what exactly I'm going to do. And the medium that I choose is not really important - it can be email, blog, wiki, JIRA... Of course design will change in later development but these documents will serve as draft for release documentation.

share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.