C Traps and Pitfalls

Since I have retired from programming, I have started disposing of most of my programming books. When I picked up my copy of C Traps and Pitfalls by Andrew Koenig, I thought I should recommend this book to beginning programmers.  The author describes real mistakes made by programmers so you can learn how to avoid them.  On page 79 the author describes "side effects."  This book is worth your time.

Great Quote on Complexity

When I get rid of books I sometimes read parts of them again.  Because I don't think I will be doing much distributed programming in C++ in the future, I discarded an excellent book:  Distributed Application Programming in C++ by Randall A. Maddox.  There is a great quote at the back of the book, on page 429:  "A complex system that works is invariably found to have evolved from a simple system that worked.....  A complex system designed from scratch never works and cannot be patched up to make it work.  You have to start over, beginning with a working simple system."  Mr. Maddox attributes the quote to two people.  He says Gary Booch used the quote and that Booch attributed it to Systemantics: How Systems Work and Especially How They Fail by John Gall (1977).

This is true.  Even if a complex system is designed from scratch, it must be implemented incrementally, testing along the way, and changing the design as required to develop a working complex system.  Notice I said "develop" and not "evolve." It is a horrible misuse of language and of the theory of evolution to say that people evolve software.  People can write, code, design, implement, and develop software, but people do not evolve software.

Robert Canright

Systematics
https://www.amazon.com/Systemantics-Systems-Work-Especially-They/dp/0812906748/

An IDLE Shortcut After Installing Python

After installing the Python programming language you will want to create a short cut to the Idle program.  IDLE stands for Integrated Development and Learning Environment and is a very useful tool.  You can execute lines of Python code, segments of Python code, and entire Python programs with this tool.  Here is the desktop shortcut I use to launch Python IDLE. 

The Python installer will not create this for you, so I am explaining how to do it.
Go to this location  C:\Python27\Lib\idlelib\
Make a desktop shortcut to idle.bat
Right click on the new shortcut and select "Properties"
Change the icon with  the Change Icon button.
Browse to this location to find the icon   C:\Python27\Lib\idlelib\Icons\
Select idle.ico as the icon.  Yes, dot ico means icon, but your Windows explorer has to be set to show the dot ico.  Do that by clicking on the View menu in your Windows Explorer and checking the box that says "Filename extensions."  
Finally, right click on the desktop shortcut and select "Rename."
I changed the name to IDLE (Python). 
Double click on this shortcut and you get this GUI.

See how I used it to multiply two numbers together.  I use IDLE frequently as calculator.  Click on the File menu and you can open a Python source code program.

The program opens in a new window and has a Run menu.  The Python Idle GUI is the door way to a lot of useful functionality.

Robert

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