Programming Languages Are Wordy
It sounds silly to say this, but computer programs are full of words. Thousands of them, hundreds of thousands of lines of them, maybe millions of them. And out of that myriad of words, we have to find the ones associated with our intended work (bug-fix or modify behavior). Out of all those words, the developer/maintaner must figure out what all the relevant pieces are and how they all fit together.
The task is similar to that proposed by my literature professor who once held up a dictionary and remarked, “The greatest novels ever written are contained in this book; you just have to find the right words and put them in the right order.”
Every developer agrees that programs should be well-structured, but what does that really mean? Does it mean that every method or structure should have one entry-point and one exit-point? Does it mean that every object is normalized and factored to the nth degree? Does it mean that every object or function or method is part of a library to maximize reuse and utilization?
One thing that well-structured programs don’t contain is a Table of Contents. The word or object that you’re looking for could be anywhere in the thousands of lines of code and there are no hints to where in the body of code it might be. Instead we have to try to find the “main” module (or starting point) and see what it calls and then see what those modules call and keep recursing thru the modules until we assemble the whole program in our heads so we can understand enough of the “program logic” to figure out where the word or object should be.
A typical technical repair manual will have, for example, chapters on different components of the system with separate sections for maintenance, repair, replacement and disposal that will all be listed in the Table of Contents. A user with a minimum of training can turn directly to the appropriate pages of the book and find the information that they need.
If our programs really were well-structured, they might have the equivalent of a Table of Contents that would define the basic structure and major operations/procedures of the program. Instead of working on files, the developer would expand the “chapters” in the Table of Contents until they reached the right section and then jumped right to the code that they needed.
Consider what it would be like to read “War and Peace” in digital form, but instead of it being displayed in the published sequence, it was listed paragraph by paragraph in the order that Tolstoy wrote it. Or alphabetical order by the first word in the paragraph.
Would we ever be able to finish reading the whole book? Would any two ever read the same story? Following the paragraph on page 132, one reader might assume that the next paragraph was on page 417 while another reader might think that the next paragraph was on page 738. Without being given the correct sequence, War and Peace would be meaningless. And yet we have no similar requirements in computer programs, except that the modules and objects have to be compiled in order of dependencies.
And what about comments? Most developers believe that programs should be “well documented,” but there is no agreement on what well-documented means. Should every object have a comment describing how the object is used and what it does? Should every method in the object have a comment that describes what that method does and how it should be used? Should every block of code in a method have a comment that describes what that block does? Or should developers just add comments on the hard parts or the confusing parts? Except which part is hard or confusing differs depending on the developer and their level of experience.
And comments visually interrupt the flow of the code. A nice big helpful comment smack dab in the middle of a block of code can interrupt the thinking of the developer as they scroll down past the comment. Not to mention that comments are time or repetition sensitive; the first few times a comment is viewed it can be helpful but then it just gets in the way. It’s too bad there isn’t some way to hide or shrink a comment based on how many times the section of code has been recently viewed.
Not to mention the time it takes to write good comments and the time it takes to maintain the comments. And what about comments that aren’t updated when the code is updated? Pity the developer who reads the out-of-date comments about a section of code. Do they trust the comments and skip over the code? Or do they always distrust the comments and only trust the code? If so, does having comments provide any help to other subsequent developers?
The point of all this is that we have been overrun by the sheer volume of words needed to write programs. More words is not necessarily better. Sometimes having other tools or techniques (for example, Engineering Drawings mentioned in the last blog) can reduce the sheer volume of words AND improve our understanding of the structure and functionality of an object or a program.