![\"Quill\"](\"https:\/\/wp-media.patheos.com\/blogs\/sites\/384\/2014\/08\/medium_5999261134.jpg\")
<\/a> One of my regular goals as a software developer is the intentional reduction of cognitive load\u2014that is, I try to reduce the number of things I have to think about to get the job done. This applies to interfaces used by the customer, but it applies in spades to the interfaces used by the programmer: which is to say, APIs of the modules of code in the system, and the interfaces of the tools used during development.<\/p>\nIt\u2019s like this. A large software system is fiendishly, horrendously, amazingly, enormously, annoyingly complex. It is simply not possible, even if you\u2019re the only author, to keep all of the details in your head over a long period of time. (I\u2019ve been working on one project at work for almost ten years, and every so often I run across pieces of code that I know I must have written but that I have no memory of.) Consequently, I try to design my systems so that I don\u2019t need<\/em> to keep all of the details in mind.<\/p>\n Despite the title of this post, there are many tricks. The first is picking the right architecture. In this sense, your system\u2019s architecture is the way you split it up into pieces. Your architecture should be simple enough that you can keep it in mind; and then, when you\u2019re faced with a bug, or with a new feature to add, you can easily say, \u201cAha\u2014it has to be over here, in this part of the system.\u201d And then, once you dive into that part of the system it should have its own architecture as well that helps you navigate around in it; and so on.<\/p>\n The result is not unlike The Memory Palace of Matteo Ricci<\/a> Now me, my skills at envisioning such complex scenes in great visual detail are lacking; which is no doubt part of way I\u2019m not a Jesuit. But Ricci could do it, and I\u2019ve seen the same scheme described often enough that it must work for somebody.<\/p>\n In my case, I do it differently. I partition up the system, and remember the pieces; and I partition up the pieces; and so on. And there has to be a logic to the partitioning, because that logic means that I can find my way about, and keep the bits of complexity in different boxes. And that\u2019s key\u2014you only want to deal with one or two boxes at a time.<\/p>\n That\u2019s decreasing the cognitive load.<\/p>\n Another aspect is the careful design of code interfaces. Module A calls module B using module B\u2019s \u201capplication programming interface\u201d or API. (Module A and Module B are two of the boxes, and the API is where I drew the line between them.) Now APIs can be designed to make things easy for the caller; or they can be thrown together such that the caller has to do a lot of work understanding them each and every time he looks at them. You want to do the former.<\/p>\n Here\u2019s an example (some of you might to gloss over this, down to the bottom line). On most systems, the Tcl interpreter (or \u201cTcl Shell\u201d) is a program called tclsh<\/tt>. Quill<\/a> often calls the tclsh<\/tt> to do things: run tests, run the user\u2019s application, or any number of other things. Suppose I want to run a test script, That executes Well, now, that\u2019s ugly. I certainly don\u2019t want to have to do that everytime I want to use the tclsh<\/tt> to execute a script. So I added a command to add the appropriate extension to the program name, when running on Windows:<\/p>\n Since the logic to determine whether \u201c.exe\u201d is needed or not is in the But there\u2019s another problem. The The So this is better. But what if the Tcl shell cannot be found? Maybe we\u2019ve been given an explicit location to use, but the file isn\u2019t there, or perhaps none of our search mechanisms worked, and we found nothing. In that case, the above command will fail with an error; and we want it to be a useful error that makes the problem clear to the user.<\/p>\n So try this:<\/p>\n The Now, we usually need to set up some things before we invoke the Tcl shell. In particularly, we often need to set the TCL_LIB_PATH environment variable so that the Tcl shell can find the project\u2019s libraries. So we get this:<\/p>\n <\/p> When there\u2019s work that the caller of an API needs to do every single time, that\u2019s a sign that you\u2019re not providing the right API. Every time I call the Tcl shell in this way, I\u2019m going to need to do all of these things. Why don\u2019t I just define a proxy command that represents the Tcl shell program and handles all of this unpleasantness? Then my program can simply say,<\/p>\n The new Having to think about whether the Tcl shell executable is available, and how to find out, and what to do if it isn\u2019t, and setting it up properly, all of that places an enormous cognitive load on the programmer. The new And here\u2019s the bottom line.<\/b> That\u2019s really what the Quill<\/a> project is all about: reducing cognitive load. Quill automates common development tasks such that the user can rely on them without having to think about them too much. For example, I want to start work on a new project. There\u2019s a lot to put together to make that happen; but at the highest level, it\u2019s all pretty much the same as the previous project. So let\u2019s automate that:<\/p>\n Bang! I\u2019ve got a project tree that I know works just like my last project tree; all of the things I\u2019ve learned to do by reflex still apply, because everything is in the same place and follows the same standards.<\/p>\n ____ One of my regular goals as a software developer is the intentional reduction of cognitive load\u2014that is, I try to reduce the number of things I have to think about to get the job done. This applies to interfaces used by the customer, but it applies in spades to the interfaces used by the programmer: […]<\/p>\n","protected":false},"author":1131,"featured_media":0,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[530],"tags":[531,522],"class_list":["post-2752","post","type-post","status-publish","format-standard","hentry","category-software-development","tag-quill","tag-tcl"],"yoast_head":"\nmytest.test<\/code>. Tcl makes it really easy to call external programs, and so I might just do this:<\/p>\n exec tclsh mytest.test <\/pre>\n
mytest.test<\/code> as if I\u2019d entered tclsh mytest.test<\/code> at the system command line. And on many systems, it will work. On Windows, though, the Tcl shell is called tclsh.exe<\/code>. <\/p>\n\r\nif {[os flavor] eq \"windows\"} {\r\n set tclsh \"tclsh.exe\"\r\n} else {\r\n set tclsh \"tclsh\"\r\n}\r\n\r\nexec $tclsh mytest.test\r\n<\/pre>\n exec [os exename tclsh] mytest.test <\/pre>\n
os exename<\/code> command, the user doesn\u2019t need to think about it. <\/p>\nexec<\/code> command will search for the tclsh<\/code> program, but might not find it. Things would be smoother if we found the Tcl shell ourselves, and gave exec<\/code> its precise location. And then, we could search for the Tcl shell in a number of ways, or even read its location from a configuration file. So we get this:<\/p>\n exec [plat pathto tclsh] mytest.test <\/pre>\n
plat pathto<\/code> command not only looks for the tclsh<\/code>, who cares how, it also takes care of adding the \u201c.exe\u201d if its needed.<\/p>\n exec [plat pathto tclsh -required] mytest.test <\/pre>\n
-required<\/code> option tells plat pathto<\/code> to output a error message to the user when it cannot find the Tcl shell program, explaining that it cannot find it and what they might do about it.<\/p>\n\r\nset ::env(TCL_LIB_PATH) [project libpath]\r\nexec [plat pathto tclsh -required] mytest.test\r\n<\/pre>\n
tclshell mytest.test <\/pre>\n
tclshell<\/code> command looks up the path to the tclsh<\/code> program, taking the operating system into account, and displays a useful error if it cannot find it. But if it can, it sets the TCL_LIB_PATH environment variable, and executes the Tcl shell, passing its own arguments along, and returns the result.<\/p>\ntclshell<\/code> command, by contrast, \u201cdoes the right thing\u201d. It does what\u2019s wanted under the circumstances, and so the programmer no longer needs to think about it. It reduces the cognitive load\u2014which frees up mental resources for other things.<\/p>\n\r\n$ kite new app my-project myapp\r\n<\/pre>\n
\nphoto credit: campra<\/a> via photopin<\/a> cc<\/a><\/p>\n<\/body><\/html>\n","protected":false},"excerpt":{"rendered":"