7

I have this new customer, that has this PHP App. It was written by a single developer that wanted to "make yet another framework" back in 2005. About 3 Years later the developer left the company, and with him all Knowledge on what this thing is actually doing.

Now, as the App already went in production the manager just hired a few more developers / freelancers (that are not available anymore too) to fix bugs here and there and develop some more functionality. Some tried to follow the undocumented guidelines of the software, some did not.

You might be able to imagine how the code looks today ... its an utter mess!

I talked to the manager and told him what I think of his software and managed to get him to realy think about rewriting the damn thing.

But here comes my problem: To be able to estimate the effort needed to rewrite I would need to know what the thing is doing. The manager can tell me from his perspective what it's doing but there is just no technical knowledge about it. And as with all software that grew over years there are these "special edge cases".

Basically my idea is "record/log" the live system for a few weeks to actually get a technical, somewhat complete conclusion of what this thing is doing most of the time and what are the things that rarely get touched/used. E.g. what was the Request and what route did it go to render the results. Reading and trying to understand the code is impossible. It would help though to see which Classes/Functions are called and then read/understand them.

So, is there any tool to log/record Http Request/Responses and what call graph of the php app it triggered? Preferably something that would not have to get written into the code? I ditched PHP years ago and am somewhat rusty with my PHP Utility and Standard Library Toolset to know of something that could help me here.

yannis
  • 39,547
  • 40
  • 183
  • 216
