How much “Comments” is too much?
All throughout my ABAP career in various organizations, I have come across many organization specific “Coding Standards Documents”. And all of those documents had couple of things in common – Whenever you are making a change to existing code, mark your changes with comments stating
*Begin of changes by Juwin Thomas on 5/27/2015 ECDK909909
……
……
……
*End of changes by Juwin Thomas on 5/27/2015 ECDK909909
And I kept on wondering isn’t this already handled by SAP’s Version management? After 10 changes done by 10 different people, the commented lines in the program becomes more than actual executable code. Who reads these anyways? I haven’t, I always go to version management, to see who did the changes, when and what was the change.
Another “Coding Standard” I have seen is – Do not delete any lines from the program, comment them instead. Isn’t this similar to having dead code inside the program?
Has anyone felt the same way? Or, are there anyone here, who think something good is going to happen with all these comments in the code?
One of the arguments that I have heard from people who likes comments – especially code reviewers 😈 – is that, in production system, where there are no program versions maintained (generally), it becomes easy to understand the changes if there are comments. My question to them – is it too hard to open the development system and see the versions? Or, if they like to see the versions in production system, activate versioning in that system during transport. Why degrade the code readability by putting in all these comments?
SAP standard programs have been around for decades and have gone to regular maintenance by different developers. But, I hardly see any such comments in any of the SAP standard programs. I haven’t worked at SAPLabs, so I don’t know if they have such a Coding standard. If they don’t, how do they manage their code reviewers?
Bored of writing these type of comments in my program, I developed a small utility program that I carry around with me, to different organizations. What I do is, whenever I have to do changes to an existing program, I write the code the way I want, without any change comments, and run it through my utility program when I am done. The utility program reads the current version and previous version of my changed program and inserts the comments wherever appropriate. 😎
But, I still keep wondering, why do we need this practice? 😕 I feel that there should be a “Comments Standard Documents” also, in addition to the “Coding Standards Documents”, to explain when & how to write comments.
Interesting question. I am guilty of some of the things you mention. While version management does exist it isn't perfect. At my shop we have been through 3 upgrades and on one of those our BASIS people didn't know how to keep versions and we lost all code prior to what was Active. In our shop some of our Functional people can read code and they like it when they can see the changes all in one place. My personal policy is to leave then there until the next major change and then delete everything previously commented out.
I'm sure most of us do it this way because that is how we were taught or tolld.
My personal policy is to leave then there until the next major change and then delete everything previously commented out.
I like that. It is good to have some kind of code cleanup periodically.
Disclaimer: I have none to zero ABAP experience, I have a (NetWeaver) Java / Javascript background
From my point of view, you are absolutely right. Having comments explaining a change is redundant. It should at most serve the original developer to track what changes he has done before (!!) submitting to the versioning system -- which means he needs to clean out these comments prior to that.
As Java is compiled code, a reviewer would have no business anyway on a production environment, but I would say the same is true for the ABAP world. I would emphasize it again: no reviewer, no coder, should have access to sources on a production environment.
I do some fair amount of code reviews myself, and with regards to comments, I can share you this:
Why?
Why?
In the end, I would favor a developer writing simple code to solve a complex issue -- without writing a comment -- anytime over one that writes complex code and writes a comment explaining what he did.
Bottom line: Use as few comments as possible, your code should be self-explanatory 🙂
Looks like you got real bored of writing the comments 🙂
I also thoughts of the same thing initially when I was not QA reviewer. Now, I'm QA reviewer 😈 and I think differently. Now, I support all of these
In many of the organization, the cost of checking the version management in the development system would high especially hourly sales is in range of tens of millions of dollars. This type of Critical high priority calls, requires these type comments. So, people on the call - who are not developers, but rather executives/stakeholders and don't have development system access - can decide if the change is required or can be switched off for smoother operations and lose of revenue can be minimized. The cost of adding the comment lines would be much lesser than the time spent (hence lose of revenue) in these type of situation.
You may not run into the issue - if code was designed perfectly and was tested with all possible scenarios. You can pick and choose where to put comments, thus it would be part of the organization's coding standards and QA reviews to make sure these are implemented.
Because SAP uses the OSS note number wherever they are corrections. You can think of this note number as change number for the organization. I think, SAP might be having a local system where they would be maintaining considerable comments than what is shipped to customers in the OSS notes corrections.
I would love to see the program in action.
Regards,
Naimesh Patel
At my company, we barely write any comments at all. The general rule of thumb is that if you think you need a comment, what you probably actually need is a new method or class with a descriptive name. Your code should read like English and it should be obvious what you're doing.
If I look at any old code, the very first thing I do before I even try to understand the code is delete any commented out code and any of the *Begin of changes.... type comments.
If you do write a comment, it should be about WHY you did something, not HOW.
Hi,
Nice blog, but I respectfully disagree. As far as I'm concerned, there can never be too many comments.
If we have a big Production issue and someone has changed the code recently, I want to immediately know where, I want to know why, and I want to know what they were thinking at the time!
Version control does not always work. We moved to another system and lost all of our change history,.. Also, if a programmer starts messing with the layout / indentation of the program, it can obscure the real changes.
In general, comments force programmers to think about / explain what they are doing. And that is always a good thing. (It's also the reason why many programmers don't like commenting).
cheers
Paul
Comments, especially the type that the blog talks about, clutter the code and rot quicker than the code does as changes are made and people don't keep comments up to date.
Good design forces programmers to think about what they are doing. Comments gives them an easy out to write horrible code.
If you need to explain WHAT you're doing in comments, then your code sucks and you should refactor it until it is self-explanatory.
I can't believe what I'm reading here. Not once have I looked at code and thought "Wow, too many comments!"
If the code is self-explanatory, great, I'll skip the comments. But code is usually only self-explanatory to the person who wrote it, not to the person who has to fix it or the person who has to change it 10 years later.
If someone has a program for automatically inserting comments then in that case I agree: those comments are useless.
Good and plentiful commenting is the first thing I was taught in Programming 101.
Could not agree more Rick
Hi Rick, Thanks for your opinion on this. While I agree that some comments are necessary and help another person understand the code easily, my concern was about forcing the developers to write comments like "Begin of changes..... End of changes", which is already handled by the version management system.
Best regards, Juwin
Have a look at the following and tell me there can never be too many comments. This is over 700 lines of commented out code that has been left in one of our programs by some consultants for some reason.
It also contains some wonderful comments such as:
This is exactly the problem I have with coding standards that does not allow deletion of code.
But I must admit when looking at this code extract I don't so much think: "Wow, too many comments" as: "Wow, what a load of #%@!" 🙂
Exactly - if your comment ( or commented code ) does help you answer the questions above, it's not helpful.
Yup it's total crap, I agree. Written by some offshore consultants... The reason I shared this specifically was because it has tons of comments and it's still ****... So, the theory that comments in code makes it good is obviously not true.
I think the 'theory' advanced in the commentary above is:
No comments --implies--> bad code
While you are actually arguing against the 'theory'
Comments --implies--> good code
Which is something quite different; like the difference between a real man and a straw man 😛
Indeed, no amount of commenting will make 'bad code' good. But that doesn't relieve us of the responsibility to provide quality comments in our own code.
Quality comments provide the business context, the assumptions, the 'why' behind the code. No clever method or variable names can match that.
cheers
Paul
I beg to differ.
The business context, the assumptions, as well as the 'why', should all be clear from the code (classnames and variable names should have descriptive, English meanings, the formatting/indenting should be correct (!!) and the program flow should allow you to easily 'read' the code and understand the 'story' being told)
For example, if I should comment three blocks of code in a function, then I should use three sub-methods. These sub methods, given a proper name would remove the need for a comment.
Since the business context of your program code often spans multiple classes over multiple files over multiple locations, commenting separate stubs of code is in essence quite meaningless then 😉
As others have mentioned, no single comment have ever made my life easier -- not as a developer, and not as a code reviewer
Show me a developer who updates code written by someone else, and at the same time updates the comment written by that previous developer to match his current changes, and I'll buy him a beer.
Not once have I looked at code and thought "Great, lots of comments!"
You're soooo lucky! I'm getting concerned my eyes are going to get hurt from rolling constantly at the sight of 'begin of change by...' and 'Loop through table' and 'call BAPI' and 'insert suitable error-handling here' and just tons of commented out code that shouldn't have been written ever.
But the issue is mostly with the quality of the comments, not quantity (as we've established in the long discussion on the old blog 3 years ago). If the comments add value (or are amusing we even have a thread on this on SCN) - go ahead. But in my experience about 97% of the comment volume is digital garbage, essentially.
Doing versioning by commenting is useless. After three or more changes in one place you are not able to figure out who was doing what. If you lost your Version you did something wrong, but it's always better to solve the root cause instead of putting work arounds in place.
And yes, there is something of too many comments. comments Like "add 3 to var" are completely useless and they are superfluous. It should be explained why 3 was added.
In addition, you never can be sure if the coding matches the comment. The comment may be old and not adopted to changes in the code.
Versioning never forgets a versioning like programmers can do, so this is more trustable as having such silly comments inside the code. I promise you're unable to rebuild an old version out of such comments.
I have written/revised the programming standards several times for a various clients. I've specifically stated that versioning in code is forbidden as it leads to code that is hard to read and hard to maintain - and that means expensive.
Having to comment out large swathes of code indicates the code isn't decently modularised. With properly defined variable and method names, your code becomes self-documenting - any comments will add useful information.. I do not think that catering for bad programmers (who don't modularise ) is a way forward.
This does not mean you do not have a change log.
In BW, where there isn't versioning in certain areas, I ensure that there is the minimal ABAP required to call a function module or class, which does have versioning.
I did work at one site where there was a directive from some senior manager that version history must be maintained in comments. Fortunately, she was moved on before I started working in that team. Frankly, I'd have refused point blank to do it - exactly the same as if I was asked to update BSEG directly. I won't be associated with a project that has such bad working practices.
If I come across program code on this site that contains commented out sections, I often reject it.
//RANT ON// Like when people say "my program doesn't work, please help", but not only are too lazy (or stupid) to only post the relevant bit, but can't even be bothered to remove huge rafts of commented out code. //RANT OFF//
I'm going to add that the expense that in-code versioning adds massively, in my opinion, outweighs any benefit from:
"If we have a big Production issue and someone has changed the code recently, I want to immediately know where, I want to know why, and I want to know what they were thinking at the time!"
which in any case I think is a bit (with the greatest possible respect) inconsequent..
If I want to know things like that, I log on to the development system and see what the latest changes transported to P were, using version management. At the same time I can be logged into P and debug to figure out what's gone wrong. As a very last resort, I check the documentation of the change request... ( 😉 )
Single sign on and big screens help with this, but they're not essential. I've even done it on my tiny laptop!
Let me get this straight - a recent change went into Production, the application is dumping, and you have been called out of your bed to log in and fix it.
You think it's quite acceptable that you need to log into multiple systems and run a debug session in Production, rather than expect the programmer to provide a thoughtful two-line explanation of why the change was made (and clearly mark the relevant changes in the code).
Seems a wee bit defeatist, don't you think? 😆
Undocumented changes don't get any further than Dev in our shop!
As said, I have no ABAP background, so maybe it works differently in that realm, but in my 17 year career, I have never ever felt the need to debug in production. Heck, developers should have no access whatsoever on a production environment other than to the logs and traces.
Generally, a short investigation of the logs on production tells me what happens, and then you go to DEV and fix things.
Comments in the code -- if any -- does not help me at all, but a) the stacktrace of what happened during the exception as well as b) the DIFF between the current version and previous version(s) certainly does 😉
i can agree, but only if who raise the issue could repeat it in any other enviroment (and sadly this is pretty rare in my experience 😛 ).
As many others stated, code should be self explaining if well organized.
i avoid to comment my code since i organize it pretty well.
But i'm talking about my code.
When i work on existing spaghetti code (a 2k report with 2 forms each one of 1k rows..) i try to add some comment to help the poor guy who'll stumble on it next time.
When i work on existing spaghetti code (a 2k report with 2 forms each one of 1k rows..) i try to add some comment to help the poor guy who'll stumble on it next time.
I do that as well. I consider my humanitarian duty... anyway, it might be the next time as well!
Depends. On a validated ERP system, I've had to do a productive debug once (in the three years I worked on that system).Mere mortal 😉 programmers were not permitted - it had to be escalated to me as head of dev. department. Usually there's sufficient data in the test systems to replicate there.
In BW, which I mainly work on at the moment, debugging in production is not so restricted. Data flow failures are relatively common, so it's often not possible to replicate on test.
Let me get this straight - a recent change went into Production, the application is dumping, and you have been called out of your bed to log in and fix it.
You think it's quite acceptable that you need to log into multiple systems and run a debug session in Production, rather than expect the programmer to provide a thoughtful two-line explanation of why the change was made (and clearly mark the relevant changes in the code).
If you rely on the comments then I think you are not exercising due diligence. Yes, it's as strong as that. Comments, with the best will in the world are not reliable. As others have pointed out, the information contained in them rots, and humans are fallible. Direct code comparison via version management is definitive and the only correct way to procede. No reliance whatsoever on fallible humans getting their comments right. Comments should only be used to explain the code as it is - not changes.
Logging into two systems to resolve an issue is hardly an onerous task. I work in BW - we've got dozens of source systems.... that's a lot of systems to log onto to resolve data issues, yet somehow we manage to do it!
Yes, even one misleading, redundant, wrong... comment is too much.
[clicking on "Add Comment" and hoping it is not such case] 🙂
For a moment I actually thought this blog was about the SCN comments. We do frequently get comments longer than the blog/document itself. 🙂
There was already a blog on this on SCN back in 2012 with 100+ comments. You might want to search before posting.
Our development guidelines suggest adding meaningful comments where applicable (e.g. explaining why change was done, not when or by whom, is beneficial for future maintenance). We also sometimes mark changes with the corresponding ticket number (similar to what SAP does with note references in the comments).
The "begin of change .... end of change" comments I fight tooth and nail and purge them mercilessly (together with commented out bits) whenever I get a chance. Surprisingly, there was actually quite a bit of resistance to this from the consultants because "that's the way we've always done this". Argh...
Sorry....
Nearly 2 decades in development and I don't remember one single time that comment or dead code made my life easier.
I wish it were possible to like this comment multiple times!
Custodio has hit the nail on the head and my opinion is exactly the same. Could write a very long, rambling blog on the subject but just don't have the time.
And in my 1 decade of programming only once 🙂
Hence the question - Regarding unused "optional" parameters in procedures - do you leave them commented out?
Great to read all this stuff !
Now onwards , I will try to avoid these undesired and unwanted comments .
But can't we use documentation functionality provided by SAP itself to maintain such comments instead of writing in code .
On my current mission (where I also audit code), the policy was to comment old code. Then we
* IF vg_code_a CO c_numbers. " '0123456789
* "do nothing
* ELSEIF vg_code_a IS NOT INITIAL.
* READ TABLE t_status_list
* TRANSPORTING NO FIELDS
* WITH KEY txt04 = vg_code_a.
* IF sy-subrc NE 0.
* MESSAGE text-012 TYPE 'S' DISPLAY LIKE 'E'.
* sy-subrc = 1.
* RETURN.
* ENDIF.
* ENDIF.
*
* IF vg_code_b CO c_numbers. " '0123456789
* "do nothing
* ELSEIF vg_code_b IS NOT INITIAL.
* READ TABLE t_status_list
* TRANSPORTING NO FIELDS
* WITH KEY txt04 = vg_code_b.
* IF sy-subrc NE 0.
* MESSAGE text-012 TYPE 'S' DISPLAY LIKE 'E'.
* sy-subrc = 1.
* RETURN.
* ENDIF.
* ENDIF.
realized it was getting difficult to read the code. So we changed our policy. My tired eyes are very thankful. "MK001: we still mark code....
* ...and encourage comments when helpful 😉
I'm pretty sure these policies originate from the days where there were no versioning tools. Presumably when all CIOs have been born in the 21st century, such practices will be consigned to the bin of history - where they belong!
I feel like the point of commenting is being missed by a lot of people here. Concise comments explaining the intent of sections of code are wonderful in my opinion. They give an easily human readable picture of what is being done.
The posts containing large sections of commented out code are obviously going to be of little or no value as it's just dead code that is not being used and does not provide insight into the current implementation.
I entirely agree. Comments shouldn't be done away with - they should be done properly.
I agree - my code is filled with comments about "why", not about what the code is doing. However readable and well-modularized with good method names things are; explaining why is a big help. It's good QA too: I often spot little bugs and design flaws as I'm writing my "why" comments and I see that the code doesn't really match my intentions!
Dead right, Jim. My practice is to always write the comments before writing any code. It often leads to a rethink / redesign. I always try to state my assumptions as well.
Some of my modules end up having more comments than code. 😏
Self-commenting code does not exist, in my experience.
cheers
Paul
Are you sure you don't mean "always write my tests before writing code"? 🙂
Just yesterday I discussed with a colleague that we should have a rule: you should NEVER have more comments than code.
Anyway, I invite all the "comment lovers" to read this: Coding Without Comments
A little taste:
Cheers,
Custodio
The students who dared hand in code without comments always got an instant Fail from me and are probably living under a bridge somewhere now.
Cannot agree more with that statement! 🙂
And here I was thinking that people who refused to comment code were just lazy. Turns out there's a whole philosophy behind it!
Do they not teach the 80/20 rule any more?
You mean, 80% of the code is understood by only 20% of the developers?
Again, I cannot stress this enough, but:
This is how our professors taught us coding at school 🙂
Thanks Robin, I have been wondering if this is how it is actually being taught now.
I'm trying to find a current Computer 101 textbook online.
A question: when the Modern Programmer gives these modules their self-explanatory names, exactly which language do they use? English? The local language?
Not too hard to cut and paste a block of comments into Google Translate but it may be a bit harder with abbreviations crammed into module names with all the non-alphanumeric characters in between.
I've recently been wrestling with coding where all the variables and module names are Spanish abbreviations and I can tell you, it's a party.
I'm talking from my experience with Java and Javascript, but I'm sure this can be valid for any programming language which has support for longer, descriptive method / variable names.
BTW, my technical education was in the 90's, so not really current as well 😉
See also Extract Method, which explains the reasoning behind this type of refactoring. From the article, if you extract these 3 aforementioned blocks of code in separate methods,
Indeed, Spanish abbreviations is not a good choice, you might as well name your variables a, b, i and n for that matter 😉
Working with SAP we're always dealing with abbreviations for German words. Some of them dialect!
I'm so glad that CDD isn't a real thing.
I can't imagine writing comments before code... That sounds absolutely ridiculous.
Before the first line of code is written, you pause to gather your thoughts about what your module is going to do, what the inputs and outputs are, and what your assumptions are. Perhaps even consider if this module is needed at all.
While it's all fresh in your head, you write it down succinctly. Explaining it to yourself (or some future programmer) clarifies your thoughts even more.
Yeah, sounds like a ridiculous waste of time. Better to just get in there & code... 😕
I love this forum.. all these different points of view..
A quick explain of a method or a form could works but... this should also be the Tech Analyst's job.
Or am i wrong?
Ok, ok, i know... who even read a REAL and COMPLETE Tech Analysis even when he was a junior with less than 2hrs of work under the belt? 😀
It is perfectly possible to gather your thoughts and then program a succinct outline (top down) of the solution. The intermediate step of writing it down may indeed by a waste of time for some.
Usually I design the whole thing in my head (That's what 3a.m. is for!). Then write the code. As I've got more experienced, I find the design takes less and less time. Sometimes, I've got the whole shape of the requirement in a very short space of time, perhaps while having a coffee for five minutes.
(OK, when it's complicated I might use UML (I recommend Violet UML Editor : easy to use, completely free) , but things rarely get that complicated in my area of work).
What I think you're encountering is that (in my experience working in dozens of companies at different levels over 25 years) developers seem to broadly fit into one of two categories. The majority need to design first (or if they don't then they definitely should!) and, having everything laid out, begin coding. Others, the minority, work in a more intuitive way, adopting a design by coding methodology.
There is no one right methodology for all developers. There is merely your (or my) right way - the way that enables you or me to write code that is robust and maintainable. Don't try to fit round pegs into square holes. They wobble.
Let me fix that for you:
Before the first line of code is written, you pause to gather your thoughts about what your module is going to do, what the inputs and outputs are, and what your assumptions are. Perhaps even consider if this module is needed at all.
While it's all fresh in your head, you write a unit test for this bit of functionality that acts as living documentation and protects the code from future developers who may not fully understand the intent.
This must be this new "Fragile Programming" that I've been hearing so much about (I think that was the name).
.
Now that the code is self-explanatory I suppose testing is so last Millennium too.
At least now I have a new Second Question when interviewing for new team members!
Test Driven Development is "Fragile Programming"? I guess you haven't kept up with development practices in the last 15-20 years....
Why on earth would you imply that I think testing is so last millenium when I just suggested you write some unit tests instead of comments. We have 8500+ unit tests, hundreds of FitNesse tests and hundreds of QTP tests running against our codebase automatically every time someone promotes a change to a test environment and every night.
But I guess your comments protect your production code from breaking..........
"Now that the code is self-explanatory I suppose testing is so last Millennium too."
If you build an automated unit tests, then it reduces the effort for testing. It doesn't reduce the amount of testing. In the same way self-explanatory code reduces the need for comments. It doesn't reduce the requirement to be clear about what you're doing.
I would say: Concise comments explaining the intent of sections of code are ok, if the code itself is not clear enough.
Your (our) job is: to write clear code.
Cheers,
Custodio
I think part of the challenge is that the traditional ABAP toolset doesn't enable quick and easy re-factoring of code in the same way as other, more OOPS originated langues such as Java do with their IDEs.
I'm sure you've all read lots of articles that pretty much pronouce "refactor, refactor, refactor" as an underlying principle for all development, and I'd agree with this approach. However it isn't always really quick and easy with ABAP tools.
As an example, take a look at this blog post where I describe the simple method of refactoring using the "Extract Function" in Eclipse. Looking back, it isn't the best example however the point is that it is very easy to achieve refactoring. The ABAP toolset and actually the ABAP syntax aren't as flexible in this perspective, although with the move to AiE and the latest 7.40 releases things are greatly improved.
And why am I harping on about refactoring? Well, as others have mentioned, it is one of the best and easiest ways of making clean, uncomplex code, which in turn should remove the need for pointless comments.
Cheers,
G.
Agreed completely. Especially the dead codes and the tags. at some places, the code change seems to be minimal than these comments and cosmetic statements 🙂
I worked on one specific project where they had dual landscape for Development and support projects. Frequent refresh happens from the Production to the development environments and only the support tickets will be replicated during the project development duration. The changes as part of the development project will reflect when this refresh happens after the Go-live of that release. with this scenario, the version management or request tracking from another development environment was difficult.
But still, we used to have a log at each object tracking every change and their details are sufficient to understand.
Nevertheless, can't escape a process called review and one or the other make us to follow this practice how much ever we are against this 😛
Well a blog is always awesome when it generates this many "comments"! Groan.
I hate dead code and remove it whenever possible. Versioning is available - use it. I like comments that explain "why". As for what the code does - I should be able to read it. But why - sometimes we can repeat mistakes if we don't know the background.
And yes, if I've figured out some really "interesting" code, I tend to leave comments for the poor guy that follows me.
BTW - when making people comment changes, do they always comment everything they should? OR do they forget sometimes. How would you tell? Ha! You'd use the version management.