process of commenting and improving already written program?

Question

Please allow my intro to properly define the scope of my question:

I'm still very new to the programming world. This all started for me when I had an idea for a software program, but no programming experience. I ended up going the outsourcing route to get the program, and after almost a year, we do have it live and functioning.

This specific program is written with php and is 100% web-based. We're using lots of ajax, jQuery, etc.

Now a year into it, I have been learning and learning wherever I can (lots of learning here!!!) I'm mainly focusing on Java now to build up to Objective-C and the iPhone fun (probably like 99% of all other newbie programmers out there).

I'm really learning so much, and one of the biggest things I'm learning about is proper commenting and scalability.

I'm seeing now that this job we just finished is very sorely lacking in both those areas. I am wanting to add and build upon this program, and not only do I not have much experience, but I'm seeing that it's really hard for me to even get an idea about the functions without these comments...

So my question is-what is the best course of action to begin to pick up the pieces on this program? A full re-write is out of the question, and I don't think is needed.

I'm sure this is not the first time some newbie programmer, software developer has been down this path...what do others do here?

Is it common for a programmer to come into a project very far along and then "clean up" the mess in order to make things move forward productively?

If this is the wrong place for this question (and I understand it may well be) can someone point me to where this would be more appropriate?

Thanks! Joel

Answer 1

We call it "refactoring" and it's an important part of programming.

First, you must have a rock-solid set of automated tests. Usually we have unit tests that we run with a unit testing framework.

http://www.testingtv.com/2009/09/24/test-driven-development-with-refactoring/

Then you can make changes and run the tests to confirm that nothing was broken by your changes.

In some cases, you have to "reverse engineer" the tests around the existing programs. This is not very difficult: you have to focus on the interfaces that are "external" or "major" or "significant".

Since you're reverse-engineering, it's hard -- at first -- to determine what should be tested (because it's an important external feature,) and what should not be tested (because it's an implementation detail.)

Answer 2

I don't know about this being the wrong place or not, but I'll answer as I can:

Is it common for a programmer to come into a project very far along and then "clean up" the mess in order to make things move forward productively?

Yes, in my experience this is very common. I have been doing contract work for over 10 years, and I can't count the number of times I've had to come in and clean up something hastily put together to either make it scale or to be able to add functionality onto it. This is especially common when you outsource the programming to another company, the incentive there is to get it working and out of the door as quickly as possible.

So my question is-what is the best course of action to begin to pick up the pieces on this program? A full re-write is out of the question, and I don't think is needed.

I don't know that there is a "good" answer to this question, the only thing I can tell you is to take it one method at a time and document what they do as you figure them out. If you still have access to the people that initially wrote the program you can ask them if they could give you documentation on the system, but if that was not included as part of the original work spec I doubt they are going to have any.

I'm really learning so much, and one of the biggest things I'm learning about is proper commenting and scalability.

As you have found on your own, proper commenting is important, I'm not convinced on the importance of building scalability in from the beginning, going by the YAGNI principle. I think that as any program grows it is going to go through growing pains, whether that is scalability or functionality. Could someone have built twitter from the start with the kind of scalability in mind that it currently needs? Possibly, but there is the very real possibility that it would flop.

Answer 3

Is it common for a programmer to come into a project very far along and then "clean up" the mess in order to make things move forward productively?

It's definitely common for pretty much EVERY programmer :)

Having said that, remember the IIABTFI principle. If It Ain't Broke, Don't Fix It.

Understanding how the program works and what the pieces are is useful.

Trying to improve it without a specific goal and a business purpose in mind is not.

Answer 4

I'm really learning so much, and one of the biggest things I'm learning about is proper commenting and scalability.

First, I'm curious what you've learned about "proper commenting" as this varies drastically. For some, it's documenting every class and function. For others, it may be documenting every line of code or no code at all.

After having gone through some of the different phases above, I'm with Uncle Bob Martin who, in Clean Code, says that you document decisions, not what the code does. The code itself should be readable and not need documentation. By adding comments describing behavior, you've created duplication that will eventually become out of sync. Rather, the code should document itself. Using well-named functions and variables help describe exactly what the other intended. I'd highly recommend Clean Code for a full discussion of these concepts.

As for scalability, it's usually something that you want to build in. Scalability might be a function of good design, or a proper design for the requirements, but poor design will make scalability a nightmare.

I'm seeing now that this job we just finished is very sorely lacking in both those areas. I am wanting to add and build upon this program, and not only do I not have much experience, but I'm seeing that it's really hard for me to even get an idea about the functions without these comments...

I see this as an indicator of one of two things:

1. That the code isn't well written. Yeah, that's highly subjective. -OR-
2. That you don't yet fully understand everything you need to. -OR-
3. A little bit of both.

Writing good, intention-revealing code is hard and takes years of practice.

So my question is-what is the best course of action to begin to pick up the pieces on this program? A full re-write is out of the question, and I don't think is needed.

As other posters have mentioned, Refactoring. Refactoring is the process of changing code to improve readability and usability without changing functionality. Get a good book on refactoring, or start reading everything you can online. It's now a critical skill.

Is it common for a programmer to come into a project very far along and then "clean up" the mess in order to make things move forward productively?

Unfortunately it is. It takes a lot of diligence to avoid falling into this trap. Try to make your code a little bit better every day.

Answer 5

The big question is how well is the program currently running meeting the needs of those that use it? While it may not be the best looking code, it does work which may mean that you end up doing 101 refactoring exercises around it to get enough of the basics down to make other changes.

While you may be able to ask the original writers of the program, this can be a possible sore spot if they think it is awesome and you think it is crap, for example. It is an idea and one that should be carefully analyzed a bit before one goes and ends up burning bridges because they think you can't appreciate their genius in what was done.

Often this aren't done in an optimal way and so as one learns better ways to do things, things are done in better ways. There is a limit to that of course, but I'd start with the idea that you have some refactoring lessons to help get the basics of the app under your belt and then start putting in enhancements and other stuff to see what was really done in the end.