New suggestion: method header comment

[sap]

New suggestion: method header comment

[HrFlorianHoffmann]

I would actually discourage this kind of comment. 😄 There is a multitude of reasons for this that are also spread throughout https://github.com/SAP/styleguides/blob/master/clean-abap/CleanABAP.md#comments:

• These kinds of comments tend to outdate quickly and become misleading. If you change and rename the method to prepend_xs, will you remember to adjust the comment? Probably yes. But will you also remember it if you rename the method in an interface, and use auto-refactoring to adjust the class code? Or remember to adjust all occurrences if you rename a method that's used widely in a class hierarchy? Probably not. You will be left with methods that read prepend_xs but have a misleading comment Add Xs to a string inside - and this is only an obvious, mild example for the confusion that outdated comments can create.

• If you add these comments everywhere, the code gets bloated drastically. Your example already has 7 lines of comments for 6 lines of production code - a clear misbalance, in my eyes. What will it look like after refactoring number 18, when your comment starts filling out a whole page for a still tiny piece of code?

• Adding the history in such a prominent way suggests that the history is more important than what currently is. I think this is a misconception. The method should focus first and foremost on what it does. Only if need be should there be means to inspect what prior versions of the code did, and why that was changed.

• Commit messages describe a set of related changes in a single place. This is quite different from these comments, where the common idea behind the change will probably get lost between the many individual small comments.

• Most of the information in the comment can already be gleaned from the history of the object: the IDs of the transport requests, the dates (and even times) of change, and the users that released the changes. Transport requests also allow adding short texts that roughly describe the change.

• Writing this information consistently is a lot of work, and - at least knowing my colleagues 😄 - I am convinced some people or others will simply forget it or make mistakes (copy-paste, wrong date, typo in the change ID, ...) that make the comments questionable or even worthless.

Of course we should be able to produce the information you describe. But I think that attempting to fix this with comments instead of improving the version control itself is the wrong way.

[blahbap]

You bring up a lot of good points and I have experienced several of the problems you mention IRL.
Most of my colleagues seem to agree with you :)

Hopefully better code and tools will make the header comment unnecessary.
Thank you for for you comments, I will close the issue.

regards
Frank