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