Hired as a developer to maintain and update current code base, no docs!

Question

This is my first job after graduating:

I was hired with literally one day overlap from the last remaining developer's last day and my first day. I was given a very very quick rundown of basic functions and uses that apparently we as a company need lots of changes to for each client...

Here's my problem: The code has no comments. The code has no developer's documentation of any sort. Where in the world should I start? I was thinking of creating a developer's wiki as I learn this system, but I feel very overwhelmed right now. I'm looking at thousands and thousands of lines of code, and no one to reference for any help. Suggestions from anyone who has been in this situation would be very appreciated!

Answer 1

Careful notes as you go will be helpful, as will using something like Doxygen to get a high level picture of how parts of the system are related. However, that will only get you so far. What's you need most is to know 'why', you can discover 'what' as you go.

For this, you should consider getting in contact with the previous developers, sometimes if you can ask reasonably quick questions you can get someone to help you. You could also propose to your boss that you try to re-hire one of the previous developers on a short term contract strictly for training purposes.

Answer 2

I think your idea of building documentation as you go is a good one, and a wiki may work.

You don't say what language you are dealing with, so this next idea may not work for you, but when faced with a load of Java don't know well, I would laod it up into a UML modelling tool. This allows me to build class diagrams of interesting pieces.

I would also think about adding documentation into the code, at least for key classes (if that's what you have). So in my Java world I would start to add some Java doc.

The general idea being not only to understand what's going on but leave things in a better state for when you move on, or when you have to come back to all this after a break.

Answer 3

If nobody else is familiar with the code at all, then you should baby step your way through the code.

1. Pick a simple looking change from the list.
2. Find the main entry point.
3. Start digging until you find the place where the change is due.
4. Document the code in a wiki and add helpful comments in the code as you dig.
5. Any change you make HAS TO BE REVERSIBLE, so you don't break what's working (don't forget to use version control).
6. Add unit tests to the code while you dig.

Good luck!

There is a book routinely recommended here for this kind of scenario: Working Effectively with Legacy Code

Here's a simpler PDF from the same author.

Answer 4

Indeed - I've experienced similar. Just take things one step at a time don't try and do too much in one go. You will begin to understand the system, it will just take some time. Hopefully your colleagues don't expect that you'll hit the ground running since you took over the system.

Be aware that what you are seeing will be how the system works, not how it is supposed to work. Be mindful of that as users/stakeholders may not understand the difference because they will expect that the system was written to work they way they envisioned already.

I think it is an excellent idea to create a wiki to document your discoveries. Also comment the code.

As for where to start, I'm guessing you've been asked to fix a bug or two or add a new feature. Start there. Take some user scenarios and walk through them in the code.

Answer 5

Keep your head up: this is an excellent opportunity for you to prove your worth to the company while learning how not to code. If the previous programmer was dismissed that quickly, it suggests that your company is aware of how bad he was. Also, any job beats no job.

Answer 6

Take a few days to get to know the code, if you can afford it. Take a copy of the code base that you will absolutely massacre and get it up and running. Now do the following:

Most modern code on webapps (and Desktop apps, too) have almost all code initiated from the user's perspective. So take any user function and find the code that corresponds to it (this may be trivial, which is great). For instance, if the button says "login," change it to say "not login" or whatever. Now you know that you're editing code that is related to the app. Now start going forward in the call stack to get an idea of how the app is structured, what the layers are, etc. When you need to make sure you're right, break something completely or change it a bit to make sure you're in the right place. You can always get a fresh copy or just leave it broken, since it's a copy.

After you've done this with a few pieces of the app you'll get the idea that it's (hopefully) structured the same way throughout all functions. For instance, "add a client" looks like "login" etc. Break stuff and make sure you're right. Then put it back (or not) and keep investigating.

As you investigate, take chronological notes (I call this "rambling"). When you finish enough investigations to feel like you know what the app looks like and how it works (you usually get bored after you've finished less than 5% of it, since you can figure out the rest as you go), takes your "rambles" and convert them into a Wiki (as you said).

When you've finished this initial investigation, you'll be ready to hack into the app and make changes as needed. Not that you'll know the entire thing, but you'll feel comfortable enough to cut in, investigate some more, and make changes.

Note: if the earlier dev didn't have a version control system setup, you must do that and all similar infrastructure tasks. But, do stuff as you have time, and little by little, as always.

Answer 7

No documentation and no code comments... Well, most of the software projects written in the world are like this.

People do not write documentation because they are usually not allotted time for doing this (you are unlikely to do it on your free time without being paid).

Here's how you start:

• You learn each day a small piece of code, one at a time, whatever you need to accomplish daily tasks
• Your best friend is debugger, to try to understand things
• You set logging in various parts of the code to track execution and get an idea what happens where and when
• You need a mentor to transfer the knowledge. If the last guys has just jumped off the wagon, it's bad. Depending on the scope of the project, it may take up to a year and more before you will feel "at home" with the project. Before that happens, many of your tasks will effectively go with unpredictable time to finish.

Wiki idea sounds very good, but don't make it too elaborate, rather short notes for yourself. Just document basic execution paths, architecture ideas, processes, engineering ideas you see, bugs, code examples etc.

Don't be scared. You feel overwhelmed, it is only natural. Relax and simply try your best. But absolutely tell the management that due to the absence of docs and mentorship, they should not count on your being productive first months. To make things clear from the start.

Answer 8

You need to know the software's functional specification ("FS"): to be told what the code does, and/or what it's supposed to be doing.

Even if this FS isn't documented, you can still get it from the program/project/product manager, and/or end-users (it needn't come from a programmer, though a programmer if there were one might give you a more precise description of the FS than a non-developer would, and/or tell you what was actually implemented as opposed to what was desired).

You also need to know:

• How to build the software (makefile, solution, ant script, whatever it is)
• How to deploy it (make it testable)
• How to test it (list of test cases, preferably automated)

Given all this, you can:

• Test it to see whether its functionality matches its functional specification
• Debug its functionality if not
• Do regression testing after any changes you make

Answer 9

A very early stage has to be to make sure your bosses are aware of the situation. If they think you can dive straight in and start adding your own enhancements or bug fixes, that's a big problem. It sounds like you're one graduate developer replacing their only developer, which is rarely fun. But it can be a great opportunity to shine.

Answer 10

1. Search is your best friend. Often there is some distinct phrase which is part of the user interface which will lead you straight to the code you need to fix. You can get in and out without needing to understand everything.

2. Add your own comments. The legacy code won't seem as daunting once you start seeing your own comments all the way through.

3. The users can help you. There might not be any developers left who know the code, but if you can get in contact with a user of the program, they can often give you a complete overview of all the functionality, which will help you understand the code.

Answer 11

Most importantly, remember that no matter how much of a feat this is or how well you manage in spite of these hurdles, your efforts will probably go unnoticed by your non-tech savvy superiors.

Answer 12

Adding to the mountains of great advice, there's another excellent book on this subject (though it's focused primarily on C and Assembler) called Software Exorcism: A Handbook for Debugging and Optimizing Legacy Code.

My techniques -- and I'm in the midst of such a beast right now from one of my clients -- are similar to many other answers you'll see here:

1. Immediate task: Determine which (if any) third party libraries are used in the project. This is critical, because knowing which assemblies (.NET), packages or other libraries in the project are outside your control helps pare down the "working set" of code you have to trudge through. (Note that you still have to find documentation or samples for said 3rd-party libraries.) (Note #2: This was one of the hardest lessons I had to learn.)
2. Does anyone familiar with the project still exist in the firm? Great, they're your new best friends. Schedule as much face time with them as humanly possible. Buy them coffee, donuts and bagels. You want to know what this beast was supposed to do. (You don't care, yet, what it actually does. You will, but right now find out what the business needed this app to do, and then look at all of the code from that perspective.) Take notes. Lots and lots of notes.
3. Start small. Understand a single module or flow. Understand its immediate dependencies. Then start branching out into the dependencies' dependencies and so forth.
4. Don't start changing things yet. Get a halfway decent handle on the structure and standards of the project. And yes, the absence of structure and standards is (unfortunately) itself a standard. My old adage of "sometimes it's better to be consistent than correct" may apply -- but your mileage on that may vary. (As a consultant, I inherit a lot of code -- code which may or may not be permanently maintained by me. I'd usually rather match what's there so the next guy has an easier time.)
5. Begin developing some of your own documentation. It doesn't have to be formal, it can even be "just notes." If you're using Office 2007, OneNote is very handy for this, but a regular word processing document can work just as well. Just capture what you learn about the code.
6. Does the project have unit tests? Of course not -- I've never once inherited a project which did. So, sounds like a good way to get your feet wet with the code, doesn't it? Why would we write these now? Because unit tests are a great way to document what code does, and more importantly, what it's intended to do. You may not know what the intent of the previous developer was, but you know what your intent is. For better or for worse, the code is now yours; make sure you know what it does. You don't need to write tests for the entire app all at once, but make sure you do enough that you're ready for ...
7. Change time! Like others said, start small. And make sure you have unit tests that are already working for everything your change touches. That means all of your changes dependencies, both up- and down-stream. The unit tests not only ensure that the code works, but in this scenario provide some (small) level of regression testing for you.
8. Test your changes, both in and out of the debugger. Make sure your change "seems to work."
9. Now find someone in the business to test it.
10. GOTO 6

Good luck! I'll be honest, the whole forensic analysis bit is probably my favorite part of a new app -- even if the codebases are typically rotten to their cores. It's some of the most challenging work you get to do as a developer.

Answer 13

My advice comes in two folds.

1- revision control. Get it in hg or git yesterday. If it's already in revision control examine the changesets it will help you find the places where the code changes a lot.

2- write all type of tests starting with integration tests. This will give you:

• a great understanding of the code base
• It will tell you if you break something in the future
• It will let you refractor all the horrible code

This is a great talk regarding point two Building tests for large, untested codebases

Answer 14

Something no one (edit: one person!) has suggested yet is making pictures of how the modules, classes, or objects (if any) seem to interact with each other. You didn't say what language this is in, but if it's an OO language, there's some natural structure there. Even if it's not Java, C++, etc., there should be module boundaries, where you can start drawing arrows to "indicate this block of code interacts with this other one quite a bit, and vice-versa (mutual dependency)!", and other similar annotations.

I'd use Visio or OmniGraffle for this, but anything which lets you draw boxes with text and arrows would do. Don't worry about full-blown UML, these are just to go in your developer's wiki and be useful for you.

As someone else said, if the code is in a version control system, great! That's documentation. If it's not, then get it into one, pronto.

Answer 15

Scanned the others answers and people are forgetting the most important thing with legacy code.

See the code running in a LIVE or Test environment (sit next to the users and see how they use it, if a front end application). See what the inputs are and what is generated from the application/code that your looking at (if a back end task see if files/tables are being read and written to by the code).

Once you understand the code as a black box, then it starts to help you break down what is actually happening.

Then I would try to run it in my DEV environment. Then I would step into and debug, debug, debug. This is so important as you see the code flow of the working app, not "static" code. This will remove any complexity and ambiguity on what the code is doing.

Most of the time I tend to take on work by doing the above and get ahead of the game on my contracts. Other developers want the information put into their palms and complain when things are not how they expect in an application.

There are points above about making notes and documenting as you go along. If my team members were doing this I would think they are wasting time. I would tell them to get your head around the code and feel comfortable with it's inner workings, then once your there the documentation will flow out in no time.