During the last summer I learned the hard way why it’s important to give your variables, functions and classes a meaning full name. I build a program (in python) that would eventually create a Excel file with a balance sheet and a profit and loss account. In the part of the program where everything is written to the Excel file I had the “amazing” idea to give my function and variable names shorted and non-descriptive names. The result:
def WSubFunc(self, x, lst, index, page): n = x e = 0 for item in self.r: if item in lst: page['A' + str(x)] = item page['C' + str(x)] = item e = x x += 1 if e == 0: return x else: if e != n: page['D' + str(x)] = "=SUM(C" + str(n) + ":C" + str(e) + ")" self.total[index].append('D' + str(x)) return x else: page['D' + str(x)] = "=C" + str(e) self.total[index].append('D' + str(x)) return x
Can you see what is does? From the code alone I can’t. There is a comment close by that is so non-descriptive that the only reason I know what it does because I made the comment. It creates the type of structure you see in the following picture bellow Particulars and Amount.
There is so much wrong with this code and the code in the rest of the project that if someone would ever want to extend the project, I would suggest a full rewrite. But besides that the application works and most of all it gave me a few very important insight in why I would name my variables, functions and classes with a meaningful name. The result is that I will keep myself from now on to the following rules:
- The name accurately describe what the class/function/variable does.
- No abbreviations allowed when there are no memory limitations.
- The only time I use a one letter variable is as a counter in a for-loop.
These rules should prevent the l’enfer c’est moi thought I get when I look it the code in this post.