Video Course on Python from The Great Courses

I'll bet there are free video resources for Python programming.  The Great Courses has very nice material so I will mention they have a course on Python programming. 

How to Program: Computer Science Concepts and Python Exercises
Course No. 9151
Professor John Keyser, Ph.D.
Texas A&M University

You need to be aware that the prices vary significantly  for courses from The Great Courses. Today's Wall Street Journal has an advertisement for this course.  Readers of the Journal can buy this course for $79.95 using the priority code in the advertisement.  Otherwise the non-sale price is $269.95 for this course on DVD.

Videos go on-sale at reduced prices.  You want to buy from The Great Courses from a catalog, an advertisement, or by checking their website for when items on-sale.

Robert

Avoid Bit Fields

Avoid bit fields

Here in the struct named MyData we see an example of poorly done bit fields and the bad design practice of pre-planned improvements.  The problem with MyData is that two of the variables have bit fields that cross 8-bit boundries.  The variables data3, data4, and data5 are jammed into 32 bits so 8 bits could be saved into a reserve variable for some future use.  I am writing this article because I worked on code like this that is over 20 years old, so the 8 bits in reserve sat unused all these decades.  Crossing 8 bit boundaries meant that data4 and data5 could not use the regular byte swap software like bswap_16(x) or bswap_32(x) (from /usr/include/byteswap.h)

struct MyData
{
    UINT8    data1;
    UINT8    reserve;
    UINT16    data2;
    UINT32    data3    :6;
    UINT32    data4    :12;
    UINT32    data5    :14;
};

See that data3 is 6 bits, which fits into a UINT8; data4 fits inside 16 bits, as does data5.  A better design is struct MyImprovedData, shown below.

struct MyImprovedData
{
    UINT8    data1;
    UINT8    data3;
    UINT16    data2;
    UINT16    data4;
    UINT16    data5;
};

Both structs are 8 bytes, but the second does not waste space with the unused "reserve" and also does not use bit fields that adversely impact portability and maintainability.  Let me emphasize this:  avoid bit fields to improve software maintainability.

A word about UINT8, UINT16, and UINT32.  These are typedefs for the C data types.

Writing Code that Isn't Needed

Page 24 of Code Simplicity: The Fundamentals of Software by Max Kanat-Alexander has a section entitled "Writing Code that Isn't Needed." If you try to write code anticipating future changes, you will be wrong and you will need to fix your incorrect design.  You might as well wait until you need to make the change and do it right.  This is similar to a design rule called YAGNI, "You ain't gonna need it."

Contorting struct MyData in order to set aside an 8 bit reserve field that was never needed is a flaw worth avoiding in your code.

I will go a step futher and suggest you avoid using bit fields if you can. Decades ago memory was a scarce resource. Today memory is a plentiful resource and programming manpower is the scarce resource.

Robert

What are BAMs?

BAMs stands for Binary Angular Measurements.  A BAM is an unsigned short data type which can store a value between 0 and 65,535.  BAMs are used to represent an angular measure; there are 65,535 BAMs per 360°.  An angle provided in BAMs can be converted to degrees by the following relationship:
Angle (Degrees) = (360 / 65,535) * Angle (BAMs)
I got this definition from this website:  
https://ssreng.com/what-are-bams/
However, you can change this a bit to get a floating point number:
Angle (Degrees) = (360.0 / 65,535) * Angle (BAMs)
Just make it 360.0 or in C cast the 360 to a float.

The reason for BAMs, in my opinion, is to store an angle as an unsigned integer.  You can store the angle in a C struct, you can write the struct to a file on disk or tape, or you can send the data through TCP/IP.  Do not think about storing data as floating point or sending floating point through the network.

Consider how you send data through TCP/IP:  you use functions to set the numbers to network byte-order (big endian). Look at this webpage:  https://linux.die.net/man/3/htobe32.  Functions are used to convert from host (computer) to network byte order. See these functions in /usr/include/endian.h
uint32_t htobe32(uint32_t host_32bits);
uint32_t htole32(uint32_t host_32bits);
uint32_t be32toh(uint32_t big_endian_32bits);
uint32_t le32toh(uint32_t little_endian_32bits);

All of these functions work on unsigned integers.  These functions will not work with floating point numbers.  You definitely use unsigned integers for BAMs, and you can actually do your calculations with scaled integers.  Some people think the calculations are faster with integer operations instead of floating point operations, as mentioned in this article on binary scaling:  https://en.wikipedia.org/wiki/Binary_scaling

The point I am stressing is the need to store and transmit data as integers.  BAMs are a way to scale an angle in the range 0 to 360 degrees to an integer.  You can always display an angle as a floating point like 24.8 degrees, but you do not store or transmit it as 24.8.

Robert

List of Articles on Software Maintenance and Maintainability

Here is a list of articles on Software Maintenance and Maintainability within this blog:

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 

Unique Method Names for SW Maintainability

