How much “Comments” is too much?
All throughout my ABAP career in various organizations, I have come across many organization specific “Coding Standards Documents”. And all of those documents had couple of things in common – Whenever you are making a change to existing code, mark your changes with comments stating
*Begin of changes by Juwin Thomas on 5/27/2015 ECDK909909
*End of changes by Juwin Thomas on 5/27/2015 ECDK909909
And I kept on wondering isn’t this already handled by SAP’s Version management? After 10 changes done by 10 different people, the commented lines in the program becomes more than actual executable code. Who reads these anyways? I haven’t, I always go to version management, to see who did the changes, when and what was the change.
Another “Coding Standard” I have seen is – Do not delete any lines from the program, comment them instead. Isn’t this similar to having dead code inside the program?
Has anyone felt the same way? Or, are there anyone here, who think something good is going to happen with all these comments in the code?
One of the arguments that I have heard from people who likes comments – especially code reviewers 😈 – is that, in production system, where there are no program versions maintained (generally), it becomes easy to understand the changes if there are comments. My question to them – is it too hard to open the development system and see the versions? Or, if they like to see the versions in production system, activate versioning in that system during transport. Why degrade the code readability by putting in all these comments?
SAP standard programs have been around for decades and have gone to regular maintenance by different developers. But, I hardly see any such comments in any of the SAP standard programs. I haven’t worked at SAPLabs, so I don’t know if they have such a Coding standard. If they don’t, how do they manage their code reviewers?
Bored of writing these type of comments in my program, I developed a small utility program that I carry around with me, to different organizations. What I do is, whenever I have to do changes to an existing program, I write the code the way I want, without any change comments, and run it through my utility program when I am done. The utility program reads the current version and previous version of my changed program and inserts the comments wherever appropriate. 😎
But, I still keep wondering, why do we need this practice? 😕 I feel that there should be a “Comments Standard Documents” also, in addition to the “Coding Standards Documents”, to explain when & how to write comments.