Languages, is popularity dominating engineering?

On 28.12.2014 г. 08:18, glen herrmannsfeldt wrote:
> Ed Prochak <edprochak@gmail.com> wrote:
>> Don wrote:
>> "The last comment is the kicker -- if you're coding for your eyes only,
>> you can do things a lot different than if others will have to view,
>> maintain or enhance your codebase"
>
> (snip)
>
>> I have followed your posts and I agree with your views on most
>> things, but I have to go against you on this idea.
>
>> Unless your memory is significantly above average, this comment is
>> just wrong. It is the opposite of this that I use as a guide to
>> comments in the code. IOW,
>
> I think I agree some with both.
>
> It is always a good idea to comment so that others can understand,
> and also so you can understand in the future. It is not a bad idea
> to assume others will have to understand, and write them with that
> assumption.

The way I do it is to write what I would be saying as an explanation
of what I am doing to someone looking over my shoulder who knows the
programming language, making sure I do not lose him.

>
> Maybe my memory is somewhat above average. I do still remember the
> first program I ever wrote (well, had help writing) when I was
> nine years old, and running it on a B5500.
>
> -- glen
>

My memory is quite good, too - and I also remember pieces of code
I have written 20 and 30 years ago.
But I do not remember everything I wrote over the past 20-30 years,
not a chance. I have not counted recently but it must exceed 50
megabytes of sources, there simply are things I have forgotten
I did at all, let alone how and why :-).

Dimiter

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

Hi Glen,

On 12/27/2014 11:18 PM, glen herrmannsfeldt wrote:
> Ed Prochak <edprochak@gmail.com> wrote:
>> Don wrote:
>> "The last comment is the kicker -- if you're coding for your eyes only,
>> you can do things a lot different than if others will have to view,
>> maintain or enhance your codebase"
>
> (snip)
>
>> I have followed your posts and I agree with your views on most
>> things, but I have to go against you on this idea.
>
>> Unless your memory is significantly above average, this comment is
>> just wrong. It is the opposite of this that I use as a guide to
>> comments in the code. IOW,
>
> I think I agree some with both.
>
> It is always a good idea to comment so that others can understand,
> and also so you can understand in the future. It is not a bad idea
> to assume others will have to understand, and write them with that
> assumption.

Writing comments is *something* like writing a (good) manual.  Ideally,
you want to present information in a manner that allows a newbie to
be led "up to speed" on the specifics involved.  And, at the same time,
don't want to burden an experienced user (who just needs "reminding").

I.e., often, different documents (manuals) are prepared to address
the different types of readers.  But, with source code, we're stuck
with *one* document to address *all*.

[The analogy falls down because a manual typically has to assume some
readers know *nothing* about the subject matter!]

> Even so, I can imagine using some tricks that I would remember and
> understand, but wouldn't want to try to explain in the comments so
> someone else could understand.

<frown>  Then what do you expect those readers to do when they
encounter your tricks -- skip over that part of the code?

If I do something "too clever", I fall back on the "Here there be dragons"
preamble -- letting myself and others know that the following bit of
code needs to be parsed carefully.  I.e., if you're just trying to "see
what's going on" in the code, feel free to skim/skip over.  But, if you
really are trying to understand the nitty-gritty, then take *careful* note
of what follows.

> Maybe my memory is somewhat above average. I do still remember the
> first program I ever wrote (well, had help writing) when I was
> nine years old, and running it on a B5500.

B5000/5500 were interesting machines.  Really sad to see how so much
of that innovation "was unsuccessful" (in the market)

Don Y <this@is.not.me.com> wrote:
 
>> Ed Prochak <edprochak@gmail.com> wrote:
>>> Don wrote:
>>> "The last comment is the kicker -- if you're coding for your eyes only,
>>> you can do things a lot different than if others will have to view,
>>> maintain or enhance your codebase"

(snip, then I wrote)

>> Even so, I can imagine using some tricks that I would remember and
>> understand, but wouldn't want to try to explain in the comments so
>> someone else could understand.
 
> <frown>  Then what do you expect those readers to do when they
> encounter your tricks -- skip over that part of the code?

