Documentation of custom code.

A recent post discussed programmers creating custom code then moving on to another job. In doing so, the custom code became unusable as it was unsupported and unsupportable due to insufficiently documented.

What form of documentation would be sufficient to ensure that my code will be supportable by my successor ?

Thanks
Jeff.

 

IMHO, normal commenting ought to be sufficient ... meaning a header with
description of the program's purpose and any necessary dependencies or
assumptions, and a brief comment on all function definitions, e.g. arguments
and return values. About like what the Acad-supplied lisps include. If the
code is decently written it ought to be self-documenting. Unless you're
building an elaborately complex system that needs explaining from a
big-picture perspective, I don't see a need for documentation outside the
program itself.

You can't guarantee your successor's proficiency, and it's not your job to
teach him or her lisp. If a reasonably adept person could make sense of your
stuff, you've done all you can.

I've left positions where everything I'd written was clearly documented, but
it went out of use after a version or two, because they hadn't seen fit to
hire anyone sufficiently knowledgeable to maintain it. That's their problem,
I think.

 

I like this question Jeff. I find myself writing code for my successor as
much as for the users these days. I hope this brings out a lot of thoughts.
Here's mine.

In a perfect world, the best documented code has no comments. It's self
documenting enough that comments only get in the way. Here is a translation
of some recent code in that other newsgroup over there <pointing over
there - > >

(defun RotateNewlyCreatedEntities()
(CreateEntities)

(if (EntitiesWereCreated)
(progn
(GetRotationBasePoint)
(GetRotationAngle)
(RotateEntites)
)
)
)

Obviously in the real world you can't always write code that is as self
evident as this short example and some comments are going to be necessary.
But I find myself striving more and more to get away from comments. There
are a myriad of ways to do this and just as many resources and opinions as
to which are the best.

Another form of documentation that I'm really just now starting to embrace
is unit testing. I'm interested in hearing others experiences in this area
myself.

Now at the application level, you are going to have to provide some
documentation on the specifications of the application. What is the overall
goal of the app? What is the expected input? What is the expected output?
These and all other expectations must be documented.

Anyway, great question. I hope this brings out the lurking gurus.
--
Bobby C. Jones

another job. In doing so, the custom code became unusable as it was
unsupported and unsupportable due to insufficiently documented.

be supportable by my successor ?

 

Bobby,

Seems like you mentioned the new version of Code Complete a few days ago...

IIRC, what the author recommended (in the first version - don't know about
the latest) was to write pseudo-code to flesh out the program structure -
somewhat vague at first, but after two or three refinements or so, as more
detail is added, it gets to the point where 'it becomes easier to actually
write code than explain what it does'. At which point that's what you do...
;comment the pseudocode, and insert the actual code.

And so the documentation is there effortlessly...

I've been doing this more, (though I probably start in with coding really
before I ought to), and there is no one more surprised as I as to how much
better documented my stuff has become. (So much so as to provoke some
outcries from this group, but, hey, I'd rather things be as clear as
possible, redundantly even, if need be, than scratching my head over some
tricky bit of code wondering what dumb thing it does).

My code ain't gonna win any awards - that I know - but I know its quality
has improved.

Another thing that can be done via TextPad or Interspector text editors is
create self documenting code clip libraries that can give a leg up (speed
and documentation-wise) via function blanks or templates, which I find very
helpful, like these examples:

;
(defun
( ;
/
;
)
; begin
; end
);_end defun

;
(setq
;
);_end setq

; ...
(if ;
; then
; else
);_end if

; ...
(while ;
; begin loop
; end loop
);_end while

Even just a few common ones seem to really improve consistency - one of the
biggest battles I seem to face. Good function and variable names go along
way too.

Best regards,
David Kozina

 

FWIW, I can't stand all of those 'end of' comments.

; end of setq
; end of defun

etc....

IMO, makes the code very difficult to follow. I do
agree that logical function/variable names do go a
long, long way.

 

In a perfect world, the best documented code has no comments.

Bobby, very well said. Your example illustrates an ancient rule of lisp
style, that no single function ought to be more than about a half dozen
lines long. It's perfectly clear and understandable at a glance, and
assuming that each of the functions called is equally crisp, this program
would be a cinch to maintain. Lisp lends itself well to this kind of
pseudo-coding. In all but the simplest cases, I usually begin a program in
just this way, starting with function "stubs" such as (defun
EntitiesWereCreated () t) and then fleshing them out one at a time. It's a
lot easier for me to grasp a complex routine if the "main" portion is
designed in this way.

 

