Out Of The Mouths Of Clients

[LondonManc]

Sure. But the question is (and I can think of situations where it is worthwhile for large systems) do you want to keep them for posterity (and therefore keep them up-to-date throughout).

Keeping them as living documents provides an easy way of producing support documentation and far more acceptable than "don't worry, I've commented the code".

[VectraMan]

In some cases, however, it may be the case that a high level design document is produced.

The high level design document should be some bullet points of key concepts and requirements. I've seen it where somebody has produced 100 pages of waffle that is essentially useless as it's virtually impossible for anyone to wade through it and extract useful information. This person then gets someone senior to "sign off" on the document after a review meeting, which can't be in any way meaningful because of the shear quantity of waffle it contains, and then refuses to discuss, explain or change any part of the system because "it's in the document that was approved". And therefore you end up with crap.

Still, I've worked many places where nobody has any real idea how the code works as everybody who worked on it has left and nothing was ever documented. But it's still debatable whether paying people to produce documents and keep the documents up to date would have been more cost effective than simply finding a good programmer to figure it out from the code.

[SpontaneousOrder]

Keeping them as living documents provides an easy way of producing support documentation and far more acceptable than "don't worry, I've commented the code".

Oh, of course. I'd view the tests as the living document. Especially if you have a comprehensive BDD style suite of acceptance tests.

I normally would view code comments as a bad sign I tend to remove them whenever I can.

[DimPrawn]

The high level design document should be some bullet points of key concepts and requirements. I've seen it where somebody has produced 100 pages of waffle that is essentially useless as it's virtually impossible for anyone to wade through it and extract useful information. This person then gets someone senior to "sign off" on the document after a review meeting, which can't be in any way meaningful because of the shear quantity of waffle it contains, and then refuses to discuss, explain or change any part of the system because "it's in the document that was approved". And therefore you end up with crap.

Still, I've worked many places where nobody has any real idea how the code works as everybody who worked on it has left and nothing was ever documented. But it's still debatable whether paying people to produce documents and keep the documents up to date would have been more cost effective than simply finding a good programmer to figure it out from the code.

Nice summary of my experience too.

I've also seen the senior person turn round and say "I didn't want this, I only signed off the document because development wouldn't begin if I didn't, and too be honest, I didn't understand the document, it was too long and waffley."

[Cirrus]

Oh Ye of Little Faith

I was cleaning up my old discs etc and found a 171 page project methodology called Evo from Tom Gilb's lad, Kai. If you don't recognise the name Tom Gilb then I've probably lost you already.

In this, he remarks that companies try and pretend they are doing waterfall (SDLC) but as it is totally impractical they actually circumvent the whole process. Doing the design document at the end is a classic ploy.

I have to confess I introduced an agile methodology for one of Europe's biggest insurers (one of my bosses described this as 'more like anarchy') and - oh yes - that had the design being produced alongside the specification alongside the actual code. You may laugh but the CMMI team spent 2 years only to cancel their similar project with nothing to show whereas I launched in 8 months. Occasionally I check the web site and it's still on the front line after 5 years.

[DimPrawn]

I normally would view code comments as a bad sign I tend to remove them whenever I can.

My last client dev team was of this mind. If you write good code, it is obvious what it does. There was not a single code comment anywhere in any code.

Poor sods supporting it down the line stood no chance. Especially as it was produced under extreme agile, with very little documentation outside of sprint planning documents.

[suityou01]

It's better to replace the functional specification with ever increasing set of automated tests. That way as the specification and the software evolves you can clearly see if the software meets the specification.

Nothing worse than 1,000,000 page written spec. Write a 1,000,000 lines of test harnesses.

This is Fragile development.

Agile can and does work well, when coupled with decent dependency injection framework, mocking etc. The problem is that as there is no design per se, from a software architecture point of view what starts out as a good design can rapidly entropy into a ball of mud.

You cannot convince me that an air traffic control system is built using agile methods. Then again, we seldom work on projects large enough to push the boundaries of agile development.

Some of the biggest cluster****s I have ever seen involved agile and offshoring. That is the sweet spot for those "ajax and squeejy mop" clean up contracts.

The industry has a very short memory as managers move on every 18 months, as IT is a stepping stone onto something bigger. It's kind of the easy street to senior management if you can't bring yourself to work in HR or Health and Safety.

I just spend the day designing a class model in Enterprise Architect, across about 5 namespaces. It's for plan B, and I have a scope and mission mapped out in my head, but really no requirements. I think the ability to object model is on the wane, and the industry is turning out scripters that can write unit tests that pass. From that point I agree with you DP.

[LondonManc]

This is Fragile development.

Agile can and does work well, when coupled with decent dependency injection framework, mocking etc. The problem is that as there is no design per se, from a software architecture point of view what starts out as a good design can rapidly entropy into a ball of mud.

You cannot convince me that an air traffic control system is built using agile methods. Then again, we seldom work on projects large enough to push the boundaries of agile development.

Some of the biggest cluster****s I have ever seen involved agile and offshoring. That is the sweet spot for those "ajax and squeejy mop" clean up contracts.

The industry has a very short memory as managers move on every 18 months, as IT is a stepping stone onto something bigger. It's kind of the easy street to senior management if you can't bring yourself to work in HR or Health and Safety.

I just spend the day designing a class model in Enterprise Architect, across about 5 namespaces. It's for plan B, and I have a scope and mission mapped out in my head, but really no requirements. I think the ability to object model is on the wane, and the industry is turning out scripters that can write unit tests that pass. From that point I agree with you DP.

No way did you write that all by yourself.

[d000hg]

No way did you write that all by yourself.

This is what SY does all day - spout this stuff in emails and not only do no work himself, but distract everyone else from theirs.

[suityou01]

No way did you write that all by yourself.

I typed it while waiting for my chicken kievs to cook. I'm glad you're impressed.