Parser, again!

Tom Gardner wrote:
> On 20/12/13 19:39, Les Cargill wrote:
>> Tom Gardner wrote:
>>> On 15/12/13 20:47, Les Cargill wrote:
>>>> Tom Gardner wrote:
>>>>> I've even seen Them strip out all comments from a
>>>>> well-documented library on the /principal/ that "comments
>>>>> get out of sync with code" and "good code doesn't need
>>>>> comments". Often valid,
>>>>
>>>> Not if you have good shop culture to support comments.
>>>> reviews help, too - if you can manage them well.
>>>
>>> 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.
>>>
>>
>> I kinda tend to think that, too. Hell is other
>> people's code :)
>
> I'll disagree, somewhat: "hell is having to *look at*
> other people's code".
>

Much better!

> E.g. I don't think a networking stack is hell; I just use it.
>
> Good comments *reduce* the amount of code I have to
> look at because:
>    - the problem I'm debugging doesn't match what their
>      code is doing
>    - they give me sufficient information for me to judge
>      accurately the pros and cons of using their code,
>      and/or to select between different approaches
> all without my having to make guesses based on speed reading
> their code and misunderstanding the subtleties and rationale
> behind it.
>
> Good commenting isn't difficult, provided the code doesn't
> smell and provided time is allotted for comments.
>
>

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.

-- 
Les Cargill

On 20/12/13 21:17, Les Cargill wrote:
> Tom Gardner wrote:
>> Good comments *reduce* the amount of code I have to
>> look at because:
>>    - the problem I'm debugging doesn't match what their
>>      code is doing
>>    - they give me sufficient information for me to judge
>>      accurately the pros and cons of using their code,
>>      and/or to select between different approaches
>> all without my having to make guesses based on speed reading
>> their code and misunderstanding the subtleties and rationale
>> behind it.
>>
>> Good commenting isn't difficult, provided the code doesn't
>> smell and provided time is allotted for comments.
>>
>>
>
> 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.

Tutorials are helpful and have advantages that cannot easily
be duplicated by other means, but they are not sufficient.

Decent comments describe the codes' requirements and guarantees
whereas tutorials only show a few examples of usage.

Javadoc and the Java type system are imperfect, but they are
awful (and aweful) lot better than the C++ "equivalents".

But then one of the impressive things about the 1996 Java Whitepaper
was the way it stated "feature X has been shown to be good by
language Y", and "X has been shown to complement Z in A" - in
other words Gosling et al learned from a wide range of
previous experience.

OTOH, the C++ world almost seemed to take a peverse satisfaction
in not knowing what had been show to work fail - and thus they
reinvented many elliptical wheels.

> 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 once did a reasonable job in that respect only to find that the
"invoke XP magic" weenies promptly made all getters and setters public
(rather than protected) merely so that they could add trivial and futile
unit tests. They completely and willfully missed that my pre-existing
unit tests had already done those tests, and that by opening up the
interface they enabled gross misuse of the library.

The concept of a small easily-maintainable public interface was
beyond their comprehension. (We got the code so we can easily change
it whenever any on e of us feels like it). Sigh.

On 20/12/13 20:33, dp wrote:
> On Friday, December 20, 2013 9:53:43 PM UTC+2, Tom Gardner wrote:
>> ...
>> Good commenting isn't difficult, provided the code doesn't
>> smell and provided time is allotted for comments.
>
> I'll go even further, good commenting saves programming time.
> Over the years it saves a lot of programming time and over many
> years it makes things possible which otherwise would simply be
> impractical if not impossible.
>
> I can speak for myself only of course but while I am writing
> and commenting practically each line  (here is a small utility
> as an example: http://tgi-sci.com/vpaex/ntp.sa ) I often
> discover that I have to stop coding and (re)think something.
>
> Saving time to type in a few words is a huge resource waste.
> If one does not have the comment words ready to type in he has even
> less code statements ready for typing.

I agree with you and it matches my experience, but I'll
play devil's advocate...

It saves time for the /next/ project - but the project
manager won't be the PM for that project. All the current
PM cares about is getting /their/ project completed under
budget.

Hence not commenting is a standard externality: somebody
else's problem.

Many projects (mostly non-embedded, and often database projects)
are mainly tedious boring CRUD stuff, i.e. create read update
delete with just a tiny bit of business logic all executing in
a poorly-understood magic framework execution environment.
Comments don't add anything; it is just as easy to read the code.

For several decades I swore I would never have anything to do
with databases. When I couldn't escape a project that was
largely DB CRUD plus a little bit of GUI, I realised how wise
my younger self was :)