Manuel Schmidt
  • 163
  • 1
  • 8
  • 3
    Could you not just build a specification from the existing running application then program your new application to that specification? What sort of app is it? – Rig Dec 08 '11 at 15:53
  • 1
    Yes, and we already talked about "high level" requirements. Though I would like to be able to make some assumptions myself, based on my own research of the status quo. IMHO Managers tend to oversimplify complex task and "overcomplexify" simple tasks. Again, i am just searching for a tool (whether available or not) that might be able to do what i want. If there is no such option, too bad. I'll have to go the "classic road" anyhow. The App collects data in xml files and users process that data by "working with it". The reworked data then is offered again to other apps via undocumented APIs. – Manuel Schmidt Dec 08 '11 at 16:06
  • Thank you for your answers. Too bad i can only choose one as "my accpeted answer". – Manuel Schmidt Dec 08 '11 at 16:24
  • 3
    So you are trading the "old" framework with your own framework, only to leave the company in 3 years from now and then... oh i see. – Vinicius Kamakura Dec 08 '11 at 17:54
  • [We've all had to work on bad code](http://stackoverflow.com/a/3009959/238419), and we've all tried rewriting it from scratch. The one bit of wisdom we can impart on you is that [it's almost always more work to rewrite the system from scratch](http://www.joelonsoftware.com/articles/fog0000000069.html). Rather, work with the existing code, and refactor it as you go along. It will eventually become something manageable! – BlueRaja - Danny Pflughoeft Dec 08 '11 at 22:46
  • I have a framework i'd say i mastered. No its not my own and you both would propably agree with me that its one of the better ones out there. I even would go so far and say you know it. Being a freelance developer i love to be able to actually chose what i want to work on. I know others don't have this freedom. – Manuel Schmidt Dec 09 '11 at 00:22

5 Answers5

16

If you want to rewrite the application then you don't need to know how it does what it does but you do need to know what it does.

Sit down with the manager and go through the system highlighting the functionality that the system must have. This will give you a list of functions (eg. assuming that the application is a blogging system):

  • Create user
  • Add blog post
  • Publish blog post at some point in the future.
  • Comment on blog post
  • etc.

Take screenshots of each page so you have a document of what the system looks like. This will also give you the objects and fields that your datamodel must have.

Then you go away and specify how long it will take to implement these functions using your framework of choice.

At no stage do you need to look at the existing code. You are mapping user functionality, not system functionality.

ChrisF
  • 38,878
  • 11
  • 125
  • 168
  • 7
    `you don't need to know how it does what it does but you do need to know what it does` +1 for this comment, because otherwise you are just repeating the mistakes of the past. – maple_shaft Dec 08 '11 at 16:10
  • Unfortunately, this doesn't work in the real world, for exactly the reasons already mentioned by Manuel: *"The manager can tell me from his perspective what it's doing but there is just no technical knowledge about it. And as with all software that grew over years there are these 'special edge cases'."* – BlueRaja - Danny Pflughoeft Dec 08 '11 at 22:30
  • @BlueRaja-DannyPflughoeft - why does the manager have to have technical knowledge? He's just defining the requirements *including edge cases*. – ChrisF Dec 08 '11 at 22:31
  • 1
    Over the years, people will submit requests saying *"When X happens, the software should Y"*. The users aren't going to know/remember all the little things the system does. Nor will they know about all the things the system does silently for them in the background. They're not going to know what other systems this system interacts with, or how it interacts with them. Or how it stores its data (which I assume they'll want to keep). Rewriting a system is not the same as building a new system from scratch, unless you expect to retrain all the users and forget about all previous data. – BlueRaja - Danny Pflughoeft Dec 08 '11 at 22:42
  • If the project owner does not know most (if not all) of these details, he has no business in asking someone to re-write the whole system. – Austyn Mahoney Sep 04 '12 at 21:55
6

You got the year wrong. It was 2001... Wait, you aren't my old coworker. This must happen everywhere.

When I had to choose between rewriting or patching Frankenstein, it was absolutely clear that a rewrite wasn't going to happen. Not all at once, anyway. Instead, we went page by page refactoring top to bottom (this wasn't exactly a model-driven architecture, so thinking of the site as a collection of pages was reasonable). The "framework" in our case started simple. Draw_Info_Box(some_object). But as the special cases arose, this function became Draw_Info_Box(some_object, true, true, true, false, "Non-default header", true)... well, you get the idea. We started by refactoring these to eliminate one additional parameter at a time. For some, we made the decision to duplicate code and eliminate the special case between the two versions (names like "DoSomethingOrSomethingElse" would get split into "DoSomething" and "DoSomethingElse"). For others, we wrapped them in simple objects and turned the additional parameters into object state variables. This allowed for easier refactoring later on.

Breaking it down into manageable units (in our case, individual pages) allowed some parts of the system to be made more manageable while the system was still being used. This also allowed for simpler bug fixes while the refactoring was going on (which was the case against the rewrite -- there were still things that needed to be done to the system being used).

I actually left before the entire system was rewritten. By then, some parts had actually been rewritten more than once (clearing away one level of organizational chaos often revealed another, but we had a methodological approach that allowed us to handle it).

If I were starting a similar thing today, I'd actually start with Selenium tests on the application and try to get some kind of code coverage metrics from the tests. Then I'd do the same refactoring job, but I'd feel a little more confident that mistakes and behavior differences would be caught.

ccoakley
  • 1,126
  • 1
  • 7
  • 6
5

So, is there any tool to log/record Http Request/Responses and what call graph of the php app it triggered? Preferably something that would not have to get written into the code?

The code coverage analysis functionality of xdebug will help you get a sense of what gets executed on each request:

Code coverage tells you which lines of script (or set of scripts) have been executed during a request. With this information you can for example find out how good your unit tests are.

xdebug's profiler outputs profiling information in the form of a Cachegrind compatible file, so in theory you don't have to do a lot in code, as you can configure xdebug via php.ini and htaccess.

This is the practical approach, don't stop here, you should follow the advice given by ChrisF and Morons.

Community
  • 1
yannis
  • 39,547
  • 40
  • 183
  • 216
  • aah great. I chose your answer as my accepted one as i asked for such a tool (and did not know in php land) But, for the Record, the suggestions given by ChrisF and Morons and others are propably even more valuable to deliver something stable. They gave me the certainty to have me and the manager sit down for a few more hours to "talk stuff through". – Manuel Schmidt Dec 08 '11 at 16:59
  • Yeap, I was going to write something similar to the other answers + suggest xdebug, but wasn't fast enough :) xdebug is a little scary at first, I didn't expand on how to get it up and running because that's mostly StackOverflow territory. [Zend Server](http://www.zend.com/products/server/) comes with a nice profiler and a nice gui, but it's not free and it doesn't really add any functionality to xdebug's. Its free version that doesn't include the profiler is a very nice basic php stack if you're looking for one... – yannis Dec 08 '11 at 17:07
4

You basically need to document the systems in terms of Use Cases\User Screens. Be Sure you cover Every screen in the system in at a least of the use cases.

Then you need to go though all the screens and use cases while running an DB profile. Document All the Db transactions on each screen. Test every Field for data validation.

Ask users about System integration, basically anything that may be happening behind the screen that is not reflected in the UI or with a Db interaction. (Sending and Email. FTPing something, whatever)

Ask About anything the runs on a schedule. Look at all the SQL behind the major reports in the System. Make an ERD.

Document, Document, Document.. Then Finally, once you got all the info you can this way. Start looking at the code for areas where you need clarification.

Jim G.
  • 8,006
  • 3
  • 35
  • 66
Morons
  • 14,674
  • 4
  • 37
  • 73
  • +1 for breaking down the major pieces. It should be added too that Use Cases must accompany screens because screens only show you the tip of the iceberg. Management typically over emphasizes the importance of screens, but screens alone will never give you a complete picture. – maple_shaft Dec 08 '11 at 16:13
2

I'd like to build on what ChrisF and Morons have already said.

From ChrisF's answer:

If you want to rewrite the application then you don't need to know how it does what it does but you do need to know what it does.

I agree 100%.

From Morons's answer:

Ask users about System integration, basically anything that may be happening behind the screen that is not reflected in the UI or with a Db interaction. (Sending and Email. FTPing something, whatever)

Ask About anything the runs on a schedule. Look at all the SQL behind the major reports in the System.

Agreed. Great point about the scheduled jobs.

Document, Document, Document.. Then Finally, once you got all the info you can this way. Start looking at the code for areas where you need clarification.

Right.

Test every Field for data validation.

OK.

Then you need to go though all the screens and use cases while running an DB profile. Document All the Db transactions on each screen.

I disagree.

  • Exhaustively profiling the database is not a good use of your time.
  • It could also be misleading.
  • Emphasis: As ChrisF said, focus on what the application does, not how it does it.

Also, know that: You will make mistakes! :)

Of course, as the technical lead, it's your responsibility to minimize these mistakes to the extent that the new system mimics the core functionality of the old system.

Having said that...

  • It seems like this will be a worthwhile effort because you're making the system maintainable and you're erasing a large amount of technical debt.
  • I just don't think it's useful, productive, efficient, or even fiscally responsible to burden yourself with a overly perfectionist attitude on this job.
Community
  • 1
Jim G.
  • 8,006
  • 3
  • 35
  • 66
  • 1
    You are propably right that my efforts would better go into solid concept/design and development of the new app. The switch to the new System _will_ in any case be a painfull one. But i want to know that i took every "reasonable ooportunity" to make it less painfull. But reengineering the app is propably not a "reasonable opportunity" to take. – Manuel Schmidt Dec 08 '11 at 16:47