When did people forget to comment?
So ever since I took my first academic programming classes back in `05 at UW, CSE 142 / 143 with Stuart Reges, I’ve always been trained to write comments religiously as the difference between
public void addTwoNumbers(int first, int two) {
return first + second;
}and
/**
* A function which adds two numbers
* @param {int} first the first number to add
* @param {int} second the second number to add
* @return {int} first and second added
*/
public void addTwoNumbers(int first, int two) {
return first + second;
}
was the difference whether or not I’d get a B or A for a semester (yes comments for code were worth 10% of your homework assignments as they were considered style points). However, my religious style of commenting seemed to be an aberration once I left academic life for industry.
Working at several companies, well maybe more than several companies (too many to be willing to share publicly), has taught me to expect extremely poorly commented code which corresponds basically to 0 documentation of how a piece of code works. I’ve seen code like the following run in a live production system before.
private RectF getRect() {
if (mRectF == null) {
int index = mStrokeWidth / 2;
mRectF = new RectF(index, index, getSize() — index, getSize() — index);
}
return mRectF;
}First of all, what the heck is RectF? Also what’s mStokeWidth? This would make any developer mad as they have to basically run the code live and debug and flow through this particular piece of code to see what each variable contains and what the function may or may not do. This simply could of been avoided, rather the waste of time debugging, if the original developer just wrote what it did.
Now all of this makes me wonder, when did people forget to comment? Is it because there’s no incentive to comment? Is it because there’s no immediate penalty not to? Or is it because saves that person a couple minutes of time? Regardless, what the person neglects to think about is the person after them that might have to change what they written. More likely than not that person will not know what the original person was thinking about and ending up wasting more time figuring out the original person’s code than it would of taken to spend a few minutes writing a couple of comments and some documentation. This also doesn’t include the possibility wasted time due to a production outage due to a change in old code where it wasn’t understood correctly.
So as a developer, please spend the extra time to document your code! You’ve already spent hours typing up an amazing piece of code, why not spend a couple more minutes spent writing some comments and documentation so save time debugging and understanding your code in the future?
