Disclaimer: this is a rant.
Firstly, let's agree that comments in source code are important for maintainability and readability of the code. I've heard opinions that the comments are mostly useless because they get quickly out of sync with actual code and these out of sync comments cause confusions. Who updates comments when doing some bug fixing? Let say that we agree that there is a value in comments and one of our goals while programming is to write a readable and maintainable code.
The reason why I am writing this rant is that many developers do not know how to write a good comments and they cause damage with their useless comments. By damage here I mean lowering readability of code. At least to me it's important to see as much code as possible and useless comments are taking precious space.
Target Audience
Let's start slowly and answer an easy question. Who is target audience for the comments in source code? End users? Nope, they don't care. Project managers? Sadly, most of project managers in SAP world do not care about quality of code (let's not digress and talk about useless PMs :-)) but even good project managers are not going to read your comments. Functional consultants? Maybe, but most of them don't read source code. Developers? Yes, that's it (I said that it's an easy question). Hence an author of comment needs to optimize for the developers. By optimizing for developers I mean that the comments should provide some value and they should definitely not cause any damage.
Examples of Useless Comments
* Increase quantity by one
ADD 1 TO mseg-menge.
I know, this one is ridiculous but sadly I've seen this in real life. The purpose of comment should not be to document what code is doing. The code is pretty clear and exact in what it is doing. It should document why it was written. Remember, the target audience is the developers. They know how to read code and what ABAP command ADD means. Hence the comment above is completely useless and should not be there.
* Refresh screen
me->refresh_screen( ).
* Load data from DB
me->load_data( ).
In this example, the comments do not provide any additional info. The names of the methods should be descriptive. When I see a method with name REFRESH_SCREEN than I assume that it refreshes screen and I don't need to read it from comment. Hence above comments are useless. If names of your methods/routines/function modules are not descriptive than you have more serious problems and comments are not going to help.
* Create helper class
CREATE OBJECT wd_this->helper_class.
Here again, the comment above does not provide any additional info. I expect that variable with name helper_class holds a reference to an instance of helper class. Every developer knows (should know) what ABAP statement CREATE OBJECT does. If they don't not know than they should not be changing the code. The comment does not explain what helper class is or what it does. Hence the comment above is useless.
And now let's be more controversial.
* Begin of Change <AUTHOR> <DATE> <TRANSPORT>
* Remove old buggy code
* CLEAR mseg-menge.
mseg-menge = 1.
* End of Change
I really can't understand why somebody needs to write all these additional lines that significantly decrease the readability of code. Sadly, it's often mandated by development standards. Has anyone checked some big open source projects such as Linux kernel or FreeBSD? Can you see there comments like this one?
/* Begin of Change: dteske – Sat Sep 29 03:41:21 2012 revision 241042
Add missing IFS
f_clean_env --except RC_CONFS RC_DEFAULTS
*/
f_clean_env --except IFS RC_CONFS RC_DEFAULTS
/* End of Change: dteske */
No, you definitely can't see lines like this. The source code is not supposed to hold full history of changes and meta information about changes. All the information is stored in version control system. But wait a minute, ABAP AS has a version management where you can see who made the change and when it was made. You can also compare different versions to see what was changed. The SAP version management is far behind of new version control systems like Git but it's still better than polluting source code with senseless comments.
I know that I haven't shown you examples of good comments but rants are not usually helpful. I also believe that just eliminating useless comments will make the world better. So don't forget. Every time you write a useless comment a kitten dies.
