Thread: Documenting Source Code

  1. #1
    Software Developer jverkoey's Avatar
    Join Date
    Feb 2003
    Location
    New York
    Posts
    1,905

    Documenting Source Code

    I'm in the research phase of my work report "An Analysis of Source Code Documentation Tools" and am looking to poll the waters, primarily the waters populated with those who work in proper companies.

    My knowledge of the commercial lineup of source code documentation is directly proportional to the number of Google searches I do on the topic and sadly, this isn't going to cut it for me. My poll to you therefor is a rather open-ended one.

    Which source code documentation software do you use in your workplace?
    If you are using a commercial product, why did you choose such a product over an open-source equivalent?

  2. #2
    and the hat of int overfl Salem's Avatar
    Join Date
    Aug 2001
    Location
    The edge of the known universe
    Posts
    39,660
    Well that depends on what you mean by "documentation".

    For forward documentation, I like using doxygen to extract formatted comments from source code.

    For 'reverse engineering' an understanding of some existing code, I've used
    - source insight http://www.sourceinsight.com/
    - source navigator http://sourcenav.sourceforge.net/
    - lxr http://lxr.linux.no/
    If you dance barefoot on the broken glass of undefined behaviour, you've got to expect the occasional cut.
    If at first you don't succeed, try writing your phone number on the exam paper.

  3. #3
    Software Developer jverkoey's Avatar
    Join Date
    Feb 2003
    Location
    New York
    Posts
    1,905
    I'm researching forms of forward documentation primarily. Reverse-engineering documentation doesn't apply much to the audience I'm writing my report for so I can safely ignore it, but those are interesting packages.

    Doxygen is what I personally use at home and is one of the systems I'm considering in the report.
    Last edited by jverkoey; 12-28-2007 at 02:05 PM. Reason: Ah, and now my brain clicks in after a well-deserved rest. Forward != inline, heh.

  4. #4
    Malum in se abachler's Avatar
    Join Date
    Apr 2007
    Posts
    3,195
    I use MS Word to document the exposed methods of functions/classes, other than that I just use inline comments of the // and /* */ type. If I had to explain what every line of code does, id never get anything done.

  5. #5
    Frequently Quite Prolix dwks's Avatar
    Join Date
    Apr 2005
    Location
    Canada
    Posts
    8,057
    I use Doxygen as well, personally. It's very useful, especially when you enable cross-linked source code.
    dwk

    Seek and ye shall find. quaere et invenies.

    "Simplicity does not precede complexity, but follows it." -- Alan Perlis
    "Testing can only prove the presence of bugs, not their absence." -- Edsger Dijkstra
    "The only real mistake is the one from which we learn nothing." -- John Powell


    Other boards: DaniWeb, TPS
    Unofficial Wiki FAQ: cpwiki.sf.net

    My website: http://dwks.theprogrammingsite.com/
    Projects: codeform, xuni, atlantis, nort, etc.

  6. #6
    Registered User VirtualAce's Avatar
    Join Date
    Aug 2001
    Posts
    9,607
    At work we use Doxygen and I'm a very big fan of it. Produces some very nice docs to go along with your code.

  7. #7
    C++ Developer XSquared's Avatar
    Join Date
    Jun 2002
    Location
    Ontario, Canada
    Posts
    2,718
    Yeah, at work we used Doxygen as well for our customer-facing API docs. And thanks for reminding me to write my work report, Jeff. :P
    Naturally I didn't feel inspired enough to read all the links for you, since I already slaved away for long hours under a blistering sun pressing the search button after typing four whole words! - Quzah

    You. Fetch me my copy of the Wall Street Journal. You two, fight to the death - Stewie

  8. #8
    Software Developer jverkoey's Avatar
    Join Date
    Feb 2003
    Location
    New York
    Posts
    1,905
    Haha, no problem. Just finished mine up last night (a great way to spend the Christmas holidays *pukes*).

  9. #9
    Malum in se abachler's Avatar
    Join Date
    Apr 2007
    Posts
    3,195
    Bleh, I hate writing reports, Daily progress reports, weekly reports, monthly reports, occasionaly technical analysis reports, and now a 'what you expect to accomplish in the next year' report. I suspect that the last one is really an 'explain why we should let you keep workign here' report

  10. #10
    and the hat of int overfl Salem's Avatar
    Join Date
    Aug 2001
    Location
    The edge of the known universe
    Posts
    39,660
    The more interesting one is "tell us why you're leaving report".
    If you dance barefoot on the broken glass of undefined behaviour, you've got to expect the occasional cut.
    If at first you don't succeed, try writing your phone number on the exam paper.

  11. #11
    C++ Developer XSquared's Avatar
    Join Date
    Jun 2002
    Location
    Ontario, Canada
    Posts
    2,718
    Eh, for us it isn't that bad. Just 1500-2000 words analyzing something for the company we did a co-op term at. Luckily for me, my boss already filled out the evaluation form, so now I just need to come up with a report.
    Naturally I didn't feel inspired enough to read all the links for you, since I already slaved away for long hours under a blistering sun pressing the search button after typing four whole words! - Quzah

    You. Fetch me my copy of the Wall Street Journal. You two, fight to the death - Stewie

  12. #12
    Malum in se abachler's Avatar
    Join Date
    Apr 2007
    Posts
    3,195
    Well, my daily report is just maybe half a paragraph paraphrasing what i did that day, basically 2-3 sentences. The weekly report is really just all the daily reports copy and pasted together in one form. The monthly is the big one, usually one page detailing what was accomplished, and what still needs to be done. The assessments are what takes awhile. Anywhere from 2-100 pages depending on the subject, citing suppliers, pricing/availability, alternate techniques, existing systems, technical requirements, etc.

    I work for one of those employers that 'forgets' to do evaluations unless they want to say something bad about you. Real pig **ckers, but until I get off probation, i can't move to another state where there are better jobs.
    Last edited by abachler; 01-04-2008 at 11:16 AM.

  13. #13
    Ethernal Noob
    Join Date
    Nov 2001
    Posts
    1,901
    Quote Originally Posted by Salem View Post
    The more interesting one is "tell us why you're leaving report".
    Would be funny to give them your manifesto instead.

  14. #14
    Malum in se abachler's Avatar
    Join Date
    Apr 2007
    Posts
    3,195
    Thanks for reminding me, I need to start writing a manifesto

    I'm leaving because of this organization can no longer provide sufficient economic oportunities for myself and my team.
    That one will confuse the hell out of them.

    or...
    So I can sell off my stock without being charged with insider trading.
    Last edited by abachler; 01-04-2008 at 04:44 PM.

  15. #15
    Ethernal Noob
    Join Date
    Nov 2001
    Posts
    1,901
    Or you can just say you have an already prosperous side-career as a guild leader.

Popular pages Recent additions subscribe to a feed

Similar Threads

  1. Seven Kingdoms I: Ancient Adversaries for Linux
    By MIH1406 in forum Projects and Job Recruitment
    Replies: 13
    Last Post: 01-17-2010, 05:03 PM
  2. How do you call another source code file?
    By nifear4 in forum C Programming
    Replies: 2
    Last Post: 10-28-2008, 12:16 PM
  3. DxEngine source code
    By Sang-drax in forum Game Programming
    Replies: 5
    Last Post: 06-26-2003, 05:50 PM
  4. Lines from Unix's source code have been copied into the heart of Linux????
    By zahid in forum A Brief History of Cprogramming.com
    Replies: 13
    Last Post: 05-19-2003, 03:50 PM
  5. Source Code Beautifier
    By Hammer in forum A Brief History of Cprogramming.com
    Replies: 2
    Last Post: 05-05-2002, 09:21 PM