The imp of the perverse (with apologies to E.A.P.)

[Sadhunathan Nadesan]

Dr. Farmer wrote,

| writing a descent technical manual instead. A "best of
| both worlds" compromise, proposed by me in the context
| of FreeGUI's scriptEditor, would be to make the
| comments *collapsable*, e.g. only see them when you
| want to see them + instantaneous switch betwwen the



	Nice idea!

	Yeah, that would do it.  I'd sort of like to right click on
	any line of code and see the basic comments, maybe a choice of
	higher levels of abstraction etc, hyperlinks to other docs, etc.
	And of course good tools to make it easy to create and maintain
	this repository of information.

	Yes, I agree, code cluttered with too many comments looks messy
	and it's hard to find what you are looking for.  One line of
	comments per 10 lines of code may be enough.

	The problem comes in when there are no technical docs or
	no comments, nada.  Even if the code is clean, regular,
	beautiful, self explanatory, etc, it takes  a NEW GUY (not the
	author) too darn long (I am talking about programs in the
	2,000 to 10,000 lines of code range, not your simpler 100-500 line
	program) to figure out what is going on.

	Everything needs to be in the context of scale.  And objectives.

	I am talking about enterprise applications with a million plus
	lines of code like the ones I am responsible for, composed of
	many hundreds of individual programs and interacting systems.
	It is absolutely unthinkable not to have comments plus companion
	technical docs.

	I am talking about the objective of on going maintenance.
	Someone who doesn't know the code having to make changes, and
	you dont have all year to study it.



| but I am not as rare as you might think. There are a
| dozen+ new "agile" software development methodologies
| being taught & used, like "Extreme Programming" for
| ex, which argue against too much documentation and



	Yap.  We've tried it.  Some of it is good, some not so good.
	Actually having someone (old hand) sit there while someone
	else codes (newbie), and they watch over their shoulder?
	REVOLT.  That part of XP I could not agree with.  I could
	strongly agree with other parts, such as, do the simplest
	thing that actually works.  That is a really good rule of
	thumb.

	Rapid prototypeing, rapid interations, create the specs as you
	go so to speak - that works pretty darn well for some things.

	Again, it depends on scale and scope.  For conservative
	organizations that expect the code to last a long time ..
	mmmmm..XP?. maybe not .. but for dot-coms that have to react quick
	and could come and go rapidly, and who cares if no one but
	the authors understand the code  , you sell it off and
	let the buyer beware of the code without the comments.



| 
| In essence, you should be as parsimonious as you can
| be with your comments, relying instead on the dev's
| group abilities, the quality of their communication,


	Nope.  You have to factor in the average career of an IT
	guy is about 2 years in one organization before they move on.
	Managment MUST insulate themselves from this kind of turn over.
	Yeah, it would be fine to rely on this if you could chain them
	down and get lifetime guarantees.  And in fact I have several
	guys with me for more than 15 years.  Pretty darn good.  But if
	they got hit by a truck?  Or head-huntered away?  or pissed
	off and left?  Hey, and I told the board of directors "well,
	i was relying on them being here forever so we didn't need
	commented code" .. ha ha!  that'd be my sweet akole on the line.
	(look it up in a hawaiian dictionary, if you can't guess, 
	but here's a hint .. it rhymes with posterior).

	It's like those cobol guys who said, hey we don't need no
	stinking 4 digit years, let the younger generation deal with
	it.  We'll be long retired.   I have to take the long view.


Again, if you are a one man or small shop, no plans for making an
establishment to last generation after generation, hey, no problem, if
you are in the corproate world of megafinance and gotta be
conservative, its a different story.

Actually in our shop, we have some of each side of the coin, because,
the mind of man is meant to create, and we have to allow that too,
with a certain freedom, and agility, to remain innovative and proactive.


Pierre wrote,

| Perhaps is it ways to code abstactions in C, Lisp or Smalltalk. Probably
| is it many more natural to do this in using an XTalk. It's just the
| reason i use, instead of any other tool each time it's possible, an
| XTalks to build my apps.
| 


Pierre, you can do it in 3rd gl languages too (not that I am a big fan
of C you understand, it is too easy to make it like the rosetta
stone), you just code top down.  In other words, you call your "ideas"
as long function names like


	main (some args here) {

	  first_ill_do_this(with some stuff);
	  then_ill_do_that(with some other stuff);
	  then_ill_do_the_hootchy_kootchy (stuff);
	  and_ill_shake_it_all_about (stuff);
	  then_ill_be_done_(stuff goes in and stuff comes out);


	}


then you break down the functions to smaller and smaller parts such as
sub functions and finally you are down to coding.

The main difference IMHO is that with a good 4GL  you don't have to
build all these routines from scratch because it comes with a complete
set, and consequently, programs are about ten times shorter and can be
coded about 10 times quicker.  Or at least, the type of programs we
are doing at my work.

And then it is *ALMOST* grin .... dare it say it ... ???

SELF DOCUMENTING~~!!!

eek.   see footnote

Cheers,
Sadhu



footnote:

The mark of an advanced intelligence is to be able to  hold two
opposing ideas in the mind at the same time and still be able to
function.