Documentation Help!

This is a discussion on Documentation Help! within the C Programming forums, part of the General Programming Boards category; I am first time doing Big C project from the Class... i wonder what is need to put in documentation ...

  1. #1
    Registered User
    Join Date
    May 2002
    Posts
    3

    Documentation Help!

    I am first time doing Big C project from the Class...
    i wonder what is need to put in documentation part?.
    Anyone can give me an outline please?
    Thanks!!!!


  2. #2
    Unleashed
    Join Date
    Sep 2001
    Posts
    1,765
    > i wonder what is need to put in documentation part?.
    What documentation part?
    What are you trying to document?
    The world is waiting. I must leave you now.

  3. #3
    ....
    Join Date
    Aug 2001
    Location
    Groningen (NL)
    Posts
    2,386
    You can put whatever you want in the documentation. But note that adding too much documentation is wrong. Avoid describing lines, so don't do things like this

    Code:
    /* Add A and B and put it in C */
    C = A + B;
    But you can describe a block of code, like

    Code:
    /* Sort the array */
    
    eerste = len;
    for (i = 0; i < len; i++) 
    {
        maxindex = ZoekMax (lijst, 0, eerste-1);
        if (maxindex != (eerste - 1)) 
            Swap (lijst, maxindex, eerste - 1);
        eerste--;
    }
    Also useful are headers, like file-headers and function headers.

    Code:
    /* Project : <Project name>
       File    : <File name>
       Author  : <Programmer who created the file>
       Date    : <Date of creation>
    
       File description
       ----------------
       <Describe shortly the functionality implemented in this file>
    
       File History
       ------------   
       Date         Author        Description
       01-01-2002   Shiro         Initial version
    */
    Code:
    /* Function  : <Describe shortly the purpose of the function>
       Param In  : <Describe input parameters>
       Param Out : <Describe output parameters>
       Return Val: <Describe the return value>
    */
    
    Example:
    
    /* Function  : Add values A and B, put result in C.
       Param In  : A, B
       Param Out : C = A + B
       Return Val: None
    */
    There are many ways of documenting. Note that the style is very personal.

    Besides documentation in the code, you could also write a design document in which you put your designs (pseudo-code, diagrams etc.) and explain design decisions.

  4. #4
    Registered User C_Coder's Avatar
    Join Date
    Oct 2001
    Posts
    523
    Heres what I use:
    Flow chart.
    Structure chart.
    Written description - which should contain an overveiw of the program and its working enviroment and be written in plain english, plus any limitations you have noticed. You could also add suggestons for future improvments( lets your boss know he still needs you).
    Test data - show results from a known range of data, prove your program works.
    All spelling mistakes, syntatical errors and stupid comments are intentional.

  5. #5
    Unleashed
    Join Date
    Sep 2001
    Posts
    1,765
    The need for explaining clearly:
    > i wonder what is need to put in documentation part?.
    If you are refering to COMMENTING your source code, refer to the help above.

    If you are refering to documenting input, or charts from the user, then you'll need to explain what you want and need.
    The world is waiting. I must leave you now.

  6. #6
    Registered User
    Join Date
    May 2002
    Posts
    3
    well....documentation is wat it said on my project. my instructor said...documentation cost 75%...so i have no idea what he ask....
    maybe u could help me out for reading http://cs2.bct-pcc.org/final2.htm

    That's my project and i dont' understand what he want my documentation to be.

    Thanks for the help and i hope u can help me a bit =>

  7. #7
    Unleashed
    Join Date
    Sep 2001
    Posts
    1,765
    Ok, I reviewed the site and it sounds like he is talking about commenting your source code ( professors / teachers saying documenting when the correct term is COMMENT ) anyhow...75% of the grade(?) for commenting code?

    Any help here?
    The world is waiting. I must leave you now.

  8. #8
    End Of Line Hammer's Avatar
    Join Date
    Apr 2002
    Posts
    6,231
    I'd say it's more than that.... never did programming at school, so don't take this as being right, but I'd say

    - Write up what your program is supposed to do (get that from the exam paper)
    - Write up how you program will achieve what is required. Highlight any shortfalls, limitations and problems. Also, highlight what benefits your program will bring that is in addition to the requirements set by the exam paper.
    - Write a flow chart of how all your code hangs together.
    - Write a summary of the source files, including function names and purpose.
    - Highlight areas of the program you have left "open" for future expansion.
    - Detail ways in which the program could be enhanced if given additional time to do the work, and show how this fits in with the previos point.
    - Write a user guide. It might end up looking like a simple program to you, but the user might be a non-technical person, so an idiots guide might be in order.

    - And yeah, comment your source code. Pick a style of commenting, and stick with it throughout all the source. In particular, comment the start of each function, saying what it takes as parameters and what it returns, and what it's purpose is. Don't go over board, just a line or 2 for each point is enough under normal circumstances.

    Have fun!
    When all else fails, read the instructions.
    If you're posting code, use code tags: [code] /* insert code here */ [/code]

  9. #9
    ....
    Join Date
    Aug 2001
    Location
    Groningen (NL)
    Posts
    2,386
    From the site:

    To achieve the full 300 points for documentation, the documentation must be extrememely thorough and detailed.
    After reading the site it reminds me of the assignments I got at university. With documentation the prof means "external documentation", not the documentation within the code, which is also important.

    What profs usually want to have in the external documentation:
    - An overview of all requirements, so a description of WHAT the software should do must be in that documentation.
    - All designs you have made, for example UML diagrams, pseudo-code etc.
    - Explain all design decisions, in other words: tell how you came to that design. Also if some requirements are not implemented, tell why you didn't.
    - Provide test-cases. It must be proven that all requirements are implemented. So setup test-cases which proof that the program meets the requirements.

Popular pages Recent additions subscribe to a feed

Similar Threads

  1. Replies: 5
    Last Post: 06-04-2009, 10:18 AM
  2. C++ Documentation Project (wiki, like php.net)
    By Tempest1 in forum C++ Programming
    Replies: 3
    Last Post: 09-28-2005, 03:11 PM
  3. amd cpuid documentation
    By valis in forum C Programming
    Replies: 1
    Last Post: 08-04-2005, 06:19 PM
  4. How to write source code documentation?
    By loobian in forum C++ Programming
    Replies: 2
    Last Post: 06-07-2005, 12:49 PM
  5. C# Documentation
    By Mephisto_2k in forum C# Programming
    Replies: 1
    Last Post: 05-06-2004, 06:16 PM

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