Comments about comments
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!
" Separate postcode out from address
SPLIT wa-address_field AT ‘,’ INTO lv_address lv_postal_code.
would be a reasonable comment. Comments should not say what the code is doing at a code level - that's what code does already very nicely.
Version management tells you everything you need to know about previous versions, so modification history in comments is doubly stupid.
I agree that your comment is more reasonable. However I don't think that it is necessary to comment it at all as the variable names should describe the purpose of the SPLIT statement. At least in this case.
The variables should be descriptive, that's true. However the comment I give explains the purpose of the code- it gives more information than just the code, and so does add value, even if that addition is small.
It's a subjective judgement call - mine's based on 25 years of commercial programming. 😏
In any case, I would use:
SPLIT address_field AT ‘,’ INTO address postal_code.
as I don't use type prefixing - which is a whole other discussion.
It surely is subjective and depends on how obvious the purpose is. That again depends on the context where the code is used. Sometimes the purpose may be harder to figure out without comments.
Thanks for pointing out the value of explicit purpose definition. That definitely adds more value than I may have thought before. And thanks for sharing your experience with a newcomer. 🙂
" Separate postcode out from address
SPLIT wa-address_field AT ‘,’ INTO lv_address lv_postal_code.
Assuming all you're trying to do is get the postal code.... The code above could easily become:
lv_postal_code = get_postal_code_from_address( lv_address ).
The rule of thumb that I use is that if you feel the need to write a comment you probably need a new method with a descriptive name. I very rarely write any comments.
Well yes.
I've written code in that style and on review been told "there's no comments". I've politely asked exactly what comment they would like. 🙂
Haha yeah that's a frustrating one... So I guess you'd write:
* Get the postal code from the address
lv_postal_code = get_postal_code_from_address( lv_address ).
😡
We are using Version management. Create a version when you begin to work and thats it. Relation to the change is given by an extarnal transport tool
By the way: i had a collegue in former times where we were writing code in assembler for the IBM mainframe. His code didnt had any comments, so i asked him to do that, After a couple of weeks he came back and presented his code with comments proudly. Instead of
LD A,3
he wrote
LD A,3 ; load register a with 3
😥
We also use comments as a change log, because you see the changes at first view without having to look at the versions. Actually, lots of changes can cause confusion quickly.
So, I "clean up" the comments from time to time and erase the older ones completely. In most cases, nobody is interested in a coding anyway which had been valid several years ago.
Besides, it is not necessary to document the history exactly for every line of code. A short remark for the reason of the change can be sufficient, too.
I strongly feel that the benefits of being able to see the changes at first view are massively outweighed by the unreadability it causes. Unreadable = unmaintainable = expensive = error prone. Such practices are completely forbidden on many projects.
Whereas a version comparsion clearly states what has been changed and where without any commenting. WHats the benefit of seeing this before? Mainly i'm not intereswted what was done before and why and by whom. Only if i need to complain as QA 😆
i use comments to say why i'm doing things and sometimes to say what i'm doing (if it's of a more complex nature and the code is not entirely self explanatory).
I never say how something is done
The example from above might look like
" we need the postcode for nanana
SPLIT wa-address_field AT ‘,’ INTO lv_address lv_postal_code.
I usually comment portions of my coding depicting why things are done the way they are done. I'm not only talking about technical stuff only here but also about functional things. Yes, this might mean I'm putting down redundant information with the requirements specification documentation (which is a neighborhood legend) and yes, it might make stuff less readable but I've experienced the lack of this very information in standard coding infuriates me the most.. so basically I try not to infuriate myself with my own coding.
Also, I tend to put down certain comments when I feel witty, because I can.
Rainer, you monster! D-:
Hello Miika,
congratulations on your first blog. I found your argumentation well presented. My special appreciation for mentioning that nobody aims at writing unreadable code.
I relate this discussion to the question: how should our program be structured? how can we better reason about our programs? and cite Barbara Liskov "modularization based on abstraction is the way things are done".
It is my view that no objective metric will separate unreadable and self explanatory code. I presume comments will sooner or later be obsolete. Either the code changes and comments do not or the developer evolves and "the code is obvious", so less comments are written.
Comments annoy me when they disrupt my perception of the abstraction behind the code I am trying to read. So comments will be less disruptive if they are clearly separated from the code. Others have shown how this could be achieved in your example. I would say that line does not deserve a comment and the developer can better reveal his intent by keeping the SPLIT statement in a cohesive block with a good name, e.g. method FORMAT_ADDRESS( ).
regards,
JNN