The triple script ecosystem benefits from programs that are written top-down. That is, it should be possible to open up a triple script, starting reading at the top of the file, and read down to the bottom in a more-or-less linear order, just like the pages in a book, and have a good understanding of the program. This is in contrast to languages like C where the conventions practically require a reader start at the bottom of the file and read to the top.
The top-down philosophy is on display in trplkt, triplescripts.org's reference compiler, where the first thing that a reader sees upon viewing the source is the primary class (TripleKit
) that is the heart of the program. We advocate that other triple scripts be written the same way. If your Build.app.htm is just a copy of trplkt, then this can be achieved in one of two ways.
The first approach is to write in your project README your build instructions as:
build -t Foo.xxx -m main.xxx
This will ensure that Foo
appears first in the resulting triple script, assuming that this is the module that best corresponds with the heart of your program.
Alternatively, you can make Foo
the first import in your main.xxx shunting block, and simply give your instructions as:
build -tm main.xxx
When implementing a class, we also advocate for keeping the top-down philosophy in mind when writing ordering methods within the file. If a method collate
calls a method seed
and collate
is seed
's only caller, then the former should appear nearer to the top of the file than the latter. When reading a triple script, it should seem like a picture that gets clearer, or a concept that gets more specific, where it originally starts out as a general outline of all that follows.
Program authors can even take advantage of function hoisting to get the same effect. Suppose you wanted to write the collate
method but didn't want to create a separate seed
method (or even a quasi-private _code
). You might instead write:
collate(collection) { if (!collection.size) { seed(collection); } /* ... actual collation implementation omitted ...*/ return collection.size; // Add some base-level entries function seed(collection) { /* ... */ } }
Notice how our collate
method has a return
statement that precedes the definition of seed
. This is legal because seed
gets "hoisted" and can be used to great effect—enabling us to write programs that read well top-down.