[squeak-dev] self error: 'comment only'

Nicolas Cellier nicolas.cellier.aka.nice at gmail.com
Tue Mar 24 21:09:34 UTC 2020

Le mar. 24 mars 2020 à 15:55, Eliot Miranda <eliot.miranda at gmail.com> a
écrit :

> > On Mar 23, 2020, at 9:57 PM, K K Subbu <kksubbu.ml at gmail.com> wrote:
> >
> > On 23/03/20 12:20 PM, Nicolas Cellier wrote:
> >> Hi all,
> >> since Tim raised the subject, let's return to caesar
> https://en.wikipedia.org/wiki/Literate_programming
> >> Otherwise, what Subbu said makes a lot of sense for me.
> >
> > Thank you for your supportive words.
> >
> > LP was a great idea for creating books or articles describing code in
> languages like Pascal or C, but it doesn't fit our needs. Times have
> changed. Squeak code graph is huge, live and 3D [1]. A static linear
> rendering will be woefully inadequate.
> +1000.  One of the flaws of Literate Programming is that it presents a
> post-hoc rationalization of the code, not how it actually came to be.
> Another is that it is designed to present a program rather than a library.
> Documenting an evolving library, that includes executable examples and
> tests, is a different thing.
> Agree, I don't think that literate programming perfectly fits very
versatile Smalltalk style.
It's just that we cannot avoid to cite the original conceptor.

Something Alan Kay and I nearly started discussing on Quora is how to write
> unit tests as both specification and documentation of an API.  This could
> be literate programming done right.  It doesn’t fit every use case; only
> certain kinds of API (say sequence manipulation APIs such as
> includesSubstring:, copyReplace:from:to:with:startingAt:, and arithmetic).
> But if the tests are written to be read as a guide one may be able to
> combine language/api specification with verification and documentation in
> the same single piece of executable code.
> I would like to see such thing!
This is the reason why I sometimes tend to write too long tests, like
FloatTest>>testCharacterization for the sake of linking the pieces of logic
I don't know if it is an antipattern (because the failure reports are no
more informative if ran by CI bots), but we need some form of narration.

> > [1] Craig Latta's Nexus demo https://youtu.be/xCwidGFkn4Q
> >
> > I expect a modern guide to be like the guided tours in science expos or
> film studios - live, direct, concrete and interactive. It should be built
> with the same materials and operated by the same tools (staff) as the rest
> of the system.
> +1000. Somewhat related, see Tudor Girba’s examples extension of unit
> tests.
> >
> > As Timothy and Tim have pointed out, we already have most of the low
> level support (doclets, hypertext, help topics) in place. We need a high
> level perspective and design to get them to work together to create a
> seamless experience.
> And you, Subbu, have they vision.  I especially liked your
> characterization of principles, etc, three or do messaged earlier in this
> thread.  Please push this.
> +1

> >
> > Regards .. Subbu
> >
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.squeakfoundation.org/pipermail/squeak-dev/attachments/20200324/f92e23c1/attachment.html>

More information about the Squeak-dev mailing list