Thread: Documenting code

  1. #1
    Registered User rogster001's Avatar
    Join Date
    Aug 2006
    Liverpool UK

    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
    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.
    Quote Originally Posted by Bjarne Stroustrup (2000-10-14)
    I get maybe two dozen requests for help with some sort of programming or design problem every day. Most have more sense than to send me hundreds of lines of code. If they do, I ask them to find the smallest example that exhibits the problem and send me that. Mostly, they then find the error themselves. "Finding the smallest program that demonstrates the error" is a powerful debugging tool.
    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
    Toronto, ON
    It means, if you have a function like this:
    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
    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.
    “I just want to use my computer in a productive manner, not learn how to use it.” — Elysia
    “A year spent in artificial intelligence is enough to make one believe in God.” — Alan Jay Perlis

  5. #5
    Super Moderator VirtualAce's Avatar
    Join Date
    Aug 2001
    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
    Replies: 14
    Last Post: 01-04-2008, 12:18 PM
  3. Obfuscated Code Contest
    By Stack Overflow in forum Contests Board
    Replies: 51
    Last Post: 01-21-2005, 04: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, 06:05 PM