As I now put back together, that was the "for my eyes only" case.

I suppose one never can be sure that no-one else will need to see
something, but then I might have a chance to add more comments before
someone else saw it.
 
> If I do something "too clever", I fall back on the "Here there be dragons"
> preamble -- letting myself and others know that the following bit of
> code needs to be parsed carefully.  I.e., if you're just trying to "see
> what's going on" in the code, feel free to skim/skip over.  But, if you
> really are trying to understand the nitty-gritty, then take *careful* note
> of what follows.

I suppose so.  Or I might not even realize how strange it is.

(snip on B5500)

-- glen

Hi Dimiter,

On 12/28/2014 7:20 AM, Dimiter_Popoff wrote:
> On 28.12.2014 г. 08:18, glen herrmannsfeldt wrote:

>> Maybe my memory is somewhat above average. I do still remember the
>> first program I ever wrote (well, had help writing) when I was
>> nine years old, and running it on a B5500.
>
> My memory is quite good, too - and I also remember pieces of code
> I have written 20 and 30 years ago.
> But I do not remember everything I wrote over the past 20-30 years,
> not a chance. I have not counted recently but it must exceed 50
> megabytes of sources, there simply are things I have forgotten
> I did at all, let alone how and why :-).

Yup.  *Terrible* feeling to look at something *you* wrote and not
be able to recall *why* you "did it *that* way".  I.e., have you
*learned* something since then that has caused you to favor a
different approach?  Is this just a "stylistic" change?  Or, is
there something that isn't immediately apparent lurking in that
implementation that protects it from some sin...

[Best wishes for the coming New Year!]
--don

On Thu, 25 Dec 2014 19:34:35 -0800, Ed Prochak wrote:

> Don wrote:
> "The last comment is the kicker -- if you're coding for your eyes only,
> you can do things a lot different than if others will have to view,
> maintain or enhance your codebase"
> 
> Hi Don,
> I have followed your posts and I agree with your views on most things,
> but I have to go against you on this idea.
> 
> Unless your memory is significantly above average, this comment is just
> wrong. It is the opposite of this that I use as a guide to comments in
> the code. IOW,
> 
> what information will I need if I have to fix a problem in the code 6
> months from now? That's what drives the comments.
> 
> If I would need that information, then I am sure another maintenance
> programmer will need it even more!

I will sometimes write throw-away code, and, to encourage it being thrown 
away by anyone other than me who uses it (including future-me), I will 
leave off _all_ comments, except maybe a comment that says

// This is test code, lack of comments is deliberate

or perhaps

// we don' need no steenking comments

-- 

Tim Wescott
Wescott Design Services
http://www.wescottdesign.com

Tim Wescott wrote:

> I will sometimes write throw-away code, and, to encourage it being thrown
> away by anyone other than me who uses it (including future-me), I will
> leave off _all_ comments, except maybe a comment that says
> 
> // This is test code, lack of comments is deliberate
> 
> or perhaps
> 
> // we don' need no steenking comments

I write plenty of throw-away code when exploring some ideas and avenues of 
thinking that may or may not lead me to a problem. I still write some 
comments with that code and mark it down as an exploratory artifact. 
Sometimes, the code is just playing around with a wild notion.

The one thing I make certain of is that this prototype or throw-away code 
never enters the production code stream. I just take the resultant 
information and write a better specification for the code that will be in 
the production release (which is subject to very robust review and test).


-- 
********************************************************************
Paul E. Bennett IEng MIET.....<email://Paul_E.Bennett@topmail.co.uk>
Forth based HIDECS Consultancy.............<http://www.hidecs.co.uk>
Mob: +44 (0)7811-639972
Tel: +44 (0)1235-510979
Going Forth Safely ..... EBA. www.electric-boat-association.org.uk..
********************************************************************

