How do you guys document your functions in the source code?

Discussion in 'OT Technology' started by D1G1T4L, May 14, 2005.

  1. D1G1T4L

    D1G1T4L Active Member

    Joined:
    May 4, 2001
    Messages:
    16,489
    Likes Received:
    0
    Location:
    Bay Area
    How do you document each function? Just wondering what do you guys put in the comments for each function etc?
     
  2. D1G1T4L

    D1G1T4L Active Member

    Joined:
    May 4, 2001
    Messages:
    16,489
    Likes Received:
    0
    Location:
    Bay Area
    i dont really understand the point of commenting in - "int numone", "int numtwo" as you can just look at the function itself and see it right away
     
  3. P07r0457

    P07r0457 New Member

    Joined:
    Sep 20, 2004
    Messages:
    28,491
    Likes Received:
    0
    Location:
    Southern Oregon
    ALWAYS comment in your input/output along with their datatypes. If you don't like "int" then use "integer"... Some IDEs take these pre-function comments and create documentation for you... Some even make tooltips with their auto-complete features. Besides all that, it's just good practice!
     
  4. D1G1T4L

    D1G1T4L Active Member

    Joined:
    May 4, 2001
    Messages:
    16,489
    Likes Received:
    0
    Location:
    Bay Area
    thx guys, you rock!
     
  5. D1G1T4L

    D1G1T4L Active Member

    Joined:
    May 4, 2001
    Messages:
    16,489
    Likes Received:
    0
    Location:
    Bay Area
    how do you document

    void function?

    out - void?


    what bout class constructors

    Class();
     
  6. P07r0457

    P07r0457 New Member

    Joined:
    Sep 20, 2004
    Messages:
    28,491
    Likes Received:
    0
    Location:
    Southern Oregon
    for void functions, I say out -- none. For classes, I have several lines detailing what the class is. It's also a good place for a todo list, or notes.
     
  7. monolith

    monolith My soul grows ever weary and the end is ever near. OT Supporter

    Joined:
    May 9, 2004
    Messages:
    32,613
    Likes Received:
    261
    Location:
    Southern California
    .
     
  8. kingtoad

    kingtoad OT Supporter

    Joined:
    Sep 2, 2003
    Messages:
    55,924
    Likes Received:
    11
    Location:
    Los Angeles
    I comment its input, describe it's functionality, and write a usage example of the function.
     
  9. Penguin Man

    Penguin Man Protect Your Digital Liberties

    Joined:
    Apr 27, 2002
    Messages:
    21,696
    Likes Received:
    0
    Location:
    Edmonton, AB
    We were taught to write pre and post conditions, so a comment would look something like this:

    Code:
    // pre: all squares have temperatures                                   
    // post: temperature has reached equilibrium accross the plate          
    public void equalize() {
    Similar to the in/out style.
     
  10. CyberBullets

    CyberBullets I reach to the sky, and call out your name. If I c

    Joined:
    Nov 13, 2001
    Messages:
    11,865
    Likes Received:
    0
    Location:
    BC, Canada/Stockholm, Sweden
    ive been taught to use pre/post conditions

    pre-condition: input float must be > 0
    post-condition: returns the sqrt of a number, to x specified sig figs
     
  11. Peyomp

    Peyomp New Member

    Joined:
    Jan 11, 2002
    Messages:
    14,017
    Likes Received:
    0
    I don't just document f(x)'s, classes, interfaces, etc. I comment on each internal control block too... like...

    // Iterate through the list of asshats, and kill the asshat named Charlie when you get to him
    for (i=0 ; i < max_asshats ; i++) {
    if(asshats == "Charlie") { kill(asshats); } // Its him, KILL HIM!
    }
     
  12. D1G1T4L

    D1G1T4L Active Member

    Joined:
    May 4, 2001
    Messages:
    16,489
    Likes Received:
    0
    Location:
    Bay Area


    :rofl:
     
  13. Peyomp

    Peyomp New Member

    Joined:
    Jan 11, 2002
    Messages:
    14,017
    Likes Received:
    0
    I'm serious. More comments than just the inputs and outputs of interfaces are required.
     
  14. CyberBullets

    CyberBullets I reach to the sky, and call out your name. If I c

    Joined:
    Nov 13, 2001
    Messages:
    11,865
    Likes Received:
    0
    Location:
    BC, Canada/Stockholm, Sweden
    unless it is complex code, i usually wont comment inside the function
     
  15. Penguin Man

    Penguin Man Protect Your Digital Liberties

    Joined:
    Apr 27, 2002
    Messages:
    21,696
    Likes Received:
    0
    Location:
    Edmonton, AB
    Oh, of course. I know from experience that overcommenting is way way better than undercommenting. Try figuring out what an Access/VBA application does when it's completely uncommented and was written by a guy who doesn't speak English. You'll really appreciate good commenting after that.
     

Share This Page