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.
A few years ago it was deemed state-of-the-art to store any kind of extra resources (images, css/js-files) directly on the webserver.
Of course this was just the best-practice, left with many who were not able to follow because of company restrictions: no access to web server, not allowed to store files, too many regulations, and so on.
Luckily APEX 5++ gave us nicely working Static Application Files and Static Workspace Files. Now everyone is using those to store extra files.