How to properly document a program

[firyace]

Sorry for posting two threads in such a short time. However, I need to know this.
After I finish my program, I am required to document it so that when I left my job (which is a few months later) people can still be able to fix my code if there is anything wrong or needs to be modified. However, I am not sure how to properly document my code such as format, the kind of description it needs, the type of detail it decribes the code etc.

The only thing that I know about commenting is the syntax /* */, so please help!

Thanks.

[swgh]

Well there are two types of documentation in programming, User documentation and code documentation. As a programmer, you code document your code as you do along. For functions espeicially. You can right a comment at the top of a function explaining what the functions does, and what you "Expect" the function to return to the calling code as the result.

At the top of the program, your name, date and a brief discription of what the program does.
User documentation is self explanitory in the form of a user manual. But having Trouble shooting tips is usually key for anyone using your program.

[Adak]

No expert but this is what I use:

Name of the program, your name, the date, copyright notice..

Purpose:
Briefly state what the program is meant to do/does.

Input:
What the program needs, where it needs to find it (filename, directory, etc.), and in what format.

Output:
What is the output (filename, directory, etc.), and what is it's format.

Limits/Known bugs:
Since you're malloc'ing a lot of memory, what is the upper limit user's can expect expect on the system that is going to be running it?

Infinite is just not an option.

[Dave_Sinkula]

Consider also Doxygen or Javadoc comment styles. They tend to lead you into putting such information in there -- especially if your editor assists you -- and s a bonus there are document generators that then work with this.

[edit]Brian Kernighan's Programming Style Tips

Here is a summary of the very important programming style tips from Brian Kernighan's 1994 guest CS50 lecture.

1. Say what you mean, simply and directly.
2. Use the ``telephone test'' for readability.
3. Write clearly - don't be too clever.
4. Don't use conditional expressions as a substitute for a logical expression.
5. Parenthesize to avoid ambiguity.
6. Each time you make a test, do something.
7. Follow each decision as closely as possible with its associated action.
8. Use the good features of a language; avoid the bad ones.
9. Capture regularity in control flow, irregularity in data.
10. Each module should do one thing well.
11. Make sure comments and code agree.
12. Don't just echo the code with comments - make every comment count.
13. Don't comment bad code - rewrite it.
14. Use symbolic constants for magic numbers.
15. Watch out for side effects and order of evaluation.
16. Macros are not functions.
17. Watch out for off-by-one errors.
18. Test programs at their boundaries.
19. Program defensively.
20. Make sure input cannot violate the limits of the program.
21. Make it right before you make it faster.
22. Keep it right when you make it faster.
23. Don't sacrifice clarity for small gains in ``efficiency.''
24. Don't stop with your first draft.

[From The Elements of Programming Style, Kernighan & Plauger, McGraw-Hill, 1978]

[vart]

Here is the sample of the comment that is put before each API function in the code we sell

/************************************************************************
 * RvRtpAMRUnpack
 * description:
 * This method unserializes the payload header from a data buffer.
 * The mode and option settings should be set before calling this
 * function. Also, the storage arrays for the frame types, frame
 * quality indicators, and (optionally) the CRCs MUST be set before
 * making this call.
 * Receiving an AMR payload is a little more complicated than most. Here are the
 * steps required to properly receive and parse an AMR payload: 
 * bulletlist:
 *    - Using the header sizes, worst case frame header/data size, allocate data buffer and RTP header.
 *    - Receive the RTP packet using RvRtpRead.
 *    - Init RvRtpPayloadAMR object using RvRtpAMRPayloadInit.
 *    - Set the RvRtpPayloadAMR mode and options (BEMode, InterleavedOption, CRCOption).
 *    - Use the RvRtpPayloadAMRCalcArraySizes to detrmine Table and Contents size and the number of frames in the packet.
 *    - Use the RvRtpPayloadAMRSetArrays to set arrays for storing frame types, frame quality indicators, and (optionally) CRCs.
 *    - Use RvRtpAMRUnpack to read the AMR header from the data buffer.
 *    - The Table of Contents data (and optionally, CRCs) will now be stored in the arrays that were set with RvRtpPayloadAMRSetArrays.
 *    - RvRtpParam must be filled after RvRtpRead with the payload type, Marker bit, timestamp.
 *    - Get the CMR.
 *    - Optionally, get the ILL and ILP.
 *    - If using Bandwidth Efficient mode, get the data bit offset.
 *    - If using Bandwidth Efficient mode, shift the frame data to the right by that offset.
 *    - If using Bandwidth Efficient mode, get the high order bits that are part of the first frame data byte .
 *    - Continue normal processing of the frame data.
 * Parameters:
 *     output param - The RvRtpPayloadAMR object.
 *     input  buf   - The data buffer that the header is to be unserialized from.
 *     input  len   - data buf length
 *     input  p     - RvRtp header parameters that were received.
 * returns: Non-negative value on success
 *          Negative value on failure
 ************************************************************************/RVAPI
RvStatus RVCALLCONV RvRtpAMRUnpack(
		IN   void *      buf,
		IN   RvInt32     len,
		IN   RvRtpParam *  p,
		OUT  void *      param);

[firyace]

Nice, thankyou for all of you guys information and help I have to do the documenting today and I will refer to the advice that you guys give me

Edit: Actually, one more thing, how would you find the limit of malloc?

[vart]

Edit: Actually, one more thing, how would you find the limit of malloc?

Check the return value... always