If your child is interested in computer programming, I have started this blog to assist you. This is why there are some articles on which is the best first language for a beginner. The slant is for beginners, but there is some information for programmers in general.
I will also share items of interest related to software.
Robert
Sunday, October 13, 2013
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
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
Saturday, October 12, 2013
Cost of Software Maintenance
Software maintenance is the dirty laundry of programming. Every programmer wants to write code. No one wants the mundane task of maintaining code. But if a product is going to survive in the market place, it must be used for an extended period of time and eventually need maintenance. Software maintenance includes expanding the functionality of a system to meet new requirements, so maintenance is more than fixing defects.
Changing a software system takes time, which costs money. Frequently, the staff making the changes was not present during the creation of the product, so changes are made by people with no knowledge of the system. Saying code is self-documenting is good for a laugh among mature programmers. (The difference between an experienced programmer and a mature programmer is that a mature programmer has learned from experience. It is astounding how many experienced programmers make amateurish mistakes because they have never learned from their experiences.) Lack of documentation is one of many factors that increase the cost of maintenance.
Canright's Costs of Software Maintenance
The Wages of Sin is Death
Code with poor maintainability features, after suffering many modifications by a changing parade of programmers, will turn into a Big Ball of Mud. You might want to read the original article: http://www.laputan.org/mud/. You might enjoy hearing a lecture on the topic (66 minutes) on YouTube: http://www.youtube.com/watch?v=h6Y9aJhqO78 by the author, Brian Foote. This video lasts an hour and it is worth your time.
If you enjoyed reading Thomas Pynchon's Gravity's Rainbow , William Faulkner's Absalom, Absalom! or James Joyce's Ulysses (three illogical, hard to read books), then you might enjoy software maintenance on a Big Ball of Mud. But most programmers suffer frustration when working on projects with hard to read code. At this point maintenance can break down.
The ultimate cost of unmaintainable software is the death of the software product. If you do not have replacement products, you can lose your customers and go out of business.
If you have developed a product that is so fragile, twisted, and unmaintainable that it is sure to die, then you need to unload it. You need to sell it to an unwise investor before the product implodes. Did you notice how many dot com acquisitions disappeared?
Robert
PS: I will elaborate on unloading your start up. Consider Douglas Crockford, the inventor of the JSON data format and founder of Electric Communities. Hundreds of millions of dollars were invested in this company. He sold out. Eventually the company went bankrupt and was sold for peanuts. He got out in time. You do not want to be the owner when the start up goes bankrupt!
List of Related Articles
Software Maintenance and Variables March 16, 2014
Software Maintenance and Message IDs April 2, 2014
Unique Method Names for SW Maintainability August 26, 2017
Avoid Bit Fields October 1, 2017
Changing a software system takes time, which costs money. Frequently, the staff making the changes was not present during the creation of the product, so changes are made by people with no knowledge of the system. Saying code is self-documenting is good for a laugh among mature programmers. (The difference between an experienced programmer and a mature programmer is that a mature programmer has learned from experience. It is astounding how many experienced programmers make amateurish mistakes because they have never learned from their experiences.) Lack of documentation is one of many factors that increase the cost of maintenance.
Canright's Costs of Software Maintenance
- Assume a basic quantum of maintenance cost, Q.
- If no documentation, add Q.
- If code is riddled with poor logic, add Q.
- If the project lacks debugging tools or features, add Q.
- If the code has no error handling, add Q.
- If good programming practices (for maintainability) are omitted, add Q.
The Wages of Sin is Death
Code with poor maintainability features, after suffering many modifications by a changing parade of programmers, will turn into a Big Ball of Mud. You might want to read the original article: http://www.laputan.org/mud/. You might enjoy hearing a lecture on the topic (66 minutes) on YouTube: http://www.youtube.com/watch?v=h6Y9aJhqO78 by the author, Brian Foote. This video lasts an hour and it is worth your time.
If you enjoyed reading Thomas Pynchon's Gravity's Rainbow , William Faulkner's Absalom, Absalom! or James Joyce's Ulysses (three illogical, hard to read books), then you might enjoy software maintenance on a Big Ball of Mud. But most programmers suffer frustration when working on projects with hard to read code. At this point maintenance can break down.
The ultimate cost of unmaintainable software is the death of the software product. If you do not have replacement products, you can lose your customers and go out of business.
If you have developed a product that is so fragile, twisted, and unmaintainable that it is sure to die, then you need to unload it. You need to sell it to an unwise investor before the product implodes. Did you notice how many dot com acquisitions disappeared?
Robert
PS: I will elaborate on unloading your start up. Consider Douglas Crockford, the inventor of the JSON data format and founder of Electric Communities. Hundreds of millions of dollars were invested in this company. He sold out. Eventually the company went bankrupt and was sold for peanuts. He got out in time. You do not want to be the owner when the start up goes bankrupt!
List of Related Articles
Software Maintenance and Variables March 16, 2014
Software Maintenance and Message IDs April 2, 2014
Unique Method Names for SW Maintainability August 26, 2017
Avoid Bit Fields October 1, 2017
Subscribe to:
Posts (Atom)