See what I mean?... <veg>

 

Hey David,
Nice to talk to you again, it's been so long

I actually tried to code with the pseudocode method as described in Code
Complete. It did help me quite a bit, but I had a lot of trouble making it
a habit. Since then I have found another similar method that I have been
able to make into a habit. It's called coding by intention. It's the same
theory as pseudocode, but instead of writing comments, you actually write
code.

In my short example, the first thing that I knew that needed to happen was
that entities needed to be created. But instead of writing a pseudocode
comment that said "Create entities here" or whatever, I went ahead and coded
a call to a procedure that will sometime in the future create entities. The
key is that the name of the procedure must be just as clear as a comment. I
don't code the body of the entity creating procedure until I am done with
the current procedure which could contain calls to any number of future, or
existing, support procedures. More often than not I'll end up refactoring
part of the code because I rarely get it right the first time.

I can't say that I failed at the pseudocode method and succeeded at the
coding by intent method because "It's better". I'd say that it had just as
much to do with the fact that I already had experience in attempts to
improve my code and something finally stuck. Although in the end I do
prefer to read code than to read comments explaining the code.

I hear you! The day that I stop learning to make my code quality better is
the day that I stop coding. And if it's not, it should be.

Anything to improve consistency is an improvement in my book

As far as naming goes, I can actually feel my eyes glaze over every time I
see code with short meaningless identifier names. They do this often as I
maintain a lot of my own code that was written with very poor names :-(

 

Hi Tom,
My own coding style has slowly evolved into just what you are describing.
I'm very pleased with it so far. And it's not just limited to LISP. It's a
proven method in multiple languages.

Your example demonstrates a great point! For testing purposes it's a good
idea to code a function so that initially it returns a valid value. This
allows you to incrementally test your code. When I see good practices like
this it helps to cement them in my mind, and I need all the help I can get!
Thanks Tom.

 

OK, Tom.

Now this raises another question.

I've heard this half-dozen line 'ancient rule' before and I either:
1 - don't get it (most likely) OR
2 - just can't see how it works in actual practice, without have a bajillion
subroutines that do one little thing, used one time, in all your code -
which seems (to me) to be overkill to the nth degree.

Now, I've got a toolbox library (growing) of short, succinct, useful
functions, that I use alot in my routines, and, where I can consolidate
code, I try to do so - but I seem to always find that more is needed - much
much more, than just stringing the toolbox functions together to do what I
want.

I see the value in function 'stubs', and I really like your suggestions -
but again, I usually just can't seem to get things down to 6 lines (nor even
a dozen) - even by removing my 'superfluous' comments

And I don't think my routines are that 'tricky'/complex either.
But I can't seem to break things down further, without having a giant set of
one-off argument saturated functions that give me a headache just thinking
about what variable I forgot to include/set/return.

Perhaps I'm just too linear (or, actually, rotund). Is that so wrong?

Best regards,
David Kozina

 

Hi Tom

All what you need is a well described header to a function. The rest must be
self explaining.

Code:

;
; -- VxGetShortName
; Returns the short path/name used by programs that require the earlier 8.3
; file naming convention.
; Copyright:
;   ©2004 MENZI ENGINEERING GmbH, Switzerland
; Arguments [Typ]:
;   Fil = Filename "C:\\Program Files\\ScrapFolder\\ScrapInit.dll" [STR]
; Return [Typ]:
;   > Short path/name [STR]
;   > False if file doesn't exist
; Notes:
;   - Requires ScrRun.dll.
;
(defun VxGetShortName (Fil / FilObj FilSys RetVal)
(setq FilSys (vlax-create-object "Scripting.FileSystemObject")
RetVal (cond
((= (vlax-invoke FilSys 'FileExists Fil) 0) nil)
((setq FilObj (vlax-invoke FilSys 'GetFile Fil))
(vlax-get FilObj 'ShortPath)
)
(T nil)
)
)
(if FilObj (vlax-release-object FilObj))
(vlax-release-object FilSys)
RetVal
)

Cheers

 

Hi Jürg, I agree, that's a very good example of a function header. It
documents the dll dependency and gives all necessary information in a
concise way. If any global variables that are set by the function, those
would be noted also.

Personally I don't do much in-line commenting unless I think it's really
needed for clarity. Like Jason, I dislike the unnecessary ";end of setq"
type comments.