Skip to main content
A
Anonymous
June 24, 2007
Answered

How to learn undocumented code?

  • June 24, 2007
  • 4 replies
  • 1047 views
I have been tasked to learn the code of a conference room-scheduling tool.
It uses 20,000 lines ColdFusion, JavaScript, and SQL server 2000. There are no inline comments or any other documentation. The author is not available. Some of the files are dead code. The software is Beta, and I have managed to get some of it running.

This is my first experience learning an undocumented program of this size. I tried to manually trace some code but quickly became lost. I tried reading some files, but can’t figure out what they are supposed to do. Most of the database tables and attribute names make sense, but some are cryptic. I am overwhelmed. How do you do it? What is a good strategy for learning undocumented code?


Thank you for your advice.
    This topic has been closed for replies.
    Correct answer Newsgroup_User
    re: If you get it (the raise), just start digging in.

    Would suggest that this is exactly what poster did do, and how he came to be
    confused and asking for help in here.

    DON'T just start digging in. What you need to do is look at the
    functionality from a high level, write down EVERYTHING the system is doing
    in as much detail as possible. Get a spreadsheet going to help you organise
    all this. You'd almost be reverse engineering the business requirements and
    tech spec.

    Once you have done this, go looking for the code responsible for each bit of
    functionality. You may need to do this in increments, getting deeper and
    deeper each time as you find "new" bits of functionality you hadn't realised
    existed. Spend a lot of time doing this and getting really really familiar
    with the code/system at a higher level but getting lower and lower each
    pass. Along with updating your spreadsheet with line numbers, descriptions
    etc, you should add comments to your version of the app.

    Find some debugging tools and trace tools - anything t all that can help you
    see whats going on.

    Must repeat - DON'T just start digging in. This mentality is likley what led
    to such a poorly docuemnted app - developers not wanting to follow a
    methodology or process and instead they just start "digging in"!!

    I wouldn't be asking for a raise either - you can't expect more money just
    becuase a challenge presents itself. If you are a coder, then its your job
    to do it. However, I would consider asking for more resources if its too
    overwhelming - you are just one person after all.



    "Brian Simmons" <bsimmons@centrasoft.com> wrote in message
    news:f5mov7$j6m$1@forums.macromedia.com...
    > First things first: Ask for a raise. If you don't get it, figuring out
    > the code is easy, let the next guy do it.
    > If you get it (the raise), just start digging in. Start with the
    > Application.cfm, default.cfm, etc... and document and figure out what it's
    > doing. Take it in small chunks, so you don't overwhelm yourself any more
    > so than you need to.
    >
    > Think of it this way: The guy that wrote it, didn't write it in a day or
    > all at once. You won't figure it out in a day or all at once, it'll be
    > slow gradual process.
    >
    > hth,
    > Brian
    >
    >
    > --
    > Brian Simmons
    > bsimmons@centrasoft.com
    > The ultimate ColdFusion MX 7.0 Certification testing tool:
    > Check out CFMX Exam Buster 7.0 at: http://centrasoft.com
    >
    > "wolfv" <webforumsuser@macromedia.com> wrote in message
    > news:f5mlsh$fur$1@forums.macromedia.com...
    >>I have been tasked to learn the code of a conference room-scheduling tool.
    >> It uses 20,000 lines ColdFusion, JavaScript, and SQL server 2000. There
    >> are
    >> no inline comments or any other documentation. The author is not
    >> available.
    >> Some of the files are dead code. The software is Beta, and I have
    >> managed to
    >> get some of it running.
    >>
    >> This is my first experience learning an undocumented program of this
    >> size. I
    >> tried to manually trace some code but quickly became lost. I tried
    >> reading
    >> some files, but can?t figure out what they are supposed to do. Most of
    >> the
    >> database tables and attribute names make sense, but some are cryptic. I
    >> am
    >> overwhelmed. How do you do it? What is a good strategy for learning
    >> undocumented code?
    >>
    >>
    >> Thank you for your advice.
    >>
    >>
    >
    >


    4 replies

    N
    Newsgroup_User
    Inspiring
    June 27, 2007
    re: To imply that there is only one way to approach this is a bit short
    sighted.

    Not sure who/where/when this was implied. I implied there was a wrong way,
    not just one right way.

    re: > ALSO, don't assume that the code you come across is "right" or the
    best way to
    > do things.

    Which is why I suggest reverse engineering the requirements and document any
    associated functionality/code - reverse engineering the code is less useful
    in a lot of respects (one reason being as you suggested, code can actually
    be wrong or not actually active!)

    re: > Grab a large whiteboard or flipchart and FLOWCHART the events in the
    code.

    Suggest computer based and not whiteboard. Also suggest UML sequence diagram
    and/or state diagrams. You may find benefits later with UNL such as tooling
    and generation support if/when applicable.




    "tclaremont" <webforumsuser@macromedia.com> wrote in message
    news:f5r8ds$3ci$1@forums.macromedia.com...
    > To imply that there is only one way to approach this is a bit short
    > sighted.
    >
    > Your skills and analytical ability is going to dictate how to overcome
    > this
    > project.
    >
    > First and foremost, COMMENT the code as you discover what is going on.
    > Prefix
    > the comment with your initials or something like that so you can
    > differentiate
    > between your comments and any other comments in the code. For safety sake,
    > I
    > would suggest doing this on the test server if possible.
    >
    > Grab a large whiteboard or flipchart and FLOWCHART the events in the code.
    > If
    > you learn the basic flowchart symbols it will make life easier for both
    > you and
    > the next person that has to dissect the code.
    >
    > ALSO, don't assume that the code you come across is "right" or the best
    > way to
    > do things. Don't assume that each CFM page in the site is useful or even
    > functional. You will probably come across a lot of pages that were just
    > experiments or old versions or stuff like that.
    >
    > When you are done, you could very easilly have a well documented "owner's
    > manual" for the project that will make it much easier to maintain in the
    > future.
    >


    tclaremont
    tclaremont
    Inspiring
    June 26, 2007
    To imply that there is only one way to approach this is a bit short sighted.

    Your skills and analytical ability is going to dictate how to overcome this project.

    First and foremost, COMMENT the code as you discover what is going on. Prefix the comment with your initials or something like that so you can differentiate between your comments and any other comments in the code. For safety sake, I would suggest doing this on the test server if possible.

    Grab a large whiteboard or flipchart and FLOWCHART the events in the code. If you learn the basic flowchart symbols it will make life easier for both you and the next person that has to dissect the code.

    ALSO, don't assume that the code you come across is "right" or the best way to do things. Don't assume that each CFM page in the site is useful or even functional. You will probably come across a lot of pages that were just experiments or old versions or stuff like that.

    When you are done, you could very easilly have a well documented "owner's manual" for the project that will make it much easier to maintain in the future.
    N
    Newsgroup_UserCorrect answer
    Inspiring
    June 25, 2007
    re: If you get it (the raise), just start digging in.

    Would suggest that this is exactly what poster did do, and how he came to be
    confused and asking for help in here.

    DON'T just start digging in. What you need to do is look at the
    functionality from a high level, write down EVERYTHING the system is doing
    in as much detail as possible. Get a spreadsheet going to help you organise
    all this. You'd almost be reverse engineering the business requirements and
    tech spec.

    Once you have done this, go looking for the code responsible for each bit of
    functionality. You may need to do this in increments, getting deeper and
    deeper each time as you find "new" bits of functionality you hadn't realised
    existed. Spend a lot of time doing this and getting really really familiar
    with the code/system at a higher level but getting lower and lower each
    pass. Along with updating your spreadsheet with line numbers, descriptions
    etc, you should add comments to your version of the app.

    Find some debugging tools and trace tools - anything t all that can help you
    see whats going on.

    Must repeat - DON'T just start digging in. This mentality is likley what led
    to such a poorly docuemnted app - developers not wanting to follow a
    methodology or process and instead they just start "digging in"!!

    I wouldn't be asking for a raise either - you can't expect more money just
    becuase a challenge presents itself. If you are a coder, then its your job
    to do it. However, I would consider asking for more resources if its too
    overwhelming - you are just one person after all.



    "Brian Simmons" <bsimmons@centrasoft.com> wrote in message
    news:f5mov7$j6m$1@forums.macromedia.com...
    > First things first: Ask for a raise. If you don't get it, figuring out
    > the code is easy, let the next guy do it.
    > If you get it (the raise), just start digging in. Start with the
    > Application.cfm, default.cfm, etc... and document and figure out what it's
    > doing. Take it in small chunks, so you don't overwhelm yourself any more
    > so than you need to.
    >
    > Think of it this way: The guy that wrote it, didn't write it in a day or
    > all at once. You won't figure it out in a day or all at once, it'll be
    > slow gradual process.
    >
    > hth,
    > Brian
    >
    >
    > --
    > Brian Simmons
    > bsimmons@centrasoft.com
    > The ultimate ColdFusion MX 7.0 Certification testing tool:
    > Check out CFMX Exam Buster 7.0 at: http://centrasoft.com
    >
    > "wolfv" <webforumsuser@macromedia.com> wrote in message
    > news:f5mlsh$fur$1@forums.macromedia.com...
    >>I have been tasked to learn the code of a conference room-scheduling tool.
    >> It uses 20,000 lines ColdFusion, JavaScript, and SQL server 2000. There
    >> are
    >> no inline comments or any other documentation. The author is not
    >> available.
    >> Some of the files are dead code. The software is Beta, and I have
    >> managed to
    >> get some of it running.
    >>
    >> This is my first experience learning an undocumented program of this
    >> size. I
    >> tried to manually trace some code but quickly became lost. I tried
    >> reading
    >> some files, but can?t figure out what they are supposed to do. Most of
    >> the
    >> database tables and attribute names make sense, but some are cryptic. I
    >> am
    >> overwhelmed. How do you do it? What is a good strategy for learning
    >> undocumented code?
    >>
    >>
    >> Thank you for your advice.
    >>
    >>
    >
    >


    A
    Anonymous
    June 26, 2007
    Thank you Brian, you have given me a methodology I can work with!
    This methodology is consistent with how I develop applications top-down.

    What is a good tool for tracing in ColdFusion and/or javaScript?

    Thank you for your help, you have given me hope.
    N
    Newsgroup_User
    Inspiring
    June 24, 2007
    First things first: Ask for a raise. If you don't get it, figuring out the
    code is easy, let the next guy do it.
    If you get it (the raise), just start digging in. Start with the
    Application.cfm, default.cfm, etc... and document and figure out what it's
    doing. Take it in small chunks, so you don't overwhelm yourself any more so
    than you need to.

    Think of it this way: The guy that wrote it, didn't write it in a day or all
    at once. You won't figure it out in a day or all at once, it'll be slow
    gradual process.

    hth,
    Brian


    --
    Brian Simmons
    bsimmons@centrasoft.com
    The ultimate ColdFusion MX 7.0 Certification testing tool:
    Check out CFMX Exam Buster 7.0 at: http://centrasoft.com

    "wolfv" <webforumsuser@macromedia.com> wrote in message
    news:f5mlsh$fur$1@forums.macromedia.com...
    >I have been tasked to learn the code of a conference room-scheduling tool.
    > It uses 20,000 lines ColdFusion, JavaScript, and SQL server 2000. There
    > are
    > no inline comments or any other documentation. The author is not
    > available.
    > Some of the files are dead code. The software is Beta, and I have managed
    > to
    > get some of it running.
    >
    > This is my first experience learning an undocumented program of this size.
    > I
    > tried to manually trace some code but quickly became lost. I tried
    > reading
    > some files, but can?t figure out what they are supposed to do. Most of
    > the
    > database tables and attribute names make sense, but some are cryptic. I
    > am
    > overwhelmed. How do you do it? What is a good strategy for learning
    > undocumented code?
    >
    >
    > Thank you for your advice.
    >
    >


    E
    efecto747
    Participating Frequently
    June 24, 2007
    Make sure the people who gave you this task are aware of the challenges you're facing. Its much easier to work on a problem like this when you have full support and understanding from the people you're doing it for.

    Try to break it down into logical segments, take plenty of backups, do the opposite of what the original author did and carefully document your code!! As Brian said, its a slow process - don't try and figure it out in a day.

    cheers.
    Terms & ConditionsAccessibility statement
    Using the community Terms of use Privacy Cookie preferences Do not sell or share my personal information ad choicesAdChoices