Slashdot Mirror

The source code is the blueprint/architectural plan/schematic.

The incoherent ramblings of marketing/sales/etc and the software specifications are the equivalent of the initial meeting with the architect saying we want 20 stories and a south-facing balcony on each external wall.

Three Essays by Jack W Reeves.
The Source Code Is The Design.

When reading the question I immediately remembered an article that was once linked from Slashdot. Read it and follow its advice.

http://www.developerdotstar.com/mag/articles/weinb erg_healthybody.html

It's probably worth mentioning a 'seminal' essay written by Jack W. Reeves that suggests that software development is fundamentally different to other engineering disciplines, because the construction phase costs essentially nothing. (He considers coding to be part of the design.) Well worth a read (although it's no excuse for the complete absense of documentation).

Regarding the above analogy, the engineer jumping on the lathe is analagous to the software developer hitting the compile button. And so the analogy breaks down.

Code as Design: Three Essays by Jack W. Reeves.

Actually you can take that view if you accept Jack Reeve's view that the source code is the detailed design and the "lesser-skiller laborer" is the compiler.

Basically as long as management requires short deadlines in lieu of quality, they'll get what they ask for.

Quote: These are business plans, schematics, insider corporate strategy NOT speech - these items are CAD drawings, supplier contracts ... NOT speech .... so no speech was abridged ... and besides Congress didn't make a law. A judge ruled and enforced the law.

Crap. I don't know about other engineers, but, as a programmer, my work is definitely speech.

"Insider corporate strategy" is not in the public's interest. That's what leads to the exploding Pinto cover up, cigarette manufactures researching and suppressing information while doing on-going marketing to kids. Even a flopped product, like Apple's trade secret upcoming "iCrap", is harmful to the public because it causes higher prices and wasted resources. Sunshine won't necessarily prevent a company from releasing a bad product, and occasionally Trade Secrets might even be beneficial to a particular person or company with no little or no ill effect on society, however, in many cases trade secrets cause harm. More harm, in my opinion, than the perceived benefits from companies execs (there's more than one way to market a product other than "Surprise!") or bad (evil) schemes where trade secrets are essential.

source code is not an architecture. it's a design .
what i saw in the first link was 2 pages of folders where the code for mozilla1.7 is burried.
what is the api between ui and gecko? what is the datastructure and related code for tabbed browsing? how do i add a new html tag to be recognized? etc.. the answer to those questions should not be 'RTF code'. I don't want to browse through KLOC to find the answer.

I've read the linux kernel code commentary (black book) where they describe VM subsystem, IO subsystem, kernel module interface, thread control architecture (with spin locks and all) - THAT was helpful when i started reading the code. the other way around is not helpful (timewise) - reading the code to get the mental picture.
Yes documentation becomes outdated, but having something cuts learning curve way down, and making patches to documentation is easier than writing it from scratch.