In addition, I suspect the corporate politcking and in-fighting
was so vicious partly because the tech was so boring!

Hi Les,

On 12/20/2013 2:17 PM, Les Cargill wrote:

[attrs elided]

>>>>>> I've even seen Them strip out all comments from a
>>>>>> well-documented library on the /principal/ that "comments
>>>>>> get out of sync with code" and "good code doesn't need
>>>>>> comments". Often valid,
>>>>>
>>>>> Not if you have good shop culture to support comments.
>>>>> reviews help, too - if you can manage them well.
>>>>
>>>> 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.  :<

I've (historically) tended to be overly verbose with
comments, identifiers, etc.  Even "unrolling" idioms where
they can be intimidating (folks seem to think that if they
can use less characters to express an operation, the
compiler will use less *code* to implement it!)

In my early products (1970's), it was almost a 1:1 ratio
of code to comments.  Easy with the short "line lengths" that
ASM afforded -- just tag a comment over on the right side of
the page and let it continue over the N consecutive lines
to which it applies:
     ;advance the pointer to the...
     ;...next goal in sequence and...
     ;   ... recurse

This, however, gets impractical with longer line lengths
common if HLL's (longer identifiers, too!).  So, I started
moving to "preambles" (prefaces?) that would introduce the
code fragment/paragraph that follows.  Or, a one-liner
above a particular "significant statement".

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.

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?)

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?)

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.

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!

>>> I kinda tend to think that, too. Hell is other
>>> people's code :)
>>
>> I'll disagree, somewhat: "hell is having to *look at*
>> other people's code".
>
> Much better!

No, hell is having to make other peoples' code *work*!

>> E.g. I don't think a networking stack is hell; I just use it.
>>
>> Good comments *reduce* the amount of code I have to
>> look at because:
>> - the problem I'm debugging doesn't match what their
>> code is doing
>> - they give me sufficient information for me to judge
>> accurately the pros and cons of using their code,
>> and/or to select between different approaches
>> all without my having to make guesses based on speed reading
>> their code and misunderstanding the subtleties and rationale
>> behind it.
>>
>> Good commenting isn't difficult, provided the code doesn't
>> 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")

> 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")

On 22/12/13 01:39, Don Y wrote:

> [attrs elided]
>
>>>>>>> I've even seen Them strip out all comments from a
>>>>>>> well-documented library on the /principal/ that "comments
>>>>>>> get out of sync with code" and "good code doesn't need
>>>>>>> comments". Often valid,
>>>>>>
>>>>>> Not if you have good shop culture to support comments.
>>>>>> reviews help, too - if you can manage them well.
>>>>>
>>>>> 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 :) )

There is always a need for some documentation outside the
codebase.

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.



> 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.

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.


> 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.


