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