The Importance of Commenting Code

I recently read this article on commenting code: Is There a Correct Way to Comment Your Code? by Erik Dietrich.  The opinion that “clean code needs no comments” was mentioned.  No.  I disagree.  Comments are helpful.  If a software product is successful then it will be in use for many years.  Programmers unfamiliar with the old code will need to quickly find the spots in the code that need to be changed to fix problems or to add new features.  This activity is called "software maintenance."  Complex technical code is full of equations.  Complex equations are meaningless to programmers and comments are needed to explain the purpose and workings of the equations.  (Complex equations are usually provided to programmers by systems engineers or R&D scientists.)

Complex code can benefit from comments that provide a concise design description.  These design comments might be concentrated at the start of the software module, or they might be scattered among the methods within the software module.

The primary tool for software maintenance is the grep tool.  The least of comments is a keyword in the code that can be caught with grep.  For example, imagine you are ordered to modify Capability_101 in order to add  a new Capability_102 to the old code.  As a code maintainer you need the code that implements the old capability tagged with a comment that says "Capability_101" so the grep tool can find it.

To say well written code needs no comments is foolishness.

Robert

I have written about comments in code before:

Self Documenting Code and Ecclesiastes October 13, 2013

http://canrightonsoftwareandprogramming.blogspot.com/2013/10/self-documenting-code-and-ecclesiastes.html

Software Maintenance and Variables  March 16, 2014

http://canrightonsoftwareandprogramming.blogspot.com/2014/03/software-maintenance-and-variables.html

Interested in flight, aircraft, or physics?

JSBSim is an open source flight dynamics model (FDM) that compiles and runs under many operating systems, including Microsoft Windows, Apple Macintosh, Linux, IRIX, Cygwin (Unix on Windows), etc. The FDM is essentially the physics/math model that defines the movement of an aircraft, rocket, etc., under the forces and moments applied to it using the various control mechanisms and from the forces of nature. JSBSim has no native graphics. It can be run by itself as a standalone program, taking input from a script file and various vehicle configuration files. It can also be incorporated into a larger flight simulator implementation that includes a visual system.

http://jsbsim.sourceforge.net/

Robert

Free AI Code for Chess

Here is a link to an article from CodeProject, "Test Driven Chess Artificial Intelligence" by Kristian Ekman:  https://www.codeproject.com/Articles/1168892/Test-Driven-Chess-Artificial-Intelligence

From the article:  This is a fully functional yet simple chess program that aims to help you understand how a chess engine works. There are already open source chess engines on the Internet which focus on high performance. This is a standard object oriented C# solution that is meant to be easier to comprehend. The focus has not been to make a fast and high rated chess engine. I have developed a working chess AI that plays descent good moves with code that you hopefully like to read. A few of the more specific goals have been to correctly implement Alpha Beta Pruning and Zobrist Hashing using C# 6.

If you are interested in artificial intelligence or computer chess, you might enjoy this.

Robert

Why Learn Pascal?

I purchased a copy of Genetic Algorithms in Search, Optimization & Machine Learning by David E. Goldman (1989).  The book has sample code in Pascal.  This is where Free Pascal comes in.  When I coded last in Pascal it was with Turbo Pascal and I enjoyed it much more than coding in C.  (I mentioned Free Pascal back in December 22, 2012 in this post:  Learning to Program with Pascal.)

If you go to the Free Pascal website and look at their documentation you can see there is a great deal of documentation and that Free Pascal is now an object oriented language.  You can download a  copy of the language (free under the GNU General Public License).  My complaint against the Genetic Algorithms book by Goldman is not that pascal is used, but that there is no license.  I have looked at the book and there is no license that permits you to use the code.  So if I typed up the code and posted it online at Sourceforge or Git Hub I would be violating copyright law, so I cannot share the code.  And the code is not available online.  You have to type the code yourself.  There was an operating systems textbook for an OS called Xinu that had a statement from the author that the code could be used and I saw people use this OS professionally, typing the code from the book.

Criticisms against Pascal being old are misguided.  The Scheme programming language is old, but it is a great educational language.  The book Structure and Interpretation of Computer Programs by Harold Abelson et al is a great book to study.  The Scheme programming language is also free.

So do not hesitate to get the book Genetic Algorithms by Goldman because the code is in Pascal.  Pascal is a nice language worth knowing and Free Pascal can be used to run the code in the book.

Robert Canright

Comparing Files in Notepad++

A couple of years ago I posted an article about installing a Compare plugin for Notepad++.  The links I used in the past have died, so here is new information.

On my copy of Notepad++, I did Plugins > Compare > About and got the window I show above.  So you can go to Source Forge (https://sourceforge.net/) and search on "compare notepad plugin" and you will see you can download Compare Plugin 1.5.6.2.bin.zip (https://sourceforge.net/projects/npp-compare/?source=directory).  Also there is a Notepad++ web page (https://notepad-plus-plus.org/community/topic/11116/compare-plugin) that lets you download Compare Plugin 1.5.6.7.bin.zip

This website (http://docs.notepad-plus-plus.org/index.php?title=Plugin_Development#How_to_install_a_plugin) has these instructions on how to install a Notepad++ plugin:

How to install a plugin

The plugin (in the DLL form) should be placed in the \plugins subfolder of the Notepad++ Install Folder. Configuration files should go in \Plugins\Config. Documentation files should go to \Plugins\Doc\ directory.
These are generic instructions. If the plugin comes with some different procedure, that procedure should be followed instead.
Once you installed the plugin, you can use (and you may configure) it via the menu "Plugins".

KDiff3
The KDiff3 tool is a little better.  It compares directories as well. I am working a job now where the client provided me with a computer that had Notepad++ installed, but not KDiff3 and the client would not give me admin privileges to install KDiff3.  So I am using the Compare plugin for Notepad++ and I'm glad I have it.

Here's what it looks like (below).  Single-click on the image at it will enlarge.