How to properly document a program

This is a discussion on How to properly document a program within the C Programming forums, part of the General Programming Boards category; Sorry for posting two threads in such a short time. However, I need to know this. After I finish my ...

  1. #1
    Engineer in research :(
    Join Date
    May 2007
    Location
    Calgary
    Posts
    56

    How to properly document a program

    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.
    Firyace
    Undergraduate Research
    Electrical and Biomedical Engineering Department
    University of Calgary

    My Comp:
    |Core 2 Duo 6420 4mb cache| Corsair 2*1Gb memory pc5400|
    |500Gb and 80Gb Sata2| HIS 1950pro Turbo OC 256mb ViVo|
    |X-Cube2 red micro atx case| 3in1 Tiger Game port|
    |ASUS P5B-LD2 Rev2.0-VM| WindowsXP Pro SP2| Fedora 8|
    |Windows XP Pro 64|

    My Store
    Real estate 43

  2. #2
    Its hard... But im here swgh's Avatar
    Join Date
    Apr 2005
    Location
    England
    Posts
    1,475
    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.
    I'm just trying to be a better person - My Name Is Earl

  3. #3
    Registered User
    Join Date
    Sep 2006
    Posts
    8,868
    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.

  4. #4
    Just Lurking Dave_Sinkula's Avatar
    Join Date
    Oct 2002
    Posts
    5,006
    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]
    7. It is easier to write an incorrect program than understand a correct one.
    40. There are two ways to write error-free programs; only the third one works.*

  5. #5
    CSharpener vart's Avatar
    Join Date
    Oct 2006
    Location
    Rishon LeZion, Israel
    Posts
    6,484
    Here is the sample of the comment that is put before each API function in the code we sell
    Code:
    /************************************************************************
     * 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);
    The first 90% of a project takes 90% of the time,
    the last 10% takes the other 90% of the time.

  6. #6
    Engineer in research :(
    Join Date
    May 2007
    Location
    Calgary
    Posts
    56
    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?
    Firyace
    Undergraduate Research
    Electrical and Biomedical Engineering Department
    University of Calgary

    My Comp:
    |Core 2 Duo 6420 4mb cache| Corsair 2*1Gb memory pc5400|
    |500Gb and 80Gb Sata2| HIS 1950pro Turbo OC 256mb ViVo|
    |X-Cube2 red micro atx case| 3in1 Tiger Game port|
    |ASUS P5B-LD2 Rev2.0-VM| WindowsXP Pro SP2| Fedora 8|
    |Windows XP Pro 64|

    My Store
    Real estate 43

  7. #7
    CSharpener vart's Avatar
    Join Date
    Oct 2006
    Location
    Rishon LeZion, Israel
    Posts
    6,484
    Edit: Actually, one more thing, how would you find the limit of malloc?
    Check the return value... always
    The first 90% of a project takes 90% of the time,
    the last 10% takes the other 90% of the time.

Popular pages Recent additions subscribe to a feed

Similar Threads

  1. help sharing a program with friends...
    By fingerlickin in forum C# Programming
    Replies: 1
    Last Post: 11-05-2005, 08:54 AM
  2. Dikumud
    By maxorator in forum C++ Programming
    Replies: 1
    Last Post: 10-01-2005, 06:39 AM
  3. I need some help with my program please.
    By agentxx04 in forum C Programming
    Replies: 9
    Last Post: 09-26-2004, 07:51 AM
  4. Need Delimiter Program helpful hints.
    By Unregistered in forum C Programming
    Replies: 7
    Last Post: 02-16-2002, 05:27 PM
  5. My program, anyhelp
    By @licomb in forum C Programming
    Replies: 14
    Last Post: 08-14-2001, 10:04 PM

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21