{"id":1018,"date":"2020-11-24T15:59:54","date_gmt":"2020-11-24T23:59:54","guid":{"rendered":"http:\/\/www.wirfs-brock.com\/allen\/?p=1018"},"modified":"2022-01-21T10:28:03","modified_gmt":"2022-01-21T18:28:03","slug":"software-diagrams-arent-always-correct-and-thats-ok","status":"publish","type":"post","link":"https:\/\/wirfs-brock.com\/allen\/posts\/1018","title":{"rendered":"Software Diagrams Aren&#8217;t Always Correct and That&#8217;s OK"},"content":{"rendered":"\n<figure class=\"wp-block-image size-large is-resized\"><a href=\"http:\/\/www.wirfs-brock.com\/allen\/wp-content\/uploads\/2020\/11\/figure-2-e1642789578228.png\"><img loading=\"lazy\" decoding=\"async\" src=\"http:\/\/www.wirfs-brock.com\/allen\/wp-content\/uploads\/2020\/11\/figure-2-e1642789578228-1024x504.png\" alt=\"\" class=\"wp-image-1146\" width=\"768\" height=\"378\" srcset=\"https:\/\/wirfs-brock.com\/allen\/wp-content\/uploads\/2020\/11\/figure-2-e1642789578228-1024x504.png 1024w, https:\/\/wirfs-brock.com\/allen\/wp-content\/uploads\/2020\/11\/figure-2-e1642789578228-300x148.png 300w, https:\/\/wirfs-brock.com\/allen\/wp-content\/uploads\/2020\/11\/figure-2-e1642789578228-768x378.png 768w, https:\/\/wirfs-brock.com\/allen\/wp-content\/uploads\/2020\/11\/figure-2-e1642789578228.png 1267w\" sizes=\"(max-width: 768px) 100vw, 768px\" \/><\/a><\/figure>\n\n\n\n<p>This morning I saw an interesting twitter thread:<\/p>\n\n\n\n<figure class=\"wp-block-embed is-type-rich is-provider-twitter wp-block-embed-twitter\"><div class=\"wp-block-embed__wrapper\">\n<blockquote class=\"twitter-tweet\" data-width=\"500\" data-dnt=\"true\"><p lang=\"en\" dir=\"ltr\">Sorry, this makes no sense. Most valuable architectural depictions are high-level and abstract and can&#39;t be auto-generated from code, for example; hence they&#39;re manually created.<\/p>&mdash; Andrei Pacurariu (@AndreiPacurariu) <a href=\"https:\/\/twitter.com\/AndreiPacurariu\/status\/1330848498732986370?ref_src=twsrc%5Etfw\">November 23, 2020<\/a><\/blockquote><script async src=\"https:\/\/platform.twitter.com\/widgets.js\" charset=\"utf-8\"><\/script>\n<\/div><\/figure>\n\n\n\n<p>Tudor is the driving-force behind <a rel=\"noreferrer noopener\" href=\"https:\/\/t.co\/yRa5VGXIY9\" target=\"_blank\">gtoolkit.com<\/a>, a modern and innovative programming environment that builds upon and extends classic Smalltalk development concepts.  Tudor is someone worth listening to, but his tweet was something that I really couldn&#8217;t agree with.  I found myself more in agreement with Andrei Pacurariu&#8217;s  reply.<\/p>\n\n\n\n<p>I started to tweet a response but quickly found that my thoughts were too complex to make a good tweet stream.  Instead, I wrote the following mini essay.<\/p>\n\n\n\n<hr class=\"wp-block-separator\"\/>\n\n\n\n<p>Concretely, software is just bits in electronic storage that control and\/or are manipulated by processors.&nbsp; Abstractions are the building blocks that enable humans to design and build complex software systems out of bits.&nbsp; Abstractions are products of out minds\u2014they allow us to assign meaning to clusters (some large, some small) of bits. They allow us to build software systems without thinking about billions of bits or how processors work.<\/p>\n\n\n\n<p>We manifest some useful and generally simple abstractions (instructions, statements, functions, classes, modules, etc.) as \u201ccode\u201d using other abstractions we call \u201clanguages.\u201d&nbsp; Languages give us a common vocabulary for us to communicate about those abstract building blocks and to produce the corresponding bits. &nbsp;There are many useful tools that can and should be created to help us understand the code-level operation of a system.<\/p>\n\n\n\n<p>But most systems we build today are too complex to be fully understood at the level of code. In designing them we must use higher-level abstractions to conceptualize, compose, and organize code. Abstract machines, frameworks, patterns, roles, stereotypes, heuristics, constraints, etc. are examples of such higher-level abstractions.<\/p>\n\n\n\n<p>The languages we commonly use provide few, if any, mechanisms for directly identifying&nbsp;such higher-level abstractions.&nbsp; These abstractions may manifest as naming or other coding conventions but recognizing them as such depends upon a pre-existing shared understanding between the writer and readers of the code.<\/p>\n\n\n\n<p>If such conventions have been adequately formalized and followed, a tool may be able to assist a human identify and display the usage of higher-level abstractions within a code base. But traditionally, such tools are&nbsp;rare&nbsp;and often unreliable.&nbsp; One problem is that abstractions can overlap. So we (or the tools) not only need to identify and classify abstractions but also identify the clustering and organization of abstractions. Sometimes this results in multiple views that can provide totally different conceptions of the operation of the code we are looking at.<\/p>\n\n\n\n<p>Software designers\/architects&nbsp;often use informal diagrams to capture their conceptualization of the structure and interactions of the higher-level abstractions of their designs. Such diagrams can serve as maps that help developers understand the territory of the code.&nbsp;<\/p>\n\n\n\n<p>But developers are often skeptical of such diagrams. Experience (and folklore) has taught them that design diagrams likely do not accurately reflect the actual state of a code base.&nbsp; So, how do we familiarize ourselves with a new software code base that we wish to modify or extend? Most commonly we just try to reverse engineer its architecture\/design by examining the code. We tell ourselves that the code provides the ground truth and that we or our tools can generate truthful design docs from the code because the code doesn\u2019t lie. When humans read code we can easily miss or misinterpret the higher-level abstractions that are lurking among and above the code. It\u2019s a real challenge to imagine a tool that can do better. <\/p>\n\n\n\n<p>Lacking design documents or even a good sense of a system&#8217;s overall design we then often make local code changes without correctly understanding the design context within which&nbsp;that code operates. Such local changes may \u201cwork\u201d to solve some immediate problem. But as they accumulate over long periods such changes erode the design integrity of the overall system. And they contribute to the invalidation of any pre-existing design documents and diagrams that may have at one point in time provided an accurate map of the system.&nbsp;<\/p>\n\n\n\n<p>We definitely need better tools for integrating higher-level system architecture\/design abstraction with code\u2014or at least for integrating documentation.&nbsp; But don\u2019t tell me that creating such documents are a waste of time or that any such documents should be ignored.&nbsp; I\u2019ve spent too many decades trying to guess how a complex program was intended to work by trying to use the code to get into the mind of the original designers and developers.&nbsp; Any design documentation is useful&nbsp;documentation. It will probably need to be verified&nbsp;against the current state of the code but even when the documents are no longer the truth they often provide insights that help our understanding of the system.&nbsp; When I asked <a href=\"http:\/\/www.wirfs-brock.com\/blog\">Rebecca Wirfs-Brock<\/a> to review this little essay, she had an experience to relate:<\/p>\n\n\n\n<blockquote class=\"wp-block-quote\"><p>I remember doing a code\/architecture review for a company that built software to perform high reliability backups\u2026and I was happy that the architectural documents were say 70% accurate as they gave me a good look into the mind of the architect who engineered these frameworks. And I didn\u2019t think it worthwhile to update it to reflect truth. As it was a snapshot in time. Sometimes updating may be worthwhile, but as in archeological digs, you\u2019ve gotta be careful about this.<\/p><\/blockquote>\n\n\n\n<p>Diagrams and other design documents probably won&#8217;t be up to date when somebody reads them in the future.  But that&#8217;s not an excuse to not create them.  If you care about the design integrity of you software system you need  to provide future developers (including yourself) a map of your abstract design as you currently know it.<\/p>\n\n\n\n<p><\/p>\n\n\n\n<p><\/p>\n\n\n\n<p><\/p>\n","protected":false},"excerpt":{"rendered":"<p>This morning I saw an interesting twitter thread: Tudor is the driving-force behind gtoolkit.com, a modern and innovative programming environment that builds upon and extends classic Smalltalk development concepts. Tudor is someone worth listening to, but his tweet was something that I really couldn&#8217;t agree with. I found myself more in agreement with Andrei Pacurariu&#8217;s [&hellip;]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"closed","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[76],"tags":[],"_links":{"self":[{"href":"https:\/\/wirfs-brock.com\/allen\/wp-json\/wp\/v2\/posts\/1018"}],"collection":[{"href":"https:\/\/wirfs-brock.com\/allen\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/wirfs-brock.com\/allen\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/wirfs-brock.com\/allen\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/wirfs-brock.com\/allen\/wp-json\/wp\/v2\/comments?post=1018"}],"version-history":[{"count":8,"href":"https:\/\/wirfs-brock.com\/allen\/wp-json\/wp\/v2\/posts\/1018\/revisions"}],"predecessor-version":[{"id":1147,"href":"https:\/\/wirfs-brock.com\/allen\/wp-json\/wp\/v2\/posts\/1018\/revisions\/1147"}],"wp:attachment":[{"href":"https:\/\/wirfs-brock.com\/allen\/wp-json\/wp\/v2\/media?parent=1018"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/wirfs-brock.com\/allen\/wp-json\/wp\/v2\/categories?post=1018"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/wirfs-brock.com\/allen\/wp-json\/wp\/v2\/tags?post=1018"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}