Basically I always try my best to avoid comments whenever possible. I watched many videos from Uncle Bob and regarding the things he wants to express, there are many things I agree to.
He once mentioned that ideally speaking, whenever we tend to use comments to give more information on why we do things the way we are doing inside a certain function, then that is the point where we maybe should reflect on the quality of the code we actually have written.
Of course I know that the background of certain things in bigger systems can be really hard to explain just by the code itself without having any comments inside. But still I feel like that maybe I just don't know enough yet and certain things can indeed be expressed with the actual code itself (given I use right naming conventions etc.)
Here is a concrete example:
I am working on a Telegram Bot which needs to retrieve data from messages inside channels and then forwards to other components of the rest of the system. Due to restrictions in that project I am limited to do this by only using the Selenium Webdriver. Currently I am really having trouble with chosing the right naming convention.
I found that at the moment, I can check if there are urnead messages for a specific Telegram Channel by its clickable WebElement object. It has a string member variable "text" which contains 3 lines, given there is no unread message available. If there however are unread messages available, the member variable "text" will have 4 lines. The additional line in this case contains the number of unread messages.
So the last thing I would like to do is writing a function like this:
def isUnreadMessageAvailable(self):
if len(self.__buttonElement.text.splitlines()) <= 3:
return False
return True
What I certainly don't like in the first place is that hard coded "3" there. I may need to use that exact threshold in several other places inside other python files. Also this "3" may change at any time, so when adapting to a new value for the threshold, I obviously don't want to edit it in 100 diferent places.
Instead I'd rather use something like this:
def isUnreadMessageAvailable(self):
if len(self.__buttonElement.text.splitlines()) <= Constants.AMOUNT_OF_LINES_IF_MESSAGES_READ:
return False
return True
As you can see, the name of the variable I replaced the "3" with, is really long. I mean it contains six words. Recently I feel that I am struggling more with having good names for variables, files, and functions rather than writing the logic to get my program to do what I want it to do.
I apologize for this long question, but I can't come with a way to provide readability to the code without using a variable which contains less words in that case. Any opinion of your experiences are appreciated. Maybe some of your opinions/solutions can help me in the future when I face something similiar.
Your code is for three audiences:
Write your code so your future self can understand it.
The method you showed us has some assumptions baked into it. There's something special about your three lines, or two, or seven, or whatever in the future.
A method header comment is appropriate here, Uncle Bob nothwithstanding. It should explain what's special about three lines, and briefly say why or give a reference explaining why.
Long, explanatory, names are also helpful to your future self. One reason for that: they let you search all your code for references to them.
And, you can place a comment by the declaration of any named object to explain even further.
So use good declaration and method comments and meaningful symbols both.
Keep this in mind. It's twice as hard to debug your code as it is to write it. So if you employ all your cleverness writing it, you'll have a much harder time debugging it. Writing it for your future self helps cope with the difficulty of debugging.
Modern IDEs, editors, and runtimes don't penalize long names. IDEs show you declaration comments if you hover over names. The two work together nicely.