On 29/04/16 11:12 AM, Mark Levison wrote:

I'm still a practitioner, to the extent a consultant can be.

Visualations need to be derived from the code and not the annotations since I've never met a programmer who voluntary updated their JavaDoc or other annotation.

Why are we even talking about visualisations?

Let's discuss a concrete case.
My Smalltalk library includes a FileName class.
It includes these methods:

    answer everything after the final separator in a file name;
    if that's empty, answer '.' instead.
    a.b/c.d/e.f => 'e.f'

    answer the #lastPart of the file name without the
    extension and the dot that separates it from the
    rest of the last part; a dot that begins the last part
    does not count as a separator
    a.b/c.d/e.f => 'e'
    a.b/c.d/.foo => '.foo'
    a.b.c.d/e.f.g => 'e.f'

  lastPartWithExtension: extension
    answer the #lastPart of the file name with the extension
    replaced by extension; if there is no extension, append
    a dot and then extension
    a.b/c.d/e.f 'bar' => 'e.bar'
    a.b/c.d/.foo 'bar' => '.foo.bar'
    a.b/c.d/e.f.g 'bar' => 'e.f.bar'

This week I added these methods:

  lastPart: newLastPart
    answer a copy of the receiver except that it has
    newLastPart in place of the receiver's #lastPart.
    The receiver is not changed.
    a.b/c.d/e.f 'g.h' => a.b/c.d/g.h

    answer a copy of the receiver except that its
    #lastPart has no extension.
    The receiver is not changed.

  withExtension: extension
    answer a copy of the receiver except that its
    #lastPart has the given extension in place of
    any extension the receiver has.
    The receiver is not changed.

In the current implementation, it *happens* that
#lastPartSansExtension and #lastPartWithExtension:
call #lastPart, but that really is an accident of
the implementation and I've considered an alternative
in which they wouldn't.  So control flow might, or
then again might NOT, detect some of the relationships,
depending on the implementation.

However, #lastPartSansExtension and #lastPartWithExtension:
do not call each other.  The relation between them is a
*semantic* relation.  #lastPartSansExtension is not, for
example, a special case of #lastPartWithExtension:,
passing an empty string to the latter gives you an answer
with a trailing dot, while the former does not.

There is an important *semantic* connection between
#lastPart and #lastPart:, but it's not a control flow
relationship, and to the extent that it involves
reading common data, that's true of practically *all*
the methods in the class, and wouldn't distinguish them
from anything else.

Again, there is an important *semantic* connection
between #lastPartSansExtension and #sansExtension,
but neither calls the other, and the reason they both
exist is that they return different (and different
kinds of) results.  They are *alternatives*.
I have annotated them like this.

      <alternativeTo: #lastPartSansExtension facet: #result>
      <alternativeTo: #sansExtension facet: #result>

If there is indeed a visualisation tool that can not only
display this but infer it *without* annotations, I would like
to know about it.

On the other hand, the FileName class has 194 methods
(139 if you don't count inherited methods), and a visualisation
of even 139 things is not going to be terribly helpful.

There are tools I'd definitely like to have, like ones that
colour your code to show how commonly things are executed.
But that's only going to help you with what you DID use,
not with *alternatives* that SHOULD have been used instead but

I've seen literate code on rare occasions, mostly from teams doing BDD/TDD. Even those teams have had rough edges.

So?  What I'm working with at the moment is one-line machine-readable
annotations, not paragraphs of text.  In an annotation like
  <alternativeTo: #Selector facet: #Facet>
it is perfectly possible for the machine to check that there is in
fact a Selector for this one to be an alternative to, so we're not
talking about the kind of stuff that can become untrue during
maintenance without anyone noticing.  (At the moment the annotations
are not checked because I am still trying to work out what they should
*be*.  When that's done, certainly.)

Indeed, one of the reasons I want to annotate rhetorical structures/
semantic relationships is that if you need to change a method, you
may well need to change *related* methods, possibly in other classes
or modules.

You received this message because you are subscribed to the Google Groups "PPIG 
Discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to ppig-discuss+unsubscr...@googlegroups.com.
To post to this group, send an email to ppig-discuss@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Reply via email to