> 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
>>> 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 :(


>> 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?

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.

On Saturday, December 21, 2013 8:32:01 PM UTC+2, Tom Gardner wrote:
> On 20/12/13 20:33, dp wrote:
> > On Friday, December 20, 2013 9:53:43 PM UTC+2, Tom Gardner wrote:
> >> ...
> >> Good commenting isn't difficult, provided the code doesn't
> >> smell and provided time is allotted for comments.
> >
> > I'll go even further, good commenting saves programming time.
> > Over the years it saves a lot of programming time and over many
> > years it makes things possible which otherwise would simply be
> > impractical if not impossible.
> >
> > I can speak for myself only of course but while I am writing
> > and commenting practically each line  (here is a small utility
> > as an example: http://tgi-sci.com/vpaex/ntp.sa ) I often
> > discover that I have to stop coding and (re)think something.
> >
> > Saving time to type in a few words is a huge resource waste.
> > If one does not have the comment words ready to type in he has even
> > less code statements ready for typing.
> 
> I agree with you and it matches my experience, but I'll
> play devil's advocate...
> 
> It saves time for the /next/ project - but the project
> manager won't be the PM for that project. All the current
> PM cares about is getting /their/ project completed under
> budget.

Hmmm, on that one the devil seems to be doing so-so I guess.
I have very little if any experience with product managers to
be able to judge but I imagine that even a PM has to rely
on the same person for more than a single project at times.
So he might also get the "next" project delayed... :-) .

> Many projects (mostly non-embedded, and often database projects)
> are mainly tedious boring CRUD stuff, i.e. create read update
> delete with just a tiny bit of business logic all executing in
> a poorly-understood magic framework execution environment.
> Comments don't add anything; it is just as easy to read the code.

Ah, on that the devil is doing quite well I think. I write very
few comments in command scripts for example (usually a header explaining
how to use the script). A comment line here and there inside, may be.
And the script language is (well, has become over the years) not
all that easy to read (variable names which can be made up of variables,
partial variable extraction etc.). But my scripts tend to be what,
tens of lines, a few hundred at most (if I ever wrote one that long,
not so sure; over 100 yes, over 200-300 - don't know).

Another gray area are my comments within macros. Write none
and it may become hard to understand (in VPA I rely a lot
on a very powerful system of macros, recursive, script processable,
partial argument references etc. etc.). Write a comment inside
and get it repeated too many times - and likely out of context
as it comments the design of the macro and not its use... :D (this
applies only if I need a list to look at how the macro is proceeding).

> In addition, I suspect the corporate politcking and in-fighting
> was so vicious partly because the tech was so boring!

:D 
Don't really know (no recent direct experience) but I can well
imagine this is the case.
I know I hate to the point of getting like hysteric when I have to
do the same thing more than once at times (typically because
something won't work as expected). I am not sure if I would
take another option at such a moment if I had it, I might well
do. Then again I might not, my stubbornness would likely kick
me back to do it again after all :D.

Dimiter

------------------------------------------------------
Dimiter Popoff, TGI             http://www.tgi-sci.com
------------------------------------------------------
http://www.flickr.com/photos/didi_tgi/sets/72157600228621276/

On 22/12/13 12:15, dp wrote:
> Ah, on that the devil is doing quite well I think. I write very
> few comments in command scripts for example (usually a header explaining
> how to use the script). A comment line here and there inside, may be.
> And the script language is (well, has become over the years) not
> all that easy to read (variable names which can be made up of variables,
> partial variable extraction etc.). But my scripts tend to be what,
> tens of lines, a few hundred at most (if I ever wrote one that long,
> not so sure; over 100 yes, over 200-300 - don't know).

Sounds like I wouldn't want to look (let alone maintain) that code!


> Another gray area are my comments within macros. Write none
> and it may become hard to understand (in VPA I rely a lot
> on a very powerful system of macros, recursive, script processable,
> partial argument references etc. etc.). Write a comment inside
> and get it repeated too many times - and likely out of context
> as it comments the design of the macro and not its use... :D (this
> applies only if I need a list to look at how the macro is proceeding).

Macros and templates in most (all?) languages appear to be a point
of irritation to extent that they become painful.

I try to avoid them for all but very low-level bit twiddling.

Tom Gardner wrote:
> On 22/12/13 01:39, Don Y wrote:

>> 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 :(

There's the literary problem too: different readers will have different 
needs, so it would help to know in advance whom the comment is for.  In a 
perfect world, a comment would completely explain the next bug.  In this 
world: "Yeah, right."

	Mel.

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.

On Sunday, December 22, 2013 2:35:45 PM UTC+2, Tom Gardner wrote:
> On 22/12/13 12:15, dp wrote:
> > Ah, on that the devil is doing quite well I think. I write very
> > few comments in command scripts for example (usually a header explaining
> > how to use the script). A comment line here and there inside, may be.
> > And the script language is (well, has become over the years) not
> > all that easy to read (variable names which can be made up of variables,
> > partial variable extraction etc.). But my scripts tend to be what,
> > tens of lines, a few hundred at most (if I ever wrote one that long,
> > not so sure; over 100 yes, over 200-300 - don't know).
> 
> Sounds like I wouldn't want to look (let alone maintain) that code!

Hah, well, I thought it would sound like that. But it is not. Generally
I think of writing scripts and other very high level sort of thing
not as of "programming" (which is of course wrong but this is how I
feel about it).
If you know the script language you would have little if any problems
reading a small uncommented script of these though. Here is a brief
example I did just recently (executed by the dps ftp client upon start
so it will have its own scratch directory, thus being able to run
scripts which use temporary files of the same name concurrently
in multiple instances):

*
@eoff
@path \syslib\scripts\
@path \syslib\utility\
@path \syslib\commands\
@task
@setl ftpno ]i@0
@setl temp [shellwd
@setl ftpwd ]temp ftp{$]ftpno }
@ifdefl shellwd setl ftpwd ]shellwd ftp{$]ftpno }
@mask $02   
@run md  ]ftpwd  >#null\ftp{$]ftpno }  ><!#null\ftp{$]ftpno }
@mask 0
@setl shellwd "]ftpwd \ "
@setl sc ]ftpwd \
@end
*