Someone's code was broken.  I looked at it and decided that the code was probably breaking before or after the invocation of method initService within a C++ class.  So I grepped the code base looking for initService and I found it was used in over 200 places.  I grepped on "::initService" and found many classes used a method with the same name.  I quit looking because this was too much trouble.  I let someone else fix that problem.  I am very tired of poorly named methods and functions.  I have been coding for a long time and bad names are a perennial problem, so I propose a design guideline for you.  I will name this guideline: "Canright's rule for unique method and function names."

A design guideline for software maintainability:  Each class shall have unique names for its methods.  A suffix unique to that class shall be attached to the name of every method within that class.  When inheritance is used, the unique suffix belongs to the base class and all classes derived from that base need to use the same suffix to maintain polymorphism.

Here is an example:  class Thing1 would have  initServiceAA, class Thing2 would have  initServiceAB, class Thing26 would have  initServiceAZ, and class Thing27 would have  initServiceBA.  This means that when you grep for initServiceAZ you would find only the initService method defined for class Thing26.  Every method of class Thing26 would have "AZ" added to the end of the method name.  In C++ functions for a class are called methods.  With 2 alphabet characters you can have 676 suffixes.  Three alpha characters would give you 26 * 26 * 26 = 17576 suffixes.

In C programming you could attach a suffix like AA or BZ to every function within a C file.  This would make function names unique.  You need unique function/method names to search through collections of software files when you are trouble-shooting someone else's code.

Below is a Python program that writes a file called suffix_list.txt that begins with the line
AA=next_class
and then increments these letters until the file ends with this line
ZZ=
I license this program,  suffix_list.py, to you with the MIT license.

The idea is this, when you start coding a class you register your class in the suffix_list.txt file by replacing "next_class" with your file name, then putting "next_class" into the line below the line where you added your class name.  You could write another Python program that takes your class name as an argument, modifies the suffix_list.txt file for you, and reports back to you the suffix you are to use on your class method names.

If you manage a group of programmers, you should force them to write maintainable software.  Unique method or function names improve software maintainability.  I am giving you a free program to generate a list of suffixes; I hope you use it.  Also, here is a list of articles on Software Maintenance and Maintainability within this blog.

Robert

#program name = suffix_list.py
print("suffix_list.py ran")
fp = open("suffix_list.txt", "w")
idx_i = 0
idx_j = 1
alpha1 = 'A'
alpha2 = 'A'
str1 = alpha1 + alpha2 + "=" + "next_class"
print(str1)
fp.write(str1 + "\n")
while (idx_i < 26):
    while (idx_j < 26):
        str2 = chr(ord(alpha1) + idx_i) + chr(ord(alpha2) + idx_j) + '='
        print(str2)
        fp.write(str2 + "\n")
        idx_j += 1
    idx_j = 0
    idx_i += 1
fp.close()

Copyright 2017 Robert Canright
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Making Private the Default Constructor

In C++ you should make private the default constructor, copy constructor, and operator=.

Prevent application code from using any special functions supported automatically by the C++ compiler but not supported specifically by a class.  Make private within a class any of these special functions if you do not plan to use them within the application code and you do not define them:

1. default constructor, 
2. copy constructor, and 
3. assignment operator.  

Declare them private in the dot h file if you do not define them. Here is an example.

class A {

public:

                A( int n);  // specialized constructor

                int getNum( );  // “getter” function

private:

                int i_;

                A( );     // default constructor made private (disabled)

                A( A& ); // copy constructor made private (disabled)

                A& operator=(const A&);  // assignment operator made private (disabled)

};

You might be surprised when you make them private that inaccurate coding might throw a compiler error saying you have just tried to use a private function.   There are times you invoke them in your code without intending to invoke them.  The compiler will invoke a "factory supplied" version of these functions if you invoke them without defining them.

I just reviewed someone's code and noticed he did not do this.   

Robert

gcc versus g++

Use gcc for C code
Use g++ for C++ code.
If you have Linux or use Cygwin you will have the GNU Compiler Collection, which provides both gcc and g++.  Traditionally, C programs end in dot c and C++ programs end in dot cc or dot cpp.

Some simple C++ code might compile with gcc, but eventually you will get linker errors like this:
undefined reference to ‘__gxx-personality_v0’
collect2: error: ld returned 1 exit status

If you use g++ and still get this error, try
g++ file.cc -lstdc++
because your compiler is having trouble seeing some C++ Standard Library functions
per
https://stackoverflow.com/questions/6045809/link-error-undefined-reference-to-gxx-personality-v0-and-g

I was glancing at a book on C that mentioned gcc, but did not mention g++, so I thought I should mention this to you if you are starting out as a beginning programmer.

Robert

Making a Unique File name

I overheard one fellow asking another fellow for help in creating unique file names.  He wanted a base name with a random number attached at the end.  This happens when you are doing logging and you do not want to over-write the old file or have to delete the old file before you create a new one.  Well, you do not need a random number generator.  You can just add a number to the file name that is different each time you run the program that generates the log file.  Imagine running a test program several times during a day and you want to harvest all the log files.

Below is a small program that generates files with names like this:
test_file_27023.txt
test_file_27026.txt
test_file_27029.txt
test_file_27032.txt
test_file_27035.txt

