What is the best way to document my code?

This is a discussion on What is the best way to document my code? within the General Discussions forums, part of the Community Boards category; I thought I was doing a nice job, using comments and occasionally doxygen. But a recent 'close to blunder' situation ...

  1. #1
    Registered User manasij7479's Avatar
    Join Date
    Feb 2011
    Location
    Kolkata@India
    Posts
    2,498

    What is the best way to document my code?

    I thought I was doing a nice job, using comments and occasionally doxygen.
    But a recent 'close to blunder' situation is making me rethink my practices.

    I was writing a small interpreter and suddenly realised that I needed to change most of the class and function interfaces to use pointers instead of just copying a value (some unintended object splicing occurred).

    After about 15 mins of trying to change the code to adapt to the changes, I realised that I needed to make the whole thing more loosely coupled into distinct modules (such that, say ..the expression evaluator, does not in any way depend on the inner workings of the lexer).
    That invalidated some of my attempts in documenting what I did earlier.

    Is there a way to make the process of 'updating' the documentation with code easier ?
    Manasij Mukherjee | gcc-4.8.2 @Arch Linux
    Slow and Steady wins the race... if and only if :
    1.None of the other participants are fast and steady.
    2.The fast and unsteady suddenly falls asleep while running !



  2. #2
    and the hat of wrongness Salem's Avatar
    Join Date
    Aug 2001
    Location
    The edge of the known universe
    Posts
    32,592
    Software design - Wikipedia, the free encyclopedia
    Once you're past the stage of a couple of classes, or a couple of thousand lines of code, you need to start actively planning your code at a higher level. You don't have to produce a complete detailed design before you start coding, but you should have enough to give you some kind of road map for the direction you want to go.
    So when it comes to choosing class interfaces, you can at least look ahead to your goal to help you choose something which moves you in the right direction.

    Design (like anything else) is a practiced skill. An informal design can be sketched, evaluated and thrown away in a couple of hours, but it might take you a week or more of code hacking to come to the same conclusion.

    Revision control - Wikipedia, the free encyclopedia
    Comparison of revision control software - Wikipedia, the free encyclopedia
    Get one of these - you'll be thankful the first time a series of edits goes badly wrong, and you just want to get back to something earlier which worked.
    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.
    I support http://www.ukip.org/ as the first necessary step to a free Europe.

  3. #3
    Registered User manasij7479's Avatar
    Join Date
    Feb 2011
    Location
    Kolkata@India
    Posts
    2,498
    I'd start planning more thoroughly from now on.....not just in my mind when bored during public transport.

    Quote Originally Posted by Salem
    Revision control - Wikipedia, the free encyclopedia
    Comparison of revision control software - Wikipedia, the free encyclopedia
    Get one of these - you'll be thankful the first time a series of edits goes badly wrong, and you just want to get back to something earlier which worked.
    I'm really happy that I use svn now, straight from the terminal though (learnt from the svn-book). Thus I could restore the revision just before it went haywire.
    Last edited by manasij7479; 08-22-2011 at 11:54 AM.
    Manasij Mukherjee | gcc-4.8.2 @Arch Linux
    Slow and Steady wins the race... if and only if :
    1.None of the other participants are fast and steady.
    2.The fast and unsteady suddenly falls asleep while running !



  4. #4

    Join Date
    May 2005
    Posts
    1,041
    You need version control, as mentioned. I've found the Unix text utilities, particularly SED and GREP, instrumental in physically making changes to vast amounts of code (but again, you need to have some sort of version control to do this...I know it takes me 8 trillion mistakes before I finally get it to work).

    If you're running on Windows you can install Cygwin and just select the text utilities from the download (I apologize if you already know about all this, which you probably do).
    I'm not immature, I'm refined in the opposite direction.

  5. #5
    Registered User manasij7479's Avatar
    Join Date
    Feb 2011
    Location
    Kolkata@India
    Posts
    2,498
    Get one of these - you'll be thankful the first time a series of edits goes badly wrong, and you just want to get back to something earlier which worked.
    You need version control, as mentioned.
    I previously set up an svn server repo in my /var/ directory.
    But I just got myself a sourceforge account, their service literally rocks...(so many 'management' tools in the same place.)
    Manasij Mukherjee | gcc-4.8.2 @Arch Linux
    Slow and Steady wins the race... if and only if :
    1.None of the other participants are fast and steady.
    2.The fast and unsteady suddenly falls asleep while running !



Popular pages Recent additions subscribe to a feed

Similar Threads

  1. printing a document
    By tanvi in forum C++ Programming
    Replies: 1
    Last Post: 06-27-2009, 08:40 AM
  2. Wierd txt document
    By Necrofear in forum Tech Board
    Replies: 4
    Last Post: 05-22-2006, 09:24 PM
  3. Replies: 2
    Last Post: 02-14-2006, 10:08 AM
  4. how to XOR a document
    By shivani in forum C Programming
    Replies: 6
    Last Post: 02-03-2003, 04:55 AM
  5. getting the document on one screen
    By swordfish in forum Windows Programming
    Replies: 2
    Last Post: 09-10-2001, 11:50 PM

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