Oh boy, what happened?
Yesterday I sent an emotional tweet after reviewing a piece of (open source) code, which wasn’t documented well and didn’t include inline comments:
After that I turned away from Twitter, went to sleep, got up again, and had an awesome day with the family. Until I looked at my Twitter responses and mentions.
Here are some examples:
This discussion steered a wrong way and partly painted a wrong picture and wasn’t what I was after.
I WANT comments. I BELIEVE they are good and vital.
Just because some comments are unnecessary or wrong, doesn’t mean you shouldn’t comment at all.
The opposite is true: if you ever stumble across a wrong comment in some code, lets change it. Lets improve it. Lets fix it.
No matter how smart you think you are. No matter how “self explanatory” you think your genius code is. Comments are vital. Comments are there to explain the reasoning behind your (crappy?) code to OTHERS. They might not be as smart as you, they might not have the same information level as you.
Heck, for all we know they might not be #orclAPEX developers at all. I’ve seen Java guys (no offense) tempering with APEX applications. Mostly we see regular database developers, or former Forms developers diving into APEX. They need guidance and a bit more explanation of your “oh so smart code”.
Now get your personal feelings aside and do your job. Properly! And produce the most beautiful code, ever !
P.S.: I know, I know. Life is hard, there is no time. Nobody wants to pay you for extra time. But commenting your code is not extra time. Writing documentation about implementation details is not extra time. It is an essentialPART of software development.
If you are in a job that doesn’t give you the time to comment your code, think of a change.
Yes commenting intentions is vital.
Once I wrote a peace of code just checking if a character >= ‘A’ and <= 'C' .
An other developer wanted to change this part of code by some isalpha()-Check-Function from some libraray.
But in that case this would be wronge since this libranry regards the locale-language settings. But this peace of code was part oft some phone-nummer-checkimg which should accet also vaniaty-numbers.