So, I work as a developer. We are a small team. The majority of the people (everyone except the project manager and the senior developer) are still in university. We have very flexible work hours, sometimes I don't see some of the people for 3-4 days.You can imagine that communication is key here. We write a lot of emails and use a bug tracking system and as long as you are somewhat connected to the task you can be well informed. (as long as you read all the correspondence). One of the weak points of the team is the documentation that people leave behind. The code is reasonably well written and as long as you take the time to read it in it's entirety you will understand it. (problem: this usually takes quite a bit of time when tackling modules of a couple of thousand lines of code) Note: There is very good documentation for the users which is written to the end users, however we are discussing the documentation shared between the programmers.When a new person has to enter some of the things a part of the team is working on, or when someone has to modify old code or someone's old code things get a bit complicated. As I mentioned before sometimes we don't see eachother for days so unless the project manager knows(and remembers) the details of the code the newcommer will have the following options:1 Read the source2 Read the old emails with the discussions. When you have to refactor large pieces of the code This is fine (esp the first thing) however when an algorithm needs to be changed or someone just has to use an old module as part of new module or script or whatever you can imagine that waiting to meet the guy who created the module or reading tons of emails will waste time.I have started adding small documentation in the beginning of each module. It consists of:2-3 sentences about what the module doesA bit of information for each function that is not a part of another function. Basically what it does and some specific information about the arguments it takes if the arguments are objects. If they aren't I just write see the source for more on the argumentsSince I don't know if I am on the right track the question is simple: What should such a minimal documentation contain so it can give a general idea about what the module does and how people can use it?
How viable is to create a mini documentation inside the source code
documentation
This is the set of guidelines I have seen used in multiple teams:Class: Document what the responsibility of the class is (and usually a class must have one responsibility).Method: Document what goes in the method, what method does with it, and what comes out.Inside code: Do not document what a developer can understand by skimming through the code, rather focus on assumptions, or things that are harder to discover, or a brief explanation of a complex piece of code.This also forces a little bit of better design, because if the class has too many responsibilities, then there's a problem. The purpose of the documentation is to find out when the classes and methods are expected to be used without reading the code. If someone has to read the code, then documentation is usually a waste and you are duplicating code in English.We use C# heavily, so C# code documentation tags and auto-generation of the documentation helps significantly. We produce MSDN-style documentation using SandCastle and put it on an internal share so that the developers can look at it. That acts as a forcing function. You may be able to find such a tool for whatever you are working on. And I have also been asked to find out if we can likewise generate documentation extracted from our XSD (which is also documented inline using the xs:annotation tags).Lastly, if possible, especially for classes that are exposed out of the DLL and to be used by other DLLs, I encourage (and personally try to add) example code in the comments. This can be rather onerous, especially keeping the evolution of code in mind, so it is something we wouldn't do if the usage can be found by looking at other code including tests.