Re: [comphist] Lost arts from the 8 bit days.

[Rob L. <la...@tr...>]

On Friday 04 October 2002 07:32 pm, Alan Chandler wrote:
> On Wednesday 02 October 2002 9:26 pm, Eric S. Raymond wrote:
> > I am *glad* this kind of programming is dying out.  And I say that as
> > somebody who did a lot of it back when it was necessary.  I'll say
> > this once:
> >
> > 	MAINTAINABILITY IS MORE IMPORTANT THAN EFFICIENCY
> >
> > No, that wasn't the case fifteen years ago, or even ten.  Machines were
> > too constrained.  But today, if I were managing a project and caught
> > anybody doing tricks like you describe, I'd chew him out but good.  There
> > is such a thing as being too clever in the wrong direction, and this is
> > it.
>
> I would say that maintainability has always been more important than
> efficiency.  It was certainly in my thinking 30 years ago.  In those days I
> coded in assembler (PDP Macro 11) but we (our project team) spent lots of
> time and effort in

Part of this is just experience.  Until you, personally, have had these kind 
of things come back to haunt you in your own code, you tend to blame it on 
the other guy being an idiot.

With me it took almost ten years to start compulsively documenting, although 
that wasn't constant programming.  (Two or three years were spent on an 
amiga, with no development tools, writing english instead of code.  Hmmm...  
And 82 to 90 is only about 8 years.)  So more like five or six years of 
actual "lone wolf" programming experience.

Maintainability vs efficiency is always a trade-off, and as storage and 
computing cycles have gotten cheaper the balance keeps swinging more and more 
towards maintainability.  Stuff used to be written in machine language.  Then 
in assembly (variable names are a form of documentation).  Then in higher 
level languages.  Functional programming was about maintainability.  Object 
oriented programming is entirely about modularizing the code to make it 
maintainable...

The Y2K thing was just cleaning up and throwing out legacy cruft...  
Portability is another kind of maintainability.

> a) Making the design simple so that the code would not need to be
> convoluted. This design was always documented in a technical spec - which
> would start with an overview and progressively get more detailed until...
> b) Writing detailed design documentation before even coding (we had an a4
> sheet form with details of each major subroutine - what it was for, what
> its input and output parameters were etc)

Bureaucracy.  Flowcharting still sucks.  I tend to change the design two or 
four times in the course of writing ANYTHING.  I usually don't have a full 
understanding of the problem until I've seen why my first pass doesn't work...

Maybe I'm just slow. :)

> c) Writing lots and lots of comments in the code itself.  I remember
> writing a comment at the end of almost every line of assembler AND writing
> a stand alone comment about every 5 or 6 lines.

There's a school of thought that says too MUCH commenting is a bad thing.  
The linux-kernel group goes a bit overboard here, but they do have a point.  
They care deeply about choosing good function names, variable names, 
structure groupings, etc.  And they write up fairly long documentiontion in 
another directory, and are starting to insert auto-extracted docbook   But if 
you merge a chunk of code that's got comments every three lines, Linus will 
chew you out.

The thing is, comments go stale when the code changes.  Sometimes not the 
immediate area of code, either.  And a misleading comment is WORSE than 
useless.  Lots of time has been wasted debugging to comments that don't match 
the code.  The Linux guys generally say if you need much more than a comment 
at the start of the function to tell you what it does, and then a couple of 
quick mentions of particularly tricky bits, you should probably rewrite your 
function to be more obvious.  (Do less per line, etc.)  Dunno how much I 
agree with them, my natural style's a bit more verbose than theirs.  But then 
I use 2 space tabs, and they insist on 8 space tabs... :)

It's another balance thing.  The less active development a section of code is 
likely to see, the more comments it will probably need.

> We did have to do things like pack several flag bits into a word along with
> other data, but we always had a detailed documentation showing the layouts
> with comments as to why they were like they were.  There was one particular
> system I first developed in 1975, and we were still developing in the mid
> 80's.  We had all the internal data structures documented in the "Don't
> Panic Guide".  This was a paper document - of about 50 pages
>
> These projects were often fixed price - delivery of a working system to a
> customer for a fixed amount of money.  Even within the scope of one project
> we felt it was worth the time and effort to do the design and document it,
> conduct design reviews within the projects and do code reviews of peoples
> code after it had been written, but before testing - to check for style and
> comments (to weed out the sorts of bad behaviour described in the previous
> posts).

I went through some code reviews at IBM.  It was a political ordeal, where 
hidebound bureaucrats imposed their One True Coding Style on everybody else.  
 Not to match the code that was there, but to refactor the whole project to 
be the way they wanted it to be before approving single line changes.  It 
wouldn't have been so bad if we hadn't (for political reasons) had to get 
approval from another department for our code changes.  (I believe they 
thought that cross-pollination between departments might make us hate each 
other enough for physical violence to reduce headcount and save them some 
early retirement incentives.  I'm not sure.)

I solved it using standard dealing with bureaucracy techniques: went back to 
my office, worked on other stuff, and let the problem fester until the 
requirement went away or somebody else dealt with it.

Everybody should work for a bureaucracy once.  It's like a trial by fire...

Had a bad mental image of mandatory code reviews ever since.  Having somebody 
else look at your code, spot problems, and give you their opinion is no 
problem.  Having somebody else arbitrarily and capriciously sign off on your 
changes on a line by line basis is just evil.

Rob