Tim Wescott wrote:
> On Thu, 25 Dec 2014 19:34:35 -0800, Ed Prochak wrote:
>
>> Don wrote:
>> "The last comment is the kicker -- if you're coding for your eyes only,
>> you can do things a lot different than if others will have to view,
>> maintain or enhance your codebase"
>>
>> Hi Don,
>> I have followed your posts and I agree with your views on most things,
>> but I have to go against you on this idea.
>>
>> Unless your memory is significantly above average, this comment is just
>> wrong. It is the opposite of this that I use as a guide to comments in
>> the code. IOW,
>>
>> what information will I need if I have to fix a problem in the code 6
>> months from now? That's what drives the comments.
>>
>> If I would need that information, then I am sure another maintenance
>> programmer will need it even more!
>
> I will sometimes write throw-away code, and, to encourage it being thrown
> away by anyone other than me who uses it (including future-me), I will
> leave off _all_ comments, except maybe a comment that says
>
> // This is test code, lack of comments is deliberate
>
> or perhaps
>
> // we don' need no steenking comments
>

Taking a cue from xkcd, I've taken to:
//#undef _WTF_
//#define _WTF_ 1

#if _WTF_
...
#endif

-- 
Les Cargill

Hi Glen,

On 12/29/2014 12:13 AM, glen herrmannsfeldt wrote:
> Don Y <this@is.not.me.com> wrote:
>
>>> Ed Prochak <edprochak@gmail.com> wrote:
>>>> Don wrote:
>>>> "The last comment is the kicker -- if you're coding for your eyes only,
>>>> you can do things a lot different than if others will have to view,
>>>> maintain or enhance your codebase"
>
> (snip, then I wrote)
>
>>> Even so, I can imagine using some tricks that I would remember and
>>> understand, but wouldn't want to try to explain in the comments so
>>> someone else could understand.
>
>> <frown>  Then what do you expect those readers to do when they
>> encounter your tricks -- skip over that part of the code?
>
> As I now put back together, that was the "for my eyes only" case.
>
> I suppose one never can be sure that no-one else will need to see
> something, but then I might have a chance to add more comments before
> someone else saw it.

You also can never be sure that *you* won't later want to consult
that code (and have forgotten salient aspects).

A long time ago in a galaxy far away I hacked together a little piece
of code to reverse engineer some PLA's that were being used to protect
a piece of expensive software (i.e., a "hardware key").  The PLA's
essentially were just implementing FSM's that appeared "complex" to
casual probes (but the licensed software "knew" how the PLA's would
respond to seemingly random stimuli).

I was discussing this with a friend several weeks ago as an example
of an approach he could use in a project with which he was involved.
The approach he was planning on taking was far too naive -- the
algorithm I had implemented was much more efficient.  (And, much
more deterministic -- his approach could lock up with certain types
of inputs).

