When I started to work as a junior developer ten months ago, my first tasks were mostly related to maintenance. As far as I know this is the usual way for newcomers to get familiar with software engineering processes in real customer projects. The most important thing I learnt during the maintenance tasks was that I learnt to value code readability. Code with high readability made my job easier and also helped me to focus on completing the tasks. I became quite passionate about code readability and I even did my bachelor’s thesis about refactoring.
I have studied computer science for three years. Every programming course I have attended highlighted the importance of properly commenting the code. More was better. However if we had a visiting lecturer from a software engineering company, he or she recommended to write our programs in such way that the comments would not be needed. My opinions are closer to the latter.
In my opinion there are few (too common) cases where ABAP comments decrease the code readability a lot even though the aim is exactly the opposite. I will describe three of those in more detail.
1. Rescuing unreadable code with comments
Comments are great tool for expressing complex logic in a more readable form. It is also useful for explaining why something is done. However the purpose is not to write the code in unreadable form and then comment it to get away with terrible code. I have experienced this far too often when maintaining ABAP programs. Of course commenting in this is case is far more better than leaving the unreadable code without explanation. Still the code should be written in such a way that we need as little comments as possible. To achieve this developers should use more descriptive variable and method names.
2. Commenting self explanatory code
Sometimes developers underestimate their code expressiveness. ABAP is relatively expressive language (in my opinion) and every simple statement does not need to be commented. For example the following is consider a good practice in some source:
“Separate the text value at comma into two different variables
SPLIT wa-address_field AT ‘,’ INTO lv_address lv_postal_code.
No comments needed. The line explains it’s behavior as well as (or even better than) the comment. A little bit modified but still not shining:
“The address field is separated into two variables for distinct processing
SPLIT wa-address_field AT ‘,’ INTO lv_address lv_postal_code.
I would still leave the comment out. Why would we separate the field if we did not want to process them separately in some point? Let the code explain itself.
3. Comments as change log
The last issue with commenting is its use as a change log. At first it seems nice way to tell the future readers what has changed and when. But after few modifications it makes the code unbearable to read. There starts to appear modifications inside modifications and even the smallest changes could include many, many rows of comments into the source code. Consider adding a new field as a select option for a report. Comment appears around the select-option declaration and within every query where it is used. The comments within queries are particularly annoying. To demonstrate this:
SELECT *
FROM dbtab
WHERE field EQ space
"Start of modification by username for changeid on dd.mm.yyyy
AND modified_field IN so_modified_field
"End of modification by username for changeid on dd.mm.yyyy
"Start of modification by otheruser for changeid2 on dd.mm.yyyy
AND new_field IN so_new_field.
"End of modification by otheruser for changeid2 on dd.mm.yyyy
They are not actually that rare. It is not elegant way at all when it comes to code readability. The problem with this issue is that there might not be an elegant way to document changes so that they are easily visible but do not decrease the readability of source code. Maybe I am after for some built in tool to easily browse the modification history. Of course there are functional and technical design documents but they are too far away when I need them. How do you document the change log inside SAP system?
I am eager to hear about other community members’ opinions about the best practices of commenting. Feel free to comment my comments about ABAP comments... This is my first blog post so give me feedback!
