Tips and tricks for drafting cameleon clauses (and keeping them readable)

I’m wondering, are there any tips and tricks for keeping cameleon clauses readable?

Sometimes, complex clause become very difficult to maintain, especially if you come back to them later. You can start a new line (but without a blank line), but that doesn’t help in all cases.

Perhaps it’s useful to allow for internal clause comments bij starting a new line with //. If I’m not mistaken, you can already put text between % that is ignored?

Or another idea could be to highlight extend the use of the orange highlight based on where the cursor is placed. Now it’s possible to highlight the beginning and end of an condition in orange, but it would be useful if this would also work to only highlight the “true” condition by placing the cursor on “true” for instance.

Example:

image

I think that in the legal drafting world, we can learn a lot in this context from similar problems that programmers are faced with.

In programmer’s terms, this type of screenshot illustrates “spaghetti code”, that easily becomes too difficult to understand for a normal human being.

You are absolutely right that this becomes difficult to read. My most important advice would be to use internal snippets:

image

Programmers do something similar, where they “refactor” (= clean & improve) spaghetti code into manageable chunks, typically called “subroutines” or “modules"or " functions”.

Another principel of programmers is “DRY” or “don’t repeat yourself”. So if you notice that some snippets of text are repeated again and again — even if just a couple of words — it’s good for readability & manageability to refactor it into its own internal snippet. (Cf. the @ADDENDUM-OR-CONTRACT in your example).

1 Like

By the way, you can indeed use double slashes to comment:

image

That’s also a strong recommendation programmers try to live by. Because code typically gets written once, but then rewritten and re-read over and over and over again. Understanding how certain code works is then crucial, and a simple comment can really help?.

1 Like

Thanks, this helps. I like spaghetti, but not so much on the screen.

I refined it a bit more by also making use of external snippets and parameters so that I can reuse the same approach in other clauses:

image