News for hackers. Stuff that matters.
Re:A new way to think about programs by tzs on Monday November 08, 2010 @05:29PM (#1884304)
We did something similar we did when the company I work for specialized in consulting, back in the late '80s. At the end of a project, one of our deliverables was usually something we called "left hand pages".

It consisted of a binder with a complete listing of the source code we produced for the client, with the source code printed on the right hand pages. On the left hand pages was a detailed commentary and explanation of the corresponding right hand code. Extra space would be inserted in the right as necessary to make room for the left hand commentary. We would not skimp on the left.

The commentary was aimed at being all a new programmer at the client would need to take over maintenance and enhancement of the software. It was assumed he knew the language, and had a copy of and understood the hardware specs. Of course, hardware specs often deviate from what the hardware actually does, and we'd cover all those oddities and deviations in the left hand pages.

Re:A new way to think about programs by rbanffy on Tuesday November 09, 2010 @04:46AM (#1885945)
How do you keep both sides in sync? Special comments in the source that get printed as left-hand pages and suppressed from the right-hand ones?
Re:A new way to think about programs by tzs on Tuesday November 09, 2010 @05:59AM (#1886068)
It was pretty low tech. I seem to recall we'd do something like write the left hand pages in a word processor, then we'd use the page preview mode to see how the pagination of that was going to work out. We'd make a copy of the source code in a text editor, and insert blank lines as appropriate to get it to line up reasonably. Then I believe we'd print the left hand pages on the laser printer, turn the sheets over, and print the source code.