Epoch time in C is the total number of seconds elapsed since 00:00 hours, Jan 1, 1970 UTC (Greenwich mean time).  With 5 digits the numbers will not "roll over" until after 100,000 seconds, meaning 27.7 hours.   The randomness comes from running the logging program at different times.  Usually after 8 hours of testing you harvest the log files for study and clear out the old files.

The simple program in C that has this output follow.  You can copy and paste this code and run it to test it.  You can incorporate the ideas from this code into your own code when you write a file that will be written repeatedly during the day.  This gives you multiple copies of the file, which is important when the output to the file is changing from iteration to iteration.  I hope you find this helpful.  I license this code to you free of charge via the MIT license, which appears at the very end.

Robert
-----------------------------------------------
#include <stdio.h>
#include <string.h>
#include <time.h>
#include <unistd.h> // sleep()

// compile with gcc file_unique_id.c -o file_unique_id

int main ()
{
  char* base_name = "test_file";
  char* extention = ".txt";
  // these string lengths are arbitrary
  char  long_string[200]; // holds file name
  char  short_string[100];// hold time in a string
  FILE* fd;
  int   chopped_time;
  time_t test_time;
  int index;
  for (index = 0 ; index < 5; ++index)
  {
    test_time = time(0); // get epoch time
    chopped_time = (test_time % 100000);  // keep the smallest 5 digits
    // add those 5 digits to the base file name
    sprintf(long_string, "test_file_%d", chopped_time);
    // add the file extension
    // long_string is now the file name with a unique 5 digit number
    strcat(long_string, extention);
    // short_string holds the full epoch time value
    sprintf(short_string, "%d\n", test_time);
    // log short_string to file whose name is in long_string
    fd = fopen(long_string, "w");
    fwrite(short_string, strlen(short_string), 1, fd);
    fclose(fd);
    sleep(3);
  }
  return 0;
}

/**
 * Sample outputs of this program
./file_unique_id
test_file_27023.txt
test_file_27026.txt
test_file_27029.txt
test_file_27032.txt
test_file_27035.txt

cat test_file_27023.txt
1503027023
**/
Copyright 2017 Robert Canright
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

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.

Free Computer Science Math Book

You can download in PDF a free copy of a book on Mathematics for Computer Science.  The book is Mathematics for Computer Science by Eric Lehman, F Thomson Leighton, and Albert R Meyer.

https://courses.csail.mit.edu/6.042/spring17/mcs.pdf

The book is almost a thousand pages long and it is not a cream-puff.   Leighton is with MIT.  It is used with this free on-line course: https://ocw.mit.edu/courses/electrical-engineering-and-computer-science/6-042j-mathematics-for-computer-science-fall-2010/index.htm

Some computer science work is very mathematical.  Look at the book Communicating Sequential Processes by C. A. R. Hoare.  It is very mathematical.  This is a book and topic that you might want to at least glance at so you can see another way to look at parallel processing.
Here is the book in PDF:  http://www.usingcsp.com/cspbook.pdf

Here is a Wikipedia article on Communicating Sequential Processes and another article on Tony Hoare.

Software is pretty cool.  Enjoy your reading!

Robert

C++ is Alive and Well

You might think that the C++ language, which has been around for many years, is an obsolete dinosaur.  If so, you would be wrong because C++ is very much alive and well.  Bjarne Stroustrup, the creator of C++, is a Managing Director in the Technology Division of Morgan Stanley.  Companies are still writing code in C++.  Here are a couple of open source C++ projects that are current.

Apache ActiveMQ C++ 3.9.3

IBM created the software called MQ (short for message queue).  Then IBM embedded MQ into their WebSphere product.  Now the open source community has created Apache ActiveMQ-CPP 3.9.3, which runs under the  Apache License v2.0 license.  Apache ActiveMQ runs on Red Hat Linux.

 Armadillo (C++ library)

Armadillo is a linear algebra software library for the C++ programming language. It aims to provide efficient and streamlined base calculations, while at the same time having a straightforward and easy-to-use interface. Its intended target users are scientists and engineers.  The Armadillo was last updated (version 7.800.0) February 17, 2017, which is just last month, so this is software that is very much in use.  Armadillo is open source software, so you can down-load it, study it, and use it.

C++ at Texas A&M

Programming: Principles and Practice Using C++ (2nd Edition) by Bjarne Stroustrup was developed at Texas A&M.

If you are interested in C++ programming, then you have an interest in a language still very much in use.

Robert

My Python Will Not Take a Command Line Argument

I had trouble getting my Python script to take a command line argument inside a subprocess.Popen call.   I do not mean that I had trouble with something like "python my_script.py arg".  No.  Here is what was failing for me:

import subprocess
proc = subprocess.Popen(‘executable_file.bin arg’)
proc.communicate()

What I got was "file not found" errors.  The Popen call could not recognize the argument as an argument.  It thought it was part of the file name.

I could run the command from a command line in a terminal.
executable_file.bin arg
worked in a command line.  Well, there is a way to make Popen work like a command line in a terminal/shell.  This is what works.

 subprocess.Popen(‘executable_file.bin arg’, shell=True)

The “shell=True” makes ‘executable_file.bin arg’work like it would in a terminal shell.

Robert