Documenting code

This is a discussion on Documenting code within the C++ Programming forums, part of the General Programming Boards category; I would like to post a couple of projects as open source on google code or sourceforge they are not ...

  1. #1
    Registered User rogster001's Avatar
    Join Date
    Aug 2006
    Location
    Liverpool UK
    Posts
    1,438

    Documenting code

    I would like to post a couple of projects as open source on google code or sourceforge they are not massive but might interest programmers that want to add or expand features i never fully developed, but what is expected by 'document your code'?

  2. #2
    C++ Witch laserlight's Avatar
    Join Date
    Oct 2003
    Location
    Singapore
    Posts
    21,993
    If the projects are libraries, it would be good to use Doxygen-type of comments to document the interface and to provide usage examples of both the simplified and "real world" variety.
    C + C++ Compiler: MinGW port of GCC
    Version Control System: Bazaar

    Look up a C++ Reference and learn How To Ask Questions The Smart Way

  3. #3
    and the hat of sweating
    Join Date
    Aug 2007
    Location
    Toronto, ON
    Posts
    3,545
    It means, if you have a function like this:
    Code:
    bool foo( std::string& str, int num1, float num2 );
    You should document what foo() does, and what str, num1 & num2 are (i.e. what they're used for) as well as what the return value means and any exceptions that the function might throw...
    "I am probably the laziest programmer on the planet, a fact with which anyone who has ever seen my code will agree." - esbo, 11/15/2008

    "the internet is a scary place to be thats why i dont use it much." - billet, 03/17/2010

  4. #4
    Unregistered User Yarin's Avatar
    Join Date
    Jul 2007
    Posts
    1,672
    Simply: Say how your project works, and how to use it
    For example, most libraries are run through an API, so naturally you'd want to document what each functions does (like cpjust shows). But for like a daemon, no functions, you'd want to document all the configuration instead.
    A class that doesn't overload all operators just isn't finished yet. -- SmugCeePlusPlusWeenie
    A year spent in artificial intelligence is enough to make one believe in God. -- Alan J. Perlis

  5. #5
    Super Moderator VirtualAce's Avatar
    Join Date
    Aug 2001
    Posts
    9,596
    Doxygen is nice but I feel it does pollute the code with too many comments - especially in the interfaces where it is most useful. Another way to do it is record a macro in MSVS that opens a wiki page for you and you can document as you go. A guy at my workplace did this and it's actually very nice and easy to use.

Popular pages Recent additions subscribe to a feed

Similar Threads

  1. Enforcing Machine Code Restrictions?
    By SMurf in forum Tech Board
    Replies: 21
    Last Post: 03-30-2009, 07:34 AM
  2. Documenting Source Code
    By jverkoey in forum A Brief History of Cprogramming.com
    Replies: 14
    Last Post: 01-04-2008, 11:18 AM
  3. Obfuscated Code Contest
    By Stack Overflow in forum Contests Board
    Replies: 51
    Last Post: 01-21-2005, 03:17 PM
  4. Interface Question
    By smog890 in forum C Programming
    Replies: 11
    Last Post: 06-03-2002, 05:06 PM
  5. Replies: 0
    Last Post: 02-21-2002, 05:05 PM

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