optimize a takeover process ...

[Giovanni Azua]

Hi all,

Have a problem related to taking over a large J2EE project
with +1500 java classes.

Had a ten minutes chat with the developer who is
leaving and the remarks are:

- It works as is.
- Low percent of test coverage of the source code.
- Project not really carefully designed from scratch. I assume
there is lot of "code smell" and also probably lack of e.g. design
patterns.
- It would teoretically take +1 year for a new developer
to feel confortable to modify the code fluently, assuming the
new developer is confortable with all the technologies utilized.

I will in theory work close with the original developer for a month
and bellow is my plan to get the most out of it:

- Get most documentation from the functional concerns
implemented not covered by third parties.

- Ask for all possible documentation, specifically
"meta-documentation", list of all technologies utilized and
where to find documentation i.e. in case of proprietary
frameworks etc.

- Get tools for "automatic documentation":

a) Reverse Engineer to UML.
b) Execution flows (profiler).
c) Profiler that provides automatic source code test
coverage e.g. Parasoft JTest. Then would be possible
to refactor to patterns maintaining functionality "as is".
d) Code Metrics tool to estimate the quality of the
sources.

Anyone recommend a better way?

Thanks in advance,
Giovanni

 

[Roedy Green]

Have a problem related to taking over a large J2EE project
with +1500 java classes.

What you want more than anything else is a one sentence to one
paragraph inserted about what each class is for and anything unusual
you should know about it.

Hire the original guy to do that.

 

[Robert Klemme]

What you want more than anything else is a one sentence to one
paragraph inserted about what each class is for and anything unusual
you should know about it.

Additionally I'd request a one to five page architectural description
(ideally including graphics) so you get an overview how the beast works.
For the details you can always look at the source code.

Good luck!

robert

 

[Roedy Green]

Anyone recommend a better way?

One of my hobbyhorses in that the hardest documentation to recover is
the big picture. For detail tho code will be eloquent.

So just sit the guy down with a few new programmers and turn on a tape
recorder. get him to just TALK baout how it all fits together. Have
people ask questions. This will be much more fun for him, and much
more productive of his time. Your own people can make the notes from
it afterward.

Have him walk through a typical transaction. Have him tell you all the
tools you use and what role they play. Have him tell you anything you
must do periodically just to keep the thing alive.

just get him going. He will naturally tend to tell you the stuff you
need to know.

 

[Roedy Green]

just get him going. He will naturally tend to tell you the stuff you
need to know.

Don't forget to ask the "obvious" questions.

1. what does the project do, what is it for?

2. What does the project NOT do that you might plausibly might expect
it to?

3. what parts work well? Which parts need a rewrite?

4. What are the outstanding major things that have to done in priority
order.

5. who can you ask when you have trouble?

6. When it goes off the rails, what are the most common problems?

 

[Giovanni Azua]

Hi Roedy,

Many many thanks for your very valuable input!

So just sit the guy down with a few new programmers and turn on a tape
recorder. get him to just TALK baout how it all fits together. Have
people ask questions. This will be much more fun for him, and much
more productive of his time. Your own people can make the notes from
it afterward.

This is a great idea, I did not think of it before ... I think is perfectly
feasible.

Many thanks once more!

Best Regards,
Giovanni

 

[Giovanni Azua]

Hi there!

Once more many thanks!

I was surprise that such a common real-life situation like this is not
covered by any Software Engineering process or methodology I did
not even found any articles on this real-life situation and was googling a
lot for it ... probably you Roedy could write one article about it

Best Regards,
Giovanni

 

[Chris Uppal]

I will in theory work close with the original developer for a month
and bellow is my plan to get the most out of it:

Make sure he spends some time describing the things that are (in his opinion)
wrong, or sub-optimal, in the current implementation. Early design errors that
he couldn't fix, improvements that he'd have liked to make if there'd been
time, stuff that works but he'd like to re-write, and so on...

Get him to help /you/ wite the 6-pager architectural overview, draw any
diagrams, etc. He'd more likely to spot ommisions and misunderstandings in
documents that you write, than he is to spot similar problems in what he
writes.

-- chris

 

[Roedy Green]

Get him to help /you/ wite the 6-pager architectural overview, draw any
diagrams, etc. He'd more likely to spot ommisions and misunderstandings in
documents that you write, than he is to spot similar problems in what he
writes.

This is a general principle for eliciting detailed information from
people who are too busy. Just write your best understanding. It will
drive them nuts to read it and not make the corrections.

The Java glossary would never even have started without this approach.

The approach works much more effectively than open ended "tell me what
I should know" questions.

 

[Leon Lambert]

I agree with your opinion. A brief architectural overview should be a
must. It should not go too heavily into detail design but stay higher
level. This should not change too much over time as the detail design
could as the code is enhanced and refactored.

I also agree with Roedy Green in that each class should have some high
level description. This should also stay as high level as it can so it
is isn't extincted with enhancements and refactoring.

I know this will probably cause a flame war but i find UML diagrams to
be a completely useless step and tend to quickly become out of date.
They then add expense if you also have to update them when you update
the code so no one does it.

The first thing I would do is sit down with the developer and create the
architectural overview. I would then try to make some documentation for
each major class. Then time permitting, I would try to get as much as a
comprehensive unit test as possible before he leaves. Even if he does
leave before finished I would continue creating the unit test and force
it to walk through all the code in the debug mode. I find using a unit
test and a debugger the best way to understand code.

Hope this helps.
Leon Lambert