[erlang-questions] Trace-Driven Development

[Michael Turner]

On Mon, Jun 4, 2012 at 7:07 PM, Ulf Wiger <ulf@REDACTED> wrote:

>> this fact somehow hasn't made it into the documentation. Everybody has
>> to rediscover it. This is not just a waste of their time, there's also
>> the opportunity cost for Erlang/OTP (and Ericsson) in people *not*
>> discovering it because it's not named as such at www.erlang.org.
>
> First of all, I didn't dispute that seq_trace implements Lamport clocks,

And I never said you disputed it. If there's a dispute, it's whether
AXE did. I can't see that.

> only that the requirements for seq_trace had different origins.

That would be a more credible claim if the counters in seq_trace
weren't computed in a manner *identical* to the usual descriptions of
them found in the literature starting over 30 years ago.

> ... smart people working on the same type of
> problems will sometimes independently arrive at very similar conclusions.)

The copyright on the manual starts with the year 2001. Over two
decades after Lamport famously wrote, seq_trace implements exactly
what's typically described, and the AXE document -- which doesn't
supply nearly enough detail to verify independent invention -- is the
best you can offer as evidence of independent invention?

> My main reason for responding was that you accused the OTP team of being
> "dishonest" in not mentioning where their ideas came from.

"Ideas" is *your* plural, not mine. But look at the facts: there was
an obvious thing to call it -- obvious to anyone who's studied
concurrent programming, and I think you all have. One thing it's never
called in the literature is "sequential tracing."

As for dishonesty: If somebody had this algorithm described to them,
was assigned to write the documentation, and did so in a hurry,
without checking with their informant about origins, that makes them
more sloppy than dishonest.

But not taking the trouble to even *briefly* credit the foundational
work by a famous computer scientist, in the official documentation, in
2007, after the question arose on the list and was answered in the
affirmative? That's getting *really* sloppy.

> ... I maintain that
> they are not; only that many of the inputs that *actually* informed the
> implementation were either confidential or proprietary enough to be of
> no interest to the people reading the manuals.

This is an algorithm made famous among people concerned with
concurrent programming in the late 70s and in seq_trace it's
implemented identically to the canonical implementation. And I don't
have evidence of any implementation in Erlang/OTP before 2001. An idea
this widespread and remarked upon -- and by the year 2000, celebrated
as a landmark paper -- but somehow people  missed that they had
reinvented a wheel? I don't think so. At best, they missed how sloppy
their documentation was. And is.

> A question is of course how many people are helped by the seq_trace
> documentation mentioning the relation to Lamport clocks. Some might,
> but others couldn't care less; they just want to know how to use the
> functionality.

OK, so now the defense is "who cares who invented it?" There is reason
to care. When there's decades worth of literature referring to its
uses, *everybody* should care. Anything else is an encouragement to
reinvent wheels.

> We have had examples of OTP man pages in the past that
> have gone into great detail about algorithm choices, resulting only in
> terrifying anyone who came there just to learn how to use the API.

What a strawman argument. I asked: how long does it take to add
"seq_trace implements Lamport clocks"? Nowhere have I suggested that
Ericsson's documentation on seq_trace be a comprehensive treatment of
the subject. Don't put words in my mouth. I only ask for this: Credit
where it's due, and give people a starting point for further
investigation (or for the more savvy among those doing concurrent
programming, to orient them quickly to what seq_trace does.) In the
same four words.

> This is of course the big challenge when writing product manuals.

Writing a 4-word sentence giving credit where it's due is no big
writing challenge. And in this case, it's an ethical imperative.

> Many things that are of academic interest must be left out of the
> manual if it ends up confusing the reader.

In your last response, you said you weren't even sure whether
seq_trace implemented Lamport clocks. A glance by anyone familiar with
them can verify that it does. Despite your previous level of ignorance
about Lamport clocks, it now sounds like you know for a fact that they
are only of academic interest. Where is THAT certainty coming from? A
comprehensive literature survey done in a few hours?

> ... In this case, I'm pretty sure
> it could be worked in without harming readability, but it is of course
> perfectly possible to use seq_trace without understanding, or even
> being aware of the existence of, Lamport clocks.

As it happens, so far, I haven't used the Lamport's relative timestamp
feature. But I'm coming up to the point where the fact that they help
describe a partial ordering of events is an essential part of my
testing. I *will* be looking to the literature to see what's been done
on this subject. Who wouldn't, given that people have over 30 years of
experience with it now, and must have written about it?

> The OTP team is known to accept patches to the documentation,
> so please feel free to contribute to a more helpful way to describe
> the tracing support. I'm sure it would be universally appreciated.

The one time I tried to get a patch into anything in Erlang (something
that was causing a build under FreeBSD to segfault), it didn't make it
into the next release -- even though other people helped get it into
shape for submission. Pardon me for being a little leery of the
process.

I hereby suggest, for whomever it's easier: add the line "seq_trace
implements Lamport clocks." (Alternatively, "Lamport timestamps.")
Kenneth Lundin already admitted it back in 2007, on this list. It's
long past time to get it in there.

And I suggest that you NOT take the opportunity to add any supposed
"history" about how AXE implemented Lamport clocks until you can
demonstrate that it did. From what I can see in the documentation you
pointed to, AXE did not.

-michael turner