Self Documenting Code and Ecclesiastes

In a previous article, Cost of Software Maintenance, I denigrated self-documenting code.  Because so many people believe in it, I should discuss it further.

Code changes, but documentation is usually not updated to keep pace with the code changes.  Documentation becomes increasingly outdated.  This is one reason given for skipping documentation.  Another reason is the lack of time or money when first writing the code.  Limited resources is a legitimate reason to minimize documentation.  Many believe that time-to-market is so important that documentation must be sacrificed.  Frankly, many programmers have trouble writing.  You do not see many English majors coding software.

Alexis Ohanian said in Without Their Permission that he and his partner worked day and night for a month to create a website that was "only slightly embarrassing."   He also said, "...if you are not a little embarrassed by what you launched, you waited too long.  It need only be good enough to be useful" (page 62).  He is not alone in saying this.  I remember hearing the president of Rogue Wave saying at a conference that if you spend too much time adding quality to your product, you will lose market share to a company that can get a less refined product out to market more quickly and take the market.

On the other hand, Crossing the Chasm by Geoffrey A. Moore describes the problem companies have of breaking out of the early-adopter ghetto.  When your product barely works and customers want a solid product, your growth is blocked.  Early adopters want the latest technology and they are willing to wait for quality to improve.  Lack of documentation can make it impossible to improve the product and expand your market share.  I saw one company try to out-source documentation of existing software to a company in Albania because the foreign programmers were cheaper.  It did not work.  Company growth was stymied because new staff took too long to decode the code and the outsourcing of documentation failed.

If use of self-documenting code will solve the documentation problem, then that would be great.  But what is self-documenting code?  The best approach is to use a documentation generator that creates HTML documentation from properly formatted comments.  Javadoc for Java and Pydoc for Python are examples.  The worst approach is number one on this list:  using meaningful names for variables and functions.  Meaningful names, with no comments, is very cheapest form of self-documenting code.  The following section explains how this breaks down.

Ecclesiastes

The book of Ecclesiastes says in 1:15, "What is twisted cannot be straightened; what is lacking cannot be counted."  The problem with meaningful names is that a number of programmers suffer from twisted logic and a faulty-world view.  Let me give you a real example, altered to protect the identities of those involved.

I was asked to modify Product X to issue new commands to hardware devices.  Only one device at a time was turned on and I needed to tell the code to find which device was turned on and then command it.  I found an undocumented function named getActiveDevice.  After I modified the code I went to the customer site to test it against the real devices.  The code changes did not work because the undocumented function getActiveDevice did not keep track of which device was  turned on (my interpretation of Active), but it kept track of which device had a display visible on the GUI.  (The GUI changed the devices that were visible depending on which tab was selected.)  The function should have been named getVisibleDevice.  The world-view of the previous programmer was not a view of the customer product, but a view of the programmer's GUI code.  The real world was not used as a point of reference by the previous programmer, so the variable names and function names were divorced from reality and were less than useless.

You cannot count on variable names or function names to tell you what is going on in the code if the coder used twisted logic or a faulty-world view.  If there is no documentation, and the code has no comments, and when you object you are told that the code is self-documenting, then they are "shining you on."  Documentation generators like Javadoc or Pydoc require comments.  If self-documented code is done properly,  there are meaningful comments in the code that document generators turn into HTML documents.  You cannot count on meaningful names alone to document the code.

Robert