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.
