Template for reviewing and debugging code through a file

(George Wyner) #1

Has anyone created a template for generating reports on what code is in use in a tinderbox file? I am thinking of a list of the code in all agents, display expressions, rules, edicts, and so on.

I know that it is possible to review code in individual notes, but thinking that having a single file that listed all use of code with helpful headings and structure might allow for a general review of code I am using.

Potential value would include:

  • Discovering errant rules or display expressions in a large file
  • Easy searching for known mistakes like a single equal sign in a comparison
  • Someday… running the resulting report through some kind of linter to look for issues (but that’s a whole other story)

Thinking of working on something like this but thought I would build on the shoulders of giants if possible.

(Andreas Grimm) #2

This would be also interesting in order to build an archive and repository of well-working code snippet one would want to re-use again and again.

(Mark Anderson) #3

Live code with exist in:

  • Stamps. Only visible via the Stamps Inspector. There is no import/export mechanism for stamps.
  • Action-type attributes. These are always system attributes. In a number of cases, e.g. Rules, the action can be turned off at note level. This code can be read (if short) via Key Attributes, some Inspectors or written to note $Text via action code.
  • Some users store code in note $Text. Pro tip: if doing this first add the built0in ‘Code’ prototype and set that for the note storing code as it turns off auto-correction of quotation mark style, etc.

So, there is no overall repository. Also, despite its now-powerful internal action code, Tinderbox isn’t a computer programming interface (IDE) app and I don’t think it aims to become one. Put another-way, it’s not code centric so code reporting/collecting is something left to the user.

In large projects, I generally make a container of Code-prototyped notes to store long/complex code in their $Text. If nothing else this means you can open the note as a tear-off text window and expand it to avoid line wrap and to properly review for bugs, etc.

Some people use stamps to store code snippets, which is safe as long as you don’t forget an apply code as a stamp which wasn’t intended for such use.

My method of having a starter file, with some things including code pre-configured, back in v4 days has a lineage to the now built-in Code prototype and Sandbox group of system attributes. However, consider the option of creating a file for all you code snippets & coding notes and using that as a favourite TBX. The latter can then easily be opened, code copied out and then closed until next needed.

(George Wyner) #4

@mwra this is helpful. I agree that any effort like this would be at best imperfect and likely need tuning to the individual user or file to take into account use of $Text for code. thinking that it still might work to have, for example, a display-expression agent that gathers all items with non-null display expressions and a template to export the list of display expressions in a useful format. One key thing might be to avoid repeating any code inherited from a prototype. agree that it would be at best a limited and somewhat ad hoc effort.

(Mark Anderson) #5

Agreed, though in aggregate that’s actually fairly experienced user stuff and with quite a few moving parts (templates, queries, etc.). I know from my experience in this community that well-intentioned giving of such a structure to a less experienced user generally comes with a long tail as every tweak of not-yet-understood code causes new issues (and the support/help engendered). I don’t say that to insult anyone new to the app, but without some coding expertise, a lot of more complex aspects of the set-up isn’t obvious before the fact. I still think it’s a nice idea - for those who know how! :grinning:

As well as the code itself, consider context. Once you’ve 000s of notes, there’s scope for editing one note’s (inherited) rule and then forgetting which. So the learning point is using prototypes to hold/run code where possible and learning to be diligent on selecting the prototype before editing the code (I get the latter wrong to often!).

Looking back at how I gained confidence with the app over the years, most of my code-saving plans gathered dust* whereas putting more time into getting familiar with the action (and export) code syntax and methods has paid off. Plus, solving other folks code problems helps as it throws up genuine problems which one can try and learn from without a success/failure burden. Forums like this, and its predecessors, have driven much of the fine detail of aTbRef and most of the demos I post (tutorials and demos of theoretical scenarios are much more effort).

*Not least because what I generally forgot was to annotate the code somehow. Coming back to some useful code months/years later I found I generally wanted a slightly variant on the code so a copy/paste wasn’t a substitute for understanding what the parts of the code did. Plus, Action code continues to evolve often making some old complex code replaceable with a newer function. Knowing the how/why of the code functions is very useful and I’m very open to suggestions of improvements/omissions of that knowledge in aTbRef.

So a task like “I need to know which left-handed authors collaborated during the early 20C” might be more easily approached by thinking of it in functional terms. "I need a (sorted?) Set of notes (or List.unique) within a certain date range (years()?) filtered for a left-handedness (which attribute has that?). This approach makes the moving parts easier to comprehend and also helps spot if you don’t have good enough data. Thus you might $Tags with a value of “left-handed” but in some projects, it might make sense to have $IsLeftHanded (so the default value (false) is correct for most notes) or a $HandedNess (values: left, right, or ambidextrous). The example is deliberately simplistic and unreal but I hope the wider point is thus easier to see, we’re not now looking at sample code so much as the task the code needs to do.


(George Wyner) #6

I think the point about context is incredibly important. If ignored, a report of the kind I imagine would list the same code snippets for 000s of notes. One thing it could do instead, is report on which non-prototypes have code that doesn’t match the corresponding prototype, which would point to places where some refactoring might be needed.

Apropos of all this, I was tweaking an edict earlier today and noticed that I had “=” rather than “==” in the condition of an if statement. that is the kind of thing I want to clean up. the report is not a magic bullet and just looking at my code periodically in its many locations might be even better, but I still like the idea of collecting a lot of this in one place.

(Mark Anderson) #7

As it happens, hasLocalValue(), was added for just such a purpose (at some time in v6 if I recall).

You are right about == being correct for equivalency tests, but a confusing factor is that = is likely to continue to work due to support for old code that log term users won’t or don’t know how to re-write. If that seems odd, it should be borne in mind that equivalency was only used in query code (then separate to action code). Now that queries are written in Action code and queries can turn up in find()-based designators, writing a code test for correct +/== use could end up in some gnarly regex. As discussed, using prototypes means less code to check as long as you keep an eye out for rogue local values.