I'm not here to give a lesson on commenting code, rather I'm hoping to learn a thing or two. Comment at will!
Commenting code, oh all the things we have heard about this topic. No matter how many different thoughts or ideas there are on this subject, we can agree on a few main points.
Comments should explain what and/or why, not how.
Good comments don't excuse bad code.
Comments need to be brief but informative.
Utilizing the During method of commenting code must be for the experienced developer. The ability to maintain concentration effortlessly while breaking for only a moment to efficiently comment where needed is quite impressive. I get so focused on the task at hand, I'd worry breaking my concentration would cause me to lose my train of thought. This would be ideal to complete projects with as little backtracking as possible. The things I have to work on and look forward to!
Commenting After getting the function working is what I find works best. This makes me take that second look at my work before moving on. As being a newer programmer it is advantageous to self-review your work. You have to backtrack through your code, but you more than makeup for what you lose in efficiency. You often catch easy mistakes, redundant code, or errors that will lead to issues in the future.
The other day I decided to create a little program in Python to find prime numbers in a range with a user inputting the maximum. After getting it working I decided I better practice commenting as well. Redundant Code! Well, that was just the first thing I noticed and fixed. I also had forgotten to check the input value, negative numbers cannot be prime. This was accomplished by just commenting on my code using the After method.
primeList = []
numerator = 2
#loop through numerators to be checked
while numerator <= maxNum:
z = 0
#Redundant Code!
# if numerator % primeList[z] == 0:
# numerator+=1
# else:
# z+=1
#loop through prime factors
#should have iterated using for loop
while len(primeList) > z:
if numerator % primeList[z] == 0:
numerator+=1
break
else:
z+=1
#add prime factor to primeList
if z == len(primeList):
primeList.append(numerator)
numerator+=1
Finally, the Before method is more of creating an outline for your code in comments. Usually based on tech notes or steps you have come up with as they often contain the what or why. These can assist you in starting to create good comments. I can see this being an option as I progress on my journey. It will allow me to maintain focus and have a guide as I code. Now that we got the boring but necessary comments out of the way we can get to work! It will take some practice to be able to prewrite all necessary comments. So I can see where this style might need the help of one of the others to truly work.
Commenting our code can seem tedious and pointless, but it will help future developers. It will help the less experienced most, but may even be helpful to the original developer one day. Finding your style or combination of styles is key to success in reducing the dread of commenting. Feel free to let me know what works best for you or any tips or tricks you might have found along the way.
Top comments (0)