Hi Tom,
On 12/22/2013 3:24 AM, Tom Gardner wrote:
> On 22/12/13 01:39, Don Y wrote:
>
>>>>>> Ah, but the religion dictates that the comments
>>>>>> /always/ get out of sync with the code. The code is
>>>>>> The One Executable Truth (fair enough), therefore
>>>>>> comments (which will become wrong) are a heresy
>>>>>> that should be eliminated in case they mislead.
>>
>> Religion is great -- except when it isn't. :<
>>
>> In my most recent projects, I am moving most of the commentary
>> *out* of the codebase entirely (I played with LP and found it
>> "tedious", to say the least!). In separately maintained documents,
>> I can express what I want to say without the constraints of AN
>> IMPLEMENTATION binding my explanation. I can develop an idea
>> from scratch, illustrating "naive" approaches, refining them,
>> pointing out pathological cases, etc.
>
> Now that's becoming religion (see comments above :) )
No. It's not "enforced". Rather, it's just the most
convenient, maintainable way of presenting a *lot* of
background information to the developer in a way that
doesn't clutter up the sources needlessly.
First time I did this was for a 9-track tape driver that I wrote.
Pages and pages of commentary explaining how the interface(s),
formatter(s) and transport(s) interacted. This was necessary
so a maintainer would understand why *this* path was optimized
a particular way while this other (seemingly equivalent)
path was not. Also, essential for someone to understand how
the seek algorithms worked, how "read backwards" was a viable
operation, etc.
Putting all that *in* the driver "code" made it unwieldy.
And, it didn't *need* to be there -- as long as the person
reading/maintaining the code could be relied upon to be familiar
with its contents!
This made commenting the *actual* code much easier -- I could
just concentrate on decribing *what* it was doing instead of *why*.
> There is always a need for some documentation outside the
> codebase.
In theory, *specifications*. In practice, I rarely encounter
any "live" comments outside of the actual code itself.
> However I have found, with Java in telecom and financial
> soft-realtime systems, that this is an /irreplacable/ 90%
> solution:
> - carefully separation between
> - "client" API: public _interface_ at the top-level
> that containing all that is used by clients; typically
> a list of methods interface and a factory class
> - "implementation" API: internal _abstract_classes_
> that provide the framework for the implementation
> - "extension" API: _protected_ internal classes/methods
> so that subclasses can override/extend
> - "internal" API: _private_ classes/methods except where
> necessary to widen visibility for the
> client/implementation/extension APIs
> - liberal careful use of the _package_ namespace mechanism
> to enforce the above
> - use of Javadoc, a neat mechanism for entwining and
> separating the code, comments and documentation
> - use of a IDE with code completion, which naturally
> presents a client with /all and only/ the methods that
> can be invoked at each point
>
> Little of that is possible in C.
> C++ is a little better, but a pale echo of the Java mechanisms
> which is usually avoided because it is so easy.
I think commentary is largely a function of the mindset of the
coder. I like leaving notes to myself. Hopefully, they have
value to others, as well. Often, they are reminders of boundary
conditions or dark corners that could bite me. Other times,
reminders of assumptions that are *not* valid (e.g., I posted
a program in S.E.D recently that had a common subexpression
intentionally factored out of the statements in which it should,
otherwise, have been comfortable residing -- let the compiler
find it and factor it out, right? Ah, but compiler would NOT
do that, in this case so do it manually...
>> And, I am not constrained to the exclusive use of text! An
>> illustration is often *so* much more instructive! Or, a graph
>> that makes clear how one thing relies on another. Or, a sound
>> clip (how do you describe the difference between a "Boston"
>> accent and a "New York" accent to someone who has heard neither?)
>
> In my experience diagrams are principally useful at a
> much "higher" documentation level than code.
I find most of the documentation that is "eeded" in the code
explains the algorithms being used and their "gotchas".
Most folks -- given an explanation of the algorithm -- can
usually follow along *lightly* commented code quite well.
The real chore comes when they are trying to understand your
algorithm, any special cases that you're handling, etc.
This, IMO, doesn;'t need to sit *in* the code as long as you
can refer back to something in the "external" documentation
that will "ring a bell" with someone who has, presumably, read it.
> With Java the promise of UML has largely (but not completely)
> been made moot by modern refactoring IDEs. C/C++ fundamental
> ideals preclude such refactoring browsers.
>
>> I'm currently working on embedding interactive examples in these
>> documents so a "reader" can experiment with the issues being
>> addressed and "see" the results firsthand (instead of trying to
>> tabulate umpteen different cases: how does glottal open
>> percentage contribute to "breathiness" in speech?)
>
> Interesting at the design level, but I'm skeptical about
> the code level.
As I saaid, its helpful in illustrating the underlying basis for an
algorithm. E.g., taking the breathiness example, you play with
some parameters and *hear* the difference in (otherwise constant)
speech and its a lot easier to relate that effort IN THE CODE to
the audible result. You have a first-hand feel for what the parameter
does and it's "value" in the algorithm. And, an easy reference against
which to test an implementation! (What is 40% supposed to sound like?
Is there really much difference between that and 37.5%? Can I eliminate
a floating point multiply if I restrict the range of settings...?)
>> Because this document is NOT intimately tied to the codebase
>> (i.e., "this paragraph of commentary belongs with this fragment
>> of code..."), it can survive drastic code revisions untouched.
>
> That's the function of my "client" and "extension" APIs
> documentation.
But they are still tied to a particular API. What if the API changes?
E.g., one can implement "breathiness" (above example) in any number of
different ways and the description of its role as well as the
interactive demos remains unchanged (aassuming the code gets implemented
correctly).
>> And, from the software's perspective, it eliminates the need
>> for lengthy explanations of what you're doing at any particular
>> point in the code -- you can make an offhand reference to something
>> from the external "overview"/tutorial document without having to
>> spend lots f verbiage explaning it, IN the code!
>
> In Java, that's all part of the Javadoc combined/extracted
> with/from the code.
>
>>>> Good commenting isn't difficult, provided the code doesn't
748236957>>>> smell and provided time
is allotted for comments.
>>
>> And the person doing the commenting has the sense to know
>> *what* to comment (i.e., what's the *real* essence of this
>> operation, not just the "obvious details")
>
> Oh yes. Good taste and intelligence. Silly of me to
> forget that it helps to have competent employees :(
IMO, that's far more important than any "religion". If people
look on comments as a "chore", they may as well not write any!
>>> Well, examples are better than comments, and external docs can
>>> be a bit of both. Web-able ( or just plain in-the-file-system)
>>> docs can be an improvement on comments.
>>>
>>> One possible challenge is to make an "API" ( that's what the kids
>>> call 'em these days ) such that you *can't* use it except in the
>>> intended manner. One can have a "WTF()" routine that returns a short
>>> English sentence describing the failure and a reference mark of some
>>> sort into the documentation.
>>
>> I've actually taken this approach at the application level.
>> Return identifiers that let the user see what part of the
>> documentation is appropriate to the problem at hand!
>> (instead of "error 0x80043584")
>
> Hasn't everybody been doing that for the last 15 years?
Shirley you jest? :>
> In Java to a significant extent that happens naturally when
> an exception is caught and handled. Simply give the exception a
> decent name and toString() method.
I take it a step further -- it's a reference *into* the on-line
manual. So, you can have a verbose description of "how you got there"
and how you can *fix* whatever your "problem" appears to be.