The Design of Software (CLOSED)

A public forum for discussing the design of software, from the user interface to the code architecture. Now closed.

The "Design of Software" discussion group has been merged with the main Joel on Software discussion group.

The archives will remain online indefinitely.

Code Documentation

Hi All,
  I have been reading this great forum for sometime and now time has come to post my own question. Well recently i was hired to do programming in .NET. Here they are trying to support old code which was written in ASP and slowly they are planning to convert it to .NET. Now the problem is nobody knows what the ASP code is doing and there is no documentation done and the guys who did it are not here anymore. So i had two choices either rewrite the code that is already working fine and the way they want it to work again or document the pieces of code i will be touching.
I have gone with documenting the code which is badly needed by everybody here and will make the development more easier.
I never done documentation on someone elses code but because this will be great help to everyone i went for it. I am not sure if this was the right choice? And i will miss writing code for sometime. Comments, adivce appreciated.
moons Send private email
Thursday, September 15, 2005
 
 
> Now the problem is nobody knows what the ASP code is doing and there is no documentation done and the guys who did it

Haven't you heard, the code is the design! What more could you need?

Personally I would start identifying sections I could move and start recoding them. Documenting crap you no little about  is kind of waste, if you are actually using it. If it's in stuff that can sit and rot for years then leave it alone.
son of parnas
Thursday, September 15, 2005
 
 
Yes, i could have recoded sections but here they want to keep it as it is in ASP and let it run but there are requirements to enhance the code using ASP instead of .NET, but because there is no documentation, to build new code on old as of now and in future will be difficult if not impossible... Then again redoing what is already working in same technology didnt make sense so the reason to document. Let me know if this seems like right...
moons Send private email
Thursday, September 15, 2005
 
 
If understanding the existing code is crucial to knowing what to do for the new code, then documenting it makes sense. To throw it away and rewrite it from scratch without a clear idea of what the old code did is very scary.

I have seen new products created with no clear requirements except to do whatever the old system did but on a different hardware/software platform entirely. In this case, there had to be an effort up front to learn what the old system did so we could duplicate it.

So I might have done the same thing, to start by documenting what's there.

But I would not feel hesitant about refactoring or rewriting pieces of code that were especially bad, once I understood what they did.
Briguy
Thursday, September 15, 2005
 
 
> ... but because
> there is no documentation, to build new code on old as of
> now and in future will be difficult if not impossible ...

It's not impossible... I've been there, and the code that I had to maintain was written in Perl... It just takes _a lot_ of time patience... Like what Joel said: It's harder to read code than to write it (http://www.joelonsoftware.com/articles/fog0000000069.html)...

Firstly I just tried to do small improvements here and there, then start doing bigger ones... And when I am confident that I know the ins and outs and the business implications of my  changes, I started rewriting, refactoring, and adding features...

Just my 2 cents...

Cheers,
badaiaqrandista Send private email
Thursday, September 15, 2005
 
 
Thanks guys for your comments.. they are helpful.
moons
Friday, September 16, 2005
 
 
I am currently migrating a site from asp to asp.net, while doing enhancements/maintainence on the asp site. It has been written over the last 5ish years and many pages are infested with spaghetti code.

In one sample of 3 pages, there were over 300 different states/transitions that were happening, and there were about 10 that had never worked in the past 5 years. But who got blamed for "breaking" something that never worked? You got it.

So I've found the control paths to be the most problematic to trace and debug. They get drawn out in Visio when possible. Logged in? What class user? What pages are they going from/to? Switching from preview mode to live mode?
Peter
Friday, September 16, 2005
 
 
"the code is the design! What more could you need?"

Have you even read the articles?
Scott
Monday, September 19, 2005
 
 
Do you think it's possible that was tongue-in-cheek Scott?

Monday, September 19, 2005
 
 
@>"the code is the design! What more could you need?"

@>Have you even read the articles?

@>>>Do you think it's possible that was tongue-in-cheek Scott?

Ah, 1 question where can I find the articles?  I'd like to read them
Paul H Send private email
Thursday, September 29, 2005
 
 
If you write documentation that is separate from the code, it will go out of date as you make changes, and if you're disciplined enough to keep it up to date someone else will not be.

I think you should firstly work out what the existing ASP code you want to change does, then document it in the form of test conditions that must pass (with comments as necessary in the test conditions to describe them).  Add these to the existing code. 

Then you can rearrange the ASP code, and keep the test conditions.  If the tests still pass, you will be sure that you haven't broken anything. Someone changing the page in future could see these tests.
Richard Jonas Send private email
Tuesday, October 11, 2005
 
 

This topic is archived. No further replies will be accepted.

Other recent topics Other recent topics
 
Powered by FogBugz