That evening, I dug through my (paper!) archives and found a printed
copy (the original source only lived for a few days -- once I had
reverse engineered the PLA's, it had outlived its usefulness).

The code is reasonably clear for something I'd written several decades
ago (though I can see stylistic changes).  And, very *few* comments.
The code is largely "self-documenting":

    /* find an intermediate state closer to the destination state */
    for (place=MINSTATE; place<=MAXSTATE; place++)
       if (distance[location][place] == 1)
          if (distance[place][goal] < shortest)
             break;

    /* find a stimulus which gets us to that intermediate state */
    for (tickler=MINSTIM; tickler<=MAXSTIM; tickler++)
       if (transition[location][tickler] == place)
          break;

But, the comments that are present convey the essence of *why* the
code is doing what it is doing.

Had I *not* included any commentary, it would have been a bit harder
for he (or I!) to sort out what was happening in the implementation.

>> If I do something "too clever", I fall back on the "Here there be dragons"
>> preamble -- letting myself and others know that the following bit of
>> code needs to be parsed carefully.  I.e., if you're just trying to "see
>> what's going on" in the code, feel free to skim/skip over.  But, if you
>> really are trying to understand the nitty-gritty, then take *careful* note
>> of what follows.
>
> I suppose so.  Or I might not even realize how strange it is.

You want to deliberately cause the reader to "stumble" (hesitate)
so he doesn't read things *into* the code that aren't really there.
E.g., seeing "<=" as a terminating condition for a loop instead of "<"

Hi Paul, Tim,

On 12/29/2014 7:19 PM, Paul E Bennett wrote:
> Tim Wescott wrote:
>
>> I will sometimes write throw-away code, and, to encourage it being thrown
>> away by anyone other than me who uses it (including future-me), I will
>> leave off _all_ comments, except maybe a comment that says
>>
>> // This is test code, lack of comments is deliberate
>>
>> or perhaps
>>
>> // we don' need no steenking comments
>
> I write plenty of throw-away code when exploring some ideas and avenues of
> thinking that may or may not lead me to a problem. I still write some
> comments with that code and mark it down as an exploratory artifact.
> Sometimes, the code is just playing around with a wild notion.
>
> The one thing I make certain of is that this prototype or throw-away code
> never enters the production code stream. I just take the resultant
> information and write a better specification for the code that will be in
> the production release (which is subject to very robust review and test).

This is the risk.  It's *too* easy to take some "found code" hiding
on your machine that (*almost*) works (at least it did so good enough
to satisfy those initial "experiments") and use that to jump-start
some *real* code.

Without comments, you're likely to misremember what the code *didn't*
address in it's initial, tentative implementation.  As the piece of
code *grows* (size/complexity), there is more of a temptation to
salvage it ("I'll just ADD some error checking here... and here...").

When I am "playing", files get names like "{foo,baz,ttt}.c".  As I
often get pulled away from a project for short periods of time, any
files having these names will almost always get deleted when I return
to the project -- because I can't recall *enough* of what I was doing
with them to resume those investigations.

I've also found IDE's and modern debuggers to make this a lot easier.
Instead of investing a fair bit of code in gathering arguments and
parameters from the user (i.e., "me" during these efforts) *and*
pretty-printing results for easy interpretation, I can just start
the routine with a breakpoint at "main()" and *stuff* values into
specific variables.  Similarly, after running the code to "almost
completion", I can use the same tools to examine live variables
without having to write/print their results.

I.e., it encourages me to NOT invest much in investigatory code so
I am VERY willing to err on the side of throwing away an "unfamiliar"
file instead of trying to salvage the work it represents.

On 30.12.2014 г. 00:55, Tim Wescott wrote:
> On Thu, 25 Dec 2014 19:34:35 -0800, Ed Prochak wrote:
>
>> Don wrote:
>> "The last comment is the kicker -- if you're coding for your eyes only,
>> you can do things a lot different than if others will have to view,
>> maintain or enhance your codebase"
>>
>> Hi Don,
>> I have followed your posts and I agree with your views on most things,
>> but I have to go against you on this idea.
>>
>> Unless your memory is significantly above average, this comment is just
>> wrong. It is the opposite of this that I use as a guide to comments in
>> the code. IOW,
>>
>> what information will I need if I have to fix a problem in the code 6
>> months from now? That's what drives the comments.
>>
>> If I would need that information, then I am sure another maintenance
>> programmer will need it even more!
>
> I will sometimes write throw-away code, and, to encourage it being thrown
> away by anyone other than me who uses it (including future-me), I will
> leave off _all_ comments, except maybe a comment that says
>
> // This is test code, lack of comments is deliberate
>
> or perhaps
>
> // we don' need no steenking comments
>

I also do that - I mark it as "to test" (choice of words must have been
made in some desperate moment....:-) ).
If a single line, this is the sole comment, it is supposed to not
survive the day.
If more, I put a comment line "to test"  at the start and an
"end to test" at the end.
If I want to leave that code in the source I isolate it with a
conditional line, like
  ifeq 0
  test code
  endc
Easy to switch on and off etc. Once or twice I threw away more than
"to test" code; I felt bad about deleting it (had been rewritten though
it was not that bad) so I left it after the "end" statement (so the
compiler/assembler ignores it).... :D .

I wish I could say I have never found "to test" lines in code working
and untouched for years though :-).

But my best was to dig deep down to the lowest system call level of
something which did not work under some circumstances - on a system
which had been working for years (may be 5, was about 15 years ago).
After _some_ digging I located it- was an "RTS" (return from subroutine)
line, comment on it being "until written" :D :D .

Dimiter

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