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
Saturday, July 20, 2013
Python, Best Language for Beginners
Basic is a great language for teaching programming. The BASIC programming language
was created at Dartmouth College as a vehicle for teaching programming
to beginners. But when I look at projects at the GitHub website, you
will see that Python is on the list of most popular languages, but Basic
is not: https://github.com/languages
Based on features, Python is a good first language. Its style of coding is closer to that of Java than to C/C++, but it permits procedural programming while Java is strictly object oriented. Python's popularity together with its other strengths make it the best language for beginners.
I had previously recommended Basic as the best first language for beginners. How can you go wrong with Basic? Only if Python provides more practical opportunities. Kirk McDonald, president of PubMatic, an ad tech company in Manhatten, wrote an Op-Ed piece in the Wall Street Journal, May 10, 2013, titled, "Sorry College Grads, I Probably Won't Hire You." I'll quote him: "...please learn a little computer programming." He also said, "Dabble in a bit of Python." So the president of a tech company recommends Python, not Basic. (You can google the title and read the article online.)
I had previously recommended Python Programming for the Absolute Beginner by Michael Dawson. I continue to recommend it for beginners. You can go to the publisher's website and download the version of Python that is compatible with Python modules called Livewires and Pygame, which come with the Python installer used by the book. You can also download the source code from the book. This book is an excellent resource for the beginning programmer.
Robert
Here is an article with more explanation of why people like Python:
http://www.mihneadb.net/post/python-the-best-first-programming-language/
Here is another article saying Python is the best language for beginning programmers:
"Python squeezes out JavaScript, C as best starter programming language", January 23, 2014
http://www.itworld.com/application-management/401419/python-squeezes-out-javascript-c-best-starter-programming-language
Surprisingly, the C programming language was 2nd on the survey. I last mentioned C a a beginning language on April 13, 2013:
http://canrightonsoftwareandprogramming.blogspot.com/2013/04/the-c-programming-language.html
Additional blog posts:
Python GUIs with PyGTK and Glade February 26, 2014
July 9, 2014
"At the time of writing (July 2014), Python is currently the most popular language for teaching introductory computer science courses at top-ranked U.S. departments.
Specifically, eight of the top 10 CS departments (80%), and 27 of the top 39 (69%), teach Python in introductory CS0 or CS1 courses." This quote is from the following blog:
http://cacm.acm.org/blogs/blog-cacm/176450-python-is-now-the-most-popular-introductory-teaching-language-at-top-us-universities/fulltext
Based on features, Python is a good first language. Its style of coding is closer to that of Java than to C/C++, but it permits procedural programming while Java is strictly object oriented. Python's popularity together with its other strengths make it the best language for beginners.
I had previously recommended Basic as the best first language for beginners. How can you go wrong with Basic? Only if Python provides more practical opportunities. Kirk McDonald, president of PubMatic, an ad tech company in Manhatten, wrote an Op-Ed piece in the Wall Street Journal, May 10, 2013, titled, "Sorry College Grads, I Probably Won't Hire You." I'll quote him: "...please learn a little computer programming." He also said, "Dabble in a bit of Python." So the president of a tech company recommends Python, not Basic. (You can google the title and read the article online.)
I had previously recommended Python Programming for the Absolute Beginner by Michael Dawson. I continue to recommend it for beginners. You can go to the publisher's website and download the version of Python that is compatible with Python modules called Livewires and Pygame, which come with the Python installer used by the book. You can also download the source code from the book. This book is an excellent resource for the beginning programmer.
Robert
Here is an article with more explanation of why people like Python:
http://www.mihneadb.net/post/python-the-best-first-programming-language/
Here is another article saying Python is the best language for beginning programmers:
"Python squeezes out JavaScript, C as best starter programming language", January 23, 2014
http://www.itworld.com/application-management/401419/python-squeezes-out-javascript-c-best-starter-programming-language
Surprisingly, the C programming language was 2nd on the survey. I last mentioned C a a beginning language on April 13, 2013:
http://canrightonsoftwareandprogramming.blogspot.com/2013/04/the-c-programming-language.html
Additional blog posts:
Python GUIs with PyGTK and Glade February 26, 2014
July 9, 2014
"At the time of writing (July 2014), Python is currently the most popular language for teaching introductory computer science courses at top-ranked U.S. departments.
Specifically, eight of the top 10 CS departments (80%), and 27 of the top 39 (69%), teach Python in introductory CS0 or CS1 courses." This quote is from the following blog:
http://cacm.acm.org/blogs/blog-cacm/176450-python-is-now-the-most-popular-introductory-teaching-language-at-top-us-universities/fulltext
Sunday, June 30, 2013
Instructions for installing PyDev
Here are instructions for installing PyDev into the Eclipse IDE. This a link to a detailed set of instructions that include the installation of the Eclipse IDE, followed by the installation of the PyDev plug-in. This is a 35 page document. The Chrome web browser will open it, eventually. Mozilla might have trouble opening it (my copy of Mozilla proclaimed the file was damaged, but it was not). Microsoft Internet Explorer will eventually open the PDF file. It takes time because the file is large.
PyDev was developed by a company called Aptana. They have an IDE called Aptana Studio 3 that comes with Python loaded in it. This is another version of the Eclipse IDE. It will work just like Eclipse, if you are familiar with it. You do not need to add the PyDev perspective in Aptana Studio 3. The Web perspective will run Python code just fine. You do need to setup the Python interpreter. Refer to the instructions for installing Pydev to see how that is done. See the section, Configuring the IDE, pages 14 to 18.
IDE's are helpful for debugging code. It is great that you can use Eclipse with Python.
Robert
PyDev was developed by a company called Aptana. They have an IDE called Aptana Studio 3 that comes with Python loaded in it. This is another version of the Eclipse IDE. It will work just like Eclipse, if you are familiar with it. You do not need to add the PyDev perspective in Aptana Studio 3. The Web perspective will run Python code just fine. You do need to setup the Python interpreter. Refer to the instructions for installing Pydev to see how that is done. See the section, Configuring the IDE, pages 14 to 18.
IDE's are helpful for debugging code. It is great that you can use Eclipse with Python.
Robert
Friday, June 28, 2013
Dia - Simple and Free UML Drawing Tool
I mentioned ArgoUML in an earlier post. Now I'll mention Dia for UML diagrams. ArgoUML can generate code from the UML models. Tool Dia was inspired by Visio. Dia cannot generate code, but it is very easy to use. Its homepage is:
https://wiki.gnome.org/Dia
The Windows installer for Dia can be found here:
http://dia-installer.de/
Here is an example of a sequence diagram drawn with Dia, which calls them lifelines.
You can see the diagram is more sophisticated than what you would draw with PowerPoint. There is a drop-box in Dia where you select UML diagrams.
It is important to document your designs. You export your Dia diagram to a picture file in order to paste it into documents. I found Gimp useful for cropping pictures exported from ArgoUML. In Dia I draw a simple box, put my diagram inside the box, and the export to jpeg automatically crops the picture around the box I drew. That makes it easier than ArgoUML for making jpegs to paste into documentation.
Robert
Posts elsewhere about using Dia for UML:
UML Sequence Diagram in Dia?
http://stackoverflow.com/questions/3535717/uml-sequence-diagram-in-dia
How to lengthen lifeline of sequence diagram in Dia?
http://stackoverflow.com/questions/9955587/how-to-lengthen-lifeline-of-sequence-diagram-in-dia
Post about ArgoUML:
http://canrightonsoftwareandprogramming.blogspot.com/2013/06/argouml-free-uml-drawing-tool.html
https://wiki.gnome.org/Dia
The Windows installer for Dia can be found here:
http://dia-installer.de/
Here is an example of a sequence diagram drawn with Dia, which calls them lifelines.
You can see the diagram is more sophisticated than what you would draw with PowerPoint. There is a drop-box in Dia where you select UML diagrams.
It is important to document your designs. You export your Dia diagram to a picture file in order to paste it into documents. I found Gimp useful for cropping pictures exported from ArgoUML. In Dia I draw a simple box, put my diagram inside the box, and the export to jpeg automatically crops the picture around the box I drew. That makes it easier than ArgoUML for making jpegs to paste into documentation.
Robert
Posts elsewhere about using Dia for UML:
UML Sequence Diagram in Dia?
http://stackoverflow.com/questions/3535717/uml-sequence-diagram-in-dia
How to lengthen lifeline of sequence diagram in Dia?
http://stackoverflow.com/questions/9955587/how-to-lengthen-lifeline-of-sequence-diagram-in-dia
Post about ArgoUML:
http://canrightonsoftwareandprogramming.blogspot.com/2013/06/argouml-free-uml-drawing-tool.html
Saturday, June 22, 2013
ArgoUML - Free UML Drawing Tool
UML diagrams are vital for documenting code. I have used and I recommend the free diagramming tool called ArgoUML. I have used ArgoUML 0.34 for Windows. You can download it from here:
http://argouml.tigris.org/
ArgoUML does more than create diagrams for documentation. You have to export your diagram to a picture file to have pictures for documentation. Then you might have to crop your image. I use Gimp to crop pictures.. ArgoUML can generate code from your diagrams. It supports code generation for these programming languages: C++, C#, Java, PHP4, PHP5.
For large projects, or for professional projects, I recommend buying Sparx Systems Enterprise Architect. The last time I looked it was $135 for an individual license. Sparx Systems Enterprise Architect will generate C++ code for you from the class diagrams, which pays you back for the effort of creating detailed documentation. I have used this at a customer site and was very impressed. I highly recommend this professional tool.
Here is their website:
http://www.sparxsystems.com.au/
They are an Australian company.
Robert
http://argouml.tigris.org/
ArgoUML does more than create diagrams for documentation. You have to export your diagram to a picture file to have pictures for documentation. Then you might have to crop your image. I use Gimp to crop pictures.. ArgoUML can generate code from your diagrams. It supports code generation for these programming languages: C++, C#, Java, PHP4, PHP5.
For large projects, or for professional projects, I recommend buying Sparx Systems Enterprise Architect. The last time I looked it was $135 for an individual license. Sparx Systems Enterprise Architect will generate C++ code for you from the class diagrams, which pays you back for the effort of creating detailed documentation. I have used this at a customer site and was very impressed. I highly recommend this professional tool.
Here is their website:
http://www.sparxsystems.com.au/
They are an Australian company.
Robert
Subscribe to:
Posts (Atom)