ENHANCE YOUR CODING STYLE
Imagine yourself in a situation where you are asked to explore about a topic by just an introductory heading.Seems like judging the contents of book by merely reading its title.Difficult,isn’t it?
Same happens for a beginner like me who at the first time gets confused between a table and a workarea. It is almost impossible to sail through the oceans of Function Modules and God forbid if you get across an OOPS object, you can find yourself hitting your head against the wall.You have to understand a code(not always yours) and if your luck runs out you have to make changes to it to meet a requirement. It sometimes also happened that it made me land into a serious confusion, while trying to understand my own code which I developed a few months ago.
It was after sometime my colleague told me a secret so that no other person who works on same object faces the same fate like me. It is not a big thing but a minor thing that we all ignore or forget. It is ‘POWER OF COMMENTING’. An object, however complex it maybe, becomes easy to understand if it has been properly described in comments about it.Moreover every person has a way of coding and doing things which are not easy to understand for others. Many of us find it boring and time consuming but if a new person works on an object developed by you in future,it becomes a lot easier.
Proper commenting is a healthy practice to code. A simple comment can help you understand the reason for using a particular unknown FM or why is there a particular condition in select query. After leaving no stone unturned to understand coding,this is what I figured out about the magic of “Commenting”:
1.Increases Readability of Code
It is always easy to go through a code if you know what a particular statement does.It can help you understand the gist quickly and understand your requirement easily.
2.Increases Navigation Speed
Many times it happens you need to change a particular field or a particular part of code but it takes time to find its position in a lengthy code.Commenting makes it easier,just press Ctrl+F and search your field or module.
3.Avoids Confusion
A new person can get confused if he/she sees a new object or even a select query he has no idea about.Proper comment,at proper places can help avoid that confusion.
So where and what should we comment.The answer is, wherever you feel this part needs some description.For example
In select queries:
To define what an include contains:
To establish relationship between displayed and technical field name:
Or to simply make the code more understandable:
Summary:
It is always easier to impart your knowledge of coding to others in a systematic simple way.This also benefits others in dealing with troubles and setting benchmarks for making coding a good learning exercise.
Afterall we all are here to ‘LEARN AND DECODE’ what SAP has to offer.Aren’t we?
I fail to see how commenting increases navigation speed. If I'm looking for a field Crtl-F will find the field regardless of commenting. In any case, if it's hard to find the section that you're looking for, the solution isn't commenting- it's proper modularisation.
For your selection example, if you had named your internal table deliveries the intent would have been clear. This is what is meant by writing self-commenting code. If you use good names for variables, that removes the need for certain types of comments.
Finally, you say "It is always easy to go through a code if you know what a particular statement does.". Comments shouldn't be tutorials on ABAP statements. You are expected to know these things. I hate seeing things like
* Go through all the deliveries.
LOOP AT deliveries...
The comment adds zero value. We know what LOOP AT does. We know it's deliveries. A better comment would be, for example For each delivery determine the day it will be delivered.
Hi
I do agree that ' if you had named your internal table deliveries the intent would have been clear' but my intent was what if someone looked and wondered why vbtyp_n is 'R' or 'J' in the query.For a beginner it is not easy to remember the field names or their values of various tables.
Also comments are not supposed to be tutorials on ABAP statements and everyone will hate seeing a comment for a 'if' or 'loop at' statement but it sure makes sense when you use it like:
set property of w_excel 'VISIBLE' = 1. "In background Mode
Also we usually know the name of a fields as it appears on output screen and not always remember its technical name.So when you want to change or see where is a particular field(say BSCHL as in above example), you can search 'Posting key' to search that BSCHL is the field for posting key saving some of your time and navigating you to that field if possible.
Although better comment can always help.
set property of w_excel 'VISIBLE' = c_background_mode.
To much commenting can make the code unreadable and be more of a hindrance. I comment my code so that a reasonably competent developer can understand what is going on. I do not comment my code so that a beginner can understand it. I expect a certain level of competence.
I think throwing newbies into support is a bad thing and I don't want to assist that habit at all.
I definitely agree with that last statement, it is redundant.
Sometimes it is better to think of comments as "Why is doing this?" as opposed to "what is it doing?".
The other thing is use meaningful names for constants and variables. I very often see a constant - for example c_A with a value of 'A'. It means nothing when you read it in it's context such as an if statement, but on the other hand a constant such as c_Dc_Inquiry with a value of 'A' would give an idea that you are checking for a document category that is an I(E)nquiry.....
Rich
It's even better when C_A has value of 'B'. And it is also used exactly once. I also love the monthly background jobs that have 'WEEKLY' in the name. 🙂
I've seen both. Death is too good for 'em.
While I agree with the principle of comments, I don't think you have chosen the right examples. I'm convinced though that comments are required to understand code of the generic or dynamic kind.
But very often, the ABAP syntax states exactly (and clearly) what is happening. Especially if the developer has 'enhanced' the syntax by the clear use of variables (with or without prefix 😉 ), methods, modules, routines, etc. (enough examples have been given above I think).
On the other hand, I have noticed for myself that sometimes me-myself-and-I think that a certain few lines of code are easy to understand.. but the customer or colleague does not.
Then again, I came upon a method yesterday where the developer had copied the entire spec and wrote her code in between. Most definitely not an enhancement when trying to figure out why the heck she used nested SELECT..ENDSELECT statements within a couple of nested loops.
Not the case anymore with "functional" ABAP 😉
Therefore i asked the question a few weeks ago - How much ABAP740 (read: functional ABAP programming) is too much?.
E.g., i add comments in the source code just to explain what exactly the REDUCE is doing 🙂 Just to be friendly with the developer who's gonna maintain my code.
Are you saying we'll write less code but more comments on it due the new syntax? 😛
If you're using a complex expression, then yes!
Add mesh-paths to the mix, to increase the confusion. I have already heard the comment, "I don't understand the ABAP you write!" 😐
oh well... that's a common issue!
The first time i used inline declarations, i got a good amount of complains from my former customer because "we cannot understand it " 😀
Is that why he is now a 'former' customer Simone ?? 😏
I've had that since I started doing Objects.
It all depends, though the answer that was flagged as correct in the thread you are referring to, states it all 🙂
It certainly is a bit difficult to judge this blog by the title because under "enhance your coding style" (no need to shout in all caps, by the way) I expected anything but another blog dedicated to the comment subject. (There already was one but with almost exactly opposite point.)
And it worries me a lot that a hypothetical newbie used as an example here seems to not have received any training before the assignment... Comments cannot be a substitution for basic training.
Completely agree with others that more descriptive variable names would've reduced the need for comments. Perhaps these were just not the best examples, but then for the blog dedicated solely to the comments better examples could've been chosen.
While I don't disagree that meaningful comments help (describing "why", not "what" or "how", which we can see from the code), I just don't feel this blog adds any value, sorry! In addition to the blog mentioned above there have been other SCN blogs and discussions regarding the comments in ABAP. Going forward, you might want to review the existing content before posting.
This blog doesn't add anything. But it does give a personal view, which is what blogs are about, which is why I let it be published.
I feel that the community quite capable of communicating their opinion.
Any blog that advocates commenting is a good blog, but I do think that the examples could have been a bit more, uh, convincing.
Comments are good for quickly explaining 'what' a module does and (if necessary) 'why' it was done that way.
Explaining the 'how' can be useful too, if the code is very tricky. But there's no need to state the obvious.
Keep on commenting! 🙂
I agree with Paul it's good practice and very helpful to comment what was the functionality of the code.
If you comment properly you didn't need to create technical document. 😉
Nice Blog Abhishek.
Cheers,
Naresh.
I was going to simply ignore this blog post, but I felt encouraged to copy and paste some comment I wrote in another blog post:
The quote above comes from the SAPPress book Managing Custom Code in SAP, by SAP Mentors Alisdair Templeton and Tony de Tomasis and was added with Alisdair's consent. The bold is mine.
Cheers,
Custodio
Since i started using AiE i use the AbapDoc extensively. Most of my comments explaining the "what" the procedure is doing goes into the AbapDoc and the "whys" in the source-code (if necessary). However, i am always confused on what should be going into the AbapDoc and end up over doing it.
IMO AbapDoc is a "god-sent" for people like me who HATE writing technical specs 😛 Now a days if someone asks me for tech-spec, i generate the AbapDoc and send it to them.
No disrespect to the Mentors but in this case I'd refrain from using such strong language as "failed as programmers". If you write a readable, well-performing code, an extra comment won't kill anyone. Neither will not leaving a comment. There are much worse situations for which strong (possibly explicit 🙂 ) language would be most appropriate IMHO.
Over commenting does harm since it affects readability. The easier it is to read code (in conjunction with comments), the cheaper it is to maintain it.
I think the author of the comment is not being specific enough - it is unclear whether he is saying all commenting is bad (which I think is wrong), or whether comments saying what an individual line of code does are bad (which I think in many cases, but not always, is right), or something in between.
Those mentors are wrong, I'm sorry to say.
How can self-documenting code state the assumptions? Or give a succinct 2-line summary of what the module does, so you don't have to plow through 50 lines of code to work it out for yourself?
One day I'll do a blog called 'The Self-Serving Myth of Self-Documenting Code'. To help me in that endeavor, I invite all comment skeptics to post their finest examples of self-documenting code on SCN. Because in all my years hunched over a keyboard, I've never seen any.
Except in the most trivial cases 😎
Self-documenting code is well written easy to understand code. It reduces the need for comment. It doesn't remove the need for comments.
Exactly. It simply can't be "all or nothing" with the comments, it's just not practical. Every time someone comes out in defense of the comments it's as if it's suggested to comment every single line (unfortunately this blog just has very bad examples). But the elusive 100% "self-documenting code" is not "comment-proof", it's barely "comment-resistant". 🙂 A reasonable balance between the two extremities is very much possible and it's not a "failure" in any way.
A much more common (and damaging) fallacy is the belief that your code is so clear that it doesn't need commenting. Such hubris!
On the rare occasions when I do find a helpful comment, I almost get emotional. 😘
It means someone actually cared enough to dash off a few lines, to make the job of the support guy/gal (who they will never meet) a little bit easier.
It doesn't matter if the comments are 'lucid' or not - any hint as to what the author was thinking or assuming at the time can be a big help.
Everybody can write comments, but not everybody can write code.
I've often found comments useful to determine exactly what the programmer had in mind.
This isn't always the same as what the code does - especially if I'm sitting there debugging it because it doesn't work.
I rest my case 😎
I have been a developer for 20 years. I rarely pay any attention to how a program is commented. You should be looking at the actual code to determine what logic is being implemented.
Likewise I also do not pay attention to a technical specification either.
You are putting all of your trust in the quality of comments. I have on many occasions re-visited my own code several months later and wondered what my own comments mean.
What are you going to do when you come across a program with irrelevant comments in it.
Just as my collegue sitting at the next desk did yesterday.....
Or when the comment is actively misleading, which I've also seen. Comments can't be syntax checked...
Comments cannot be fully ignored no matter how systematic you code or how meaningful variables you use.Although quality of comment matter.I have came across code where it would have been difficult to understand the why and how if proper commenting was not done.
The argument (not that I'm agreeing with it) is that if the code needs commenting to understand, you've done the coding wrong.
I totally agree. You should be able to read code and understand what it is doing. The code does not lie. Comments can assist and can be a quicker way of understanding what is happening. I do not rely on comments. I prefer to look at the code.
Comments can be misleading...misinterpreted.
The camera never lies...neither does the code.