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:
lastPart
answer everything after the final separator in a file name;
if that's empty, answer '.' instead.
a.b/c.d/e.f => 'e.f'
lastPartSansExtension
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
sansExtension
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.
sansExtension
<alternativeTo: #lastPartSansExtension facet: #result>
...
lastPartSansExtension
<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
weren't.
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.
