1. We have moved from vBulletin to XenForo and you are viewing the site in the middle of the move. Though the functional aspect of everything is working fine, we are still working on other changes including the new design on Xenforo.
    Dismiss Notice

Documentation

Discussion in 'Programming' started by prasenjitghosh09, Jan 19, 2005.

  1. prasenjitghosh09

    prasenjitghosh09 New Member

    Joined:
    Jan 18, 2005
    Messages:
    1
    Likes Received:
    0
    Trophy Points:
    0
    How can I make the documentation Of my coding? I want to mean what is the structure of documentation that are acceptable to client?
     
  2. shabbir

    shabbir Administrator Staff Member

    Joined:
    Jul 12, 2004
    Messages:
    15,276
    Likes Received:
    364
    Trophy Points:
    83
    First of all I would like to welcome you to Experts Advice Forums . I hope you will enjoy the community here and shall get good tips in programming.

    Now about your query
    To be honest there is no standard for documentation about the code but you can follow some guidelines.

    1. All variables should be commented as why they are defined and what is there use.
    2. Each function should be commented as what are the input parameters and why and what is the output and some logic in the lines.
    3. See the Java Doc and see how they generate the Documentation from the codes and comments and that should be more than sufficient.

    Thanks
    Shabbir Bhimani
     
  3. Amit Ray

    Amit Ray New Member

    Joined:
    Jul 12, 2004
    Messages:
    75
    Likes Received:
    4
    Trophy Points:
    0
    Occupation:
    Software Developer
    Home Page:
    Well, it is very encouraging to see a developer showing interest in documentation .. generally developers are of the opinion documentation is a very mechanical and boring task and should be avoided .. what they do not realise is by avoiding proper documentation they are inviting 100 times more frustrating and lengthy maintainence and bug fixing stints.

    Generally it is a good idea to document "why you do something" rather than "what you do" since the latter is pretty apparent form the code itself, mostly. Make your code readable along with documenting it.

    Make sure that if at any point of time another programmer has to make sense of your code without you being around it is a cakewalk for him. Do not document each and every line and the meaning of logical constructs (since overdoing things will make matter worse).

    Follow the golden middle and you will find people fall in love with your code very easily.

    Cheers,
    Amit Ray. :cool:
     

Share This Page