I came across this interesting article by Paul Hardy yesterday and in one of his screenshots he's using a pretty cool header/signature for his methods.
METHOD method_name. ********************************************************************** * AS AN : * I NEED TO : * SO THAT : **********************************************************************
I'm a big fan of commenting your code (AND I agree that comments are no excuse for bad naming, so I do both comments and good naming). And I already knew that the WHY in comments is more important than the WHAT. But Paul's template really nails it.
Suppose we have a method as part of an HTTP request that's supposed a descriptive error in case of an 403 (access denied) error. Previously, I'd think about how to best explain the WHY and would have probably written something like this in the header:
METHOD write_body_for_status_403. ********************************************************************** * returns a descriptive body in case a 403 error occurs. this ensures * the user is not confused by the browser-generated 403 error page **********************************************************************
Now, with Pauls' template it's much less thinking and more concise:
METHOD write_body_for_status_403. ********************************************************************** * AS AN : end user * I NEED TO : see some context in case a 403 "Access Denied" * error occurs * SO THAT : I know how I can get access to the content **********************************************************************
Interestingly, this is the same approach agile methodology takes for user stories, but it never occurred to me that it would also make sense to use it when commenting code. Goes without saying that this can be applied to all programming languages, not just ABAP.