Do your write code only for machines, or also for your fellow developers and curious functional consultants?
I believe that readability of program code is an important long-term aspect. I try to have it as a big priority and I'm constantly trying to improve my ability to use naming and composition to make the code as self-explanatory as possible. Comments still have their place though, but should not be what the code is based upon.
The online Clean ABAP style guides has a good section on comments, as does the new Clean ABAP book.
I recommend both those sources with all my heart, but let me elaborate here as well how we can write code for humans and machines at the same time...
So if we take for one aspect the naming of things in our code, like variables, classes, methods, etc. We define a very simple 2 grade scale grading how well the naming explains the thing, from 'Nope' to 'Very much so'.
For another aspect, we take the degree to which comments are used to explain the coding. Again with the same 2 grade scale.
Let's put this in four quadrants for a simplified world.
Let's get to it then...
First example is really really common - no comments and no good naming. Probably work ok right when you type it but even after a week, you yourself might not have a clue what your were up to:
Hey, I made this up myself and I'm not sure I get it... 😄
All right, so clearly we need to improve on that one... Lets add comments to explain the code:
Now, finding this code 6 months later, at least we know where to look for maintenance and what it's supposed to do... It's much better...
But are we there yet? No, there are still better ways in my subjective opinion...
Now, if we instead fix it up a bit and rename our variables, objects and methods...
Now the naming is explaining the code and the comments are explaining the code. Ok, all good? Twice as good? Well. Yes but no. Since the coding basically says the same thing as the comments now, we need to read the same thing twice... And it also has to be written twice... And changed twice when making adjustments or adding features...
And what if the comment and the code is not saying the same thing? Do we trust the comment or the code?
Let's carry on to the final one and my personal favorite...
Ah! The cleanliness. Quick to read. Quick to get an overview. Understandable code.
Just as Jules is trying real hard to be the shepherd in Pulp Fiction, I try real hard to write this kind of code. I'm not where I want to be yet, but I'm trying real hard...
Well no. First, there are a couple of important prerequisites for this... One prerequisite is a good composition of the code, the division of code into clearly defined and scoped classes and methods. If your code is 1500 lines in a procedural style, then naming things well certainly help, but you still risk getting lost anyway.
And a prerequisite to do that well is to use ABAP OO, which we all should whenever possible!
Another is context. I mean in the above example there are still many things we can't say other than that this code is supposed to be prioritizing and executing. Hopefully it's clear from the context where the code is located what an assignment is and what kind of tasks we're talking about, for instance.
Comments are still a very good way to explain WHY something is done in a certain way, that might not be obvious... Something like this, for example:
(It's funny how the styling of the code blocks here are syntax highlighting inside the comments...)
Now, if only the reality was this simple... 🙂
Stay safe everybody and let's hope to understand each others code...
Addition: To keep reading on this topic in the SAP Community, I recommend continuing with I See Dead Code after getting the extra value from the comments below.
I believe that readability of program code is an important long-term aspect. I try to have it as a big priority and I'm constantly trying to improve my ability to use naming and composition to make the code as self-explanatory as possible. Comments still have their place though, but should not be what the code is based upon.
The online Clean ABAP style guides has a good section on comments, as does the new Clean ABAP book.
I recommend both those sources with all my heart, but let me elaborate here as well how we can write code for humans and machines at the same time...
Four quadrants of code and comments
So if we take for one aspect the naming of things in our code, like variables, classes, methods, etc. We define a very simple 2 grade scale grading how well the naming explains the thing, from 'Nope' to 'Very much so'.
For another aspect, we take the degree to which comments are used to explain the coding. Again with the same 2 grade scale.
Let's put this in four quadrants for a simplified world.
Four quadrants of code and comments
Let's get to it then...
1. Nope - Nope
First example is really really common - no comments and no good naming. Probably work ok right when you type it but even after a week, you yourself might not have a clue what your were up to:
lr_tma = go_asmnt->todo( ).
ln_pt = 2.
lr_tma->find_impnt( ln_pt ).
WHILE NOT lr_tma->complete( ln_pt ).
go_asmnt->fn_main( lr_tma ).
ENDWHILE.Hey, I made this up myself and I'm not sure I get it... 😄
2. Very much so - Nope
All right, so clearly we need to improve on that one... Lets add comments to explain the code:
" Get pending tasks for assignment
lr_tma = go_asmnt->todo( ).
" Sort the tasks in order of priority (sort type = 2)
ln_pt = 2.
lr_tma->find_impnt( ln_pt ).
" Execute all of the tasks, one at a time, in order
WHILE NOT lr_tma->complete( ln_pt ).
" Execute
go_asmnt->fn_main( lr_tma ).
ENDWHILE.Now, finding this code 6 months later, at least we know where to look for maintenance and what it's supposed to do... It's much better...
But are we there yet? No, there are still better ways in my subjective opinion...
3. Very much so - Very much so
Now, if we instead fix it up a bit and rename our variables, objects and methods...
" Get pending tasks for assignments
tasks = assignments->get_pending_tasks( ).
" Sort the tasks in order of priority
tasks->sort_by_priority( ).
" Execute all of the tasks, one at a time, in order
WHILE NOT tasks->is_empty( ).
" Execute
assignments->execute_next( tasks ).
ENDWHILE.Now the naming is explaining the code and the comments are explaining the code. Ok, all good? Twice as good? Well. Yes but no. Since the coding basically says the same thing as the comments now, we need to read the same thing twice... And it also has to be written twice... And changed twice when making adjustments or adding features...
And what if the comment and the code is not saying the same thing? Do we trust the comment or the code?
Let's carry on to the final one and my personal favorite...
4. Nope - Very much so
tasks = assignments->get_pending_tasks( ).
tasks->sort_by_priority( ).
WHILE NOT tasks->is_empty( ).
assignments->execute_next( tasks ).
ENDWHILE.Ah! The cleanliness. Quick to read. Quick to get an overview. Understandable code.
Just as Jules is trying real hard to be the shepherd in Pulp Fiction, I try real hard to write this kind of code. I'm not where I want to be yet, but I'm trying real hard...
5. What, that's it? Just like that? No comments ever?
Well no. First, there are a couple of important prerequisites for this... One prerequisite is a good composition of the code, the division of code into clearly defined and scoped classes and methods. If your code is 1500 lines in a procedural style, then naming things well certainly help, but you still risk getting lost anyway.
And a prerequisite to do that well is to use ABAP OO, which we all should whenever possible!
Another is context. I mean in the above example there are still many things we can't say other than that this code is supposed to be prioritizing and executing. Hopefully it's clear from the context where the code is located what an assignment is and what kind of tasks we're talking about, for instance.
Comments are still a very good way to explain WHY something is done in a certain way, that might not be obvious... Something like this, for example:
" For some reason, the BAPI_CREATE_SOMETHING is not accepting item_id
" to be '0001' when creating a new object and assigning items at the
" same time. We use '1337' to prepare the data instead. This is fine.
items = VALUE #( ( item_id = '1337'
description = some_data->title
value = some_data->value ) ).(It's funny how the styling of the code blocks here are syntax highlighting inside the comments...)
Now, if only the reality was this simple... 🙂
Stay safe everybody and let's hope to understand each others code...
Addition: To keep reading on this topic in the SAP Community, I recommend continuing with I See Dead Code after getting the extra value from the comments below.
- SAP Managed Tags:
33 Comments
