Re: Issues of style, especially with regard to code examples

On 8/25/2016 12:46 PM, John Yeung wrote:

But for me, the fact that examples tend to be copied verbatim actually
reinforces my "strive for craftsmanship" mentality when I write them.
(This is in contrast to production code, which tends to be uglier but
hopefully more robust than examples.)

Since people are going to be copying verbatim, I worry that if I show them

action = 'Z';
coolAPI(action: data);

instead of simply

coolAPI('Z': data);

then when it comes time for them to try hooking it up to a dynamic
process, what they are going to write is

// Part of a loop that loads a new value into ACTCODE on each iteration:
action = actcode;
coolAPI(action: data);

instead of simply

coolAPI(actcode: data);

I mean, the extra step is not a crime. It's not even expensive. But I
don't really see what it gains, and I hate to encourage unnecessary
code.

I have personally been... notified that an example like coolAPI('Z':
data) should clearly show the places where variables can be used. That
my example using a literal 'locked' their mind into 'only a literal can
go there' mode. To the point where he wrote code like

if condition1
coolAPI('A': data)
end
if condition2
coolAPI('B': data)
end
if condition3
coolAPI('C': data)
end

I wish I were joking. Anyway, I don't disagree with your analysis. I
personally don't see any difference between using a literal and using a
variable. I could have used a more complex example where the function
code was set in one place and used/referenced in a different place but I
followed my typical pattern of calling an API with variables.

Now, after saying all that, I timidly ask: What exactly was wrong with
the compile-time array example? I'll reproduce it here, since this is
a new thread:

Decades ago, there was a 'Teach yourself RPG' course; I can't remember
the company. They had an example of a compile time array that
traumatised me. They put the headings for a printed report in the
array. So the O-Specs were like

OQSYSPRT H 203 1P
O OR OF
O UDATE Y 10
O ARR,1 90
...

The reason this traumatised me isn't the example per se. It's the
fact that dozens; perhaps hundreds of RPG programmers took that
example as a way to do O-specs. I have personally witnessed this
pattern in thousands of programs, in multiple companies.

Let me back up. First of all, are you saying that they used the CT
array for the report title or for column headings? If the latter, then
was each heading its own array element, or were they glommed together
into one long element? And was ARR the actual name of the array?

Column headings.
One long element.
If ARR wasn't the actual name, it was something equally useless.

Adding a column of data to the O-spec meant puttering with spaces in the
compile-time array to make things line up. Ew.

What would have been a better way to write the O-specs?

OQSYSPRT H 203 1P
O OR OF
O UDATE Y 10
O 16 'Cust'
O 28 'Name'
O 48 'Address'
O D 1 01
O CUST# 17
O CUNAME 40
O ADDR 60