Hieroglyphic I suppose but does it look that scary? I would hope
not (but I don't really know... :-) ).
Things can be (and do get) larger of course but I do not remember
having had trouble getting back into one of these uncommented
scripts last 20 years.
> 
> 
> > Another gray area are my comments within macros. Write none
> > and it may become hard to understand (in VPA I rely a lot
> > on a very powerful system of macros, recursive, script processable,
> > partial argument references etc. etc.). Write a comment inside
> > and get it repeated too many times - and likely out of context
> > as it comments the design of the macro and not its use... :D (this
> > applies only if I need a list to look at how the macro is proceeding).
> 
> Macros and templates in most (all?) languages appear to be a point
> of irritation to extent that they become painful.

In vpa - having control over the whole thing, i.e. when I have needed
something which the toolchain could not do I have just added the
capability (trying to be wise enough not to do short term junk)-
eventually the macros have become a really great resource, one can
do a lot with them. I use them to switch the language level,
it does not have to be low level assembler like all the time
after all.
 Say if I make one of the menu descriptors for a call
I have, defining a parameter - where it shows up, background drawing
to put in the area, various offsets, flags (mouse action/stop etc. related
actions), ID to call for its value with etc. etc. - this fits in
a single line. The macro is not that large nor that complex but it
calls a few macros itself, 285 lines total(just looked at it). And well,
it does have some (few) comments inside. The majority of the comments
are left for the code which uses the macros though.
Mind you, when I was writing my first assembler (about 20 years ago)
I put enough effort to make macros definable within a macro....
(with all the argument passing etc.).
Carried the capability within all subsequent assemblers (vpa being
more a compiler I suppose than an assembler).
And I don't think I ever used that. :D

Dimiter

------------------------------------------------------
Dimiter Popoff, TGI             http://www.tgi-sci.com
------------------------------------------------------
http://www.flickr.com/photos/didi_tgi/sets/72157600228621276/