> From: Ed Prochak <edproc...@[EMAIL PROTECTED]
>
> It might help to know a phrase I have used for many years which is
> Self-do***enting code isn't.
"A half truth is a lie."
So-called "self do***enting" code goes a long way to making it
easier to follow code when somebody is studying the code to see how
it works interally, which can be at all levels of abstraction, from
low-level tools that hack machine registers or use tricky bit
vectors etc., to high-level scripts that merely piece together all
the mid-level utilities to accomplish an overall task. Consider the
difference between reading code where the local variables follows
the Java or Lisp convention of long descriptive names, vs. short
cryptic names.
But I agree such code doesn't fully do***ent itself, see your
comments and my responses below:
> Normally I use this in the context that code can only tell you
> what it does (the implementation), it cannot tell you what it
> should do (the requirements).
For ease of human understanding, I would go further: Comments
directly accompanying the code make it much easier for humans to
grasp the basic idea of the algorithm, after which reading the
actual lines of code is like "of course, of course, of course, of
course" instead of "what is *that* supposed to do, why is that line
of code there, wait a minute how does this actually work".
Now back to topic:
> I think you might be overreaching for a easy term for all those
> contexts. An abstract data type is abstract for a reason. The
> functionality (look up a value for a given key) can be very
> different from the implementation. just define the functionality
> in the comments and design do***ent, pick a term to associate with
> that for your context and move on.
Unfortunately the most obviously descriptive term is too verbose:
"Thingy that contains keys and associated values in some sort of
table and provides the service of mapping any one key to the
associated value via lookup"
Repeating that whole phrase a hundred times in do***entation for a
software application would be ugly!! For example, here's the
description of a function that takes a set of keys and produces a
set of values:
"Given a thingy that contains keys and associated values in some
sort of table and provides the service of mapping any one key to
the associated value via lookup, and given a set of the keys, find
which of the keys are actually in the table, and retrieve their
associated values, and collect those values into a set with
duplicates removed."
I would like to make that more terse, something like
"Given a <foo>, and given a set of the keys, find which of the keys
are actually in the <foo>, and retrieve their associated values,
and collect those values into a set with duplicates removed."
where <foo> is some suitable jargon term. I take it you would
prefer I keep the longwinded "thingy" description instead?
Now back to the general topic: I prefer a whole set of
do***entation, starting with general purpose and use cases, then
specifications of how to implement use cases in terms of high-level
sub-tasks and general nature of persistent data stores, and then a
description of the purpose and methodology of each function/method
plus a general description of the purpose of each module of
functions/methods. **And** Java/Lisp-style verbose names for
everything to make it easy to follow the detailed code whenever
necessary *after* the general stuff has first been read and
basically understood. I'm ambivilent about the value of hierarchial
function-calling diagrams and UML etc., except for interlocked
tables in a relational database where UML or equivalent really
helps, partly because I like to work from a concept of bottom up
tool building, where there's no reason the manager of the toplevel
application needs to even know that the low-level utilities exist
much less how they call even lower level utilities. All the
low-level stuff that is reusable code should be "invisible", just
part of the API rather than part of the application itself as far
as the manager is concerned, except for paying whoever wrote it in
the first place.
--
Nobody in their right mind likes spammers, nor their automated assistants.
To gain access to this site, you must demonstrate you're not one of them.
Please spend a few seconds to try to read the text-picture in this box:
/----------------------------------------------------------------\
| /\ _ _| _ _ _|_|_ . _ . _ /~`|_ _. __|_ _ _ _ _ |
| /~~\| |(_| _\(_) | | ||_\ |_\ \_,| || |_\ | | | |(_|_\, |
| |
| /\ _ _| |_ _ _|_ _| _ _ _| _ _ _ _|'~) |
| /~~\| |(_| VV| |(_| | (_|(_) VV(/_ (_|| (/_(_|(_| ! |
| |
| /\ _ _ _|_|_ _ _ _ _ _ _| _ _ _ _ |
| /~~\| |(_) | | |(/_| \/(/_(_|| (_|(_)_\(/_| , |
| / |
| ~|~ _ |_ _ _ _ '|| |_ _ _| _ _ _| |
| | (_) VV| |(/_| | VV(/_ || |_)(/_ (_|(/_(_|(_|. |
\--(Rendered by means of <http://www.schnoggo.com/figlet.html>)--/
Then enter your best guess of the text (80-100 chars) into this TextArea:
+-----------------------------------------------------------------+
| |
| |
+-----------------------------------------------------------------+
|
