Skip to Content

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.

To report this post you need to login first.

62 Comments

You must be Logged on to comment or reply to a post.

  1. Richard Bassett

    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.

    (0) 
    1. Juwin Pallipat Thomas Post author

      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.

      (0) 
  2. Robin van het Hof

    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:


    • With comments itself is nothing wrong; what is wrong is complex code that need long, explanatory comments.


    Why?


    • Code should be self-explanatory. It is just plain wrong to write complex, obfuscated code and think an explanation in a comment will do.


    Why?


    • Because comments don’t update themselves. If you change code, the accompanied comments should also be updated. Most developers forget/neglect to do that.


    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 ๐Ÿ™‚

    (0) 
  3. Naimesh Patel

    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

    • No deletion of old code. it can be deleted after certain time
    • Begin of / End of with Change identifier
    • Enough verbal description on why the change is made

    My question to them – is it too hard to open the development system and see the versions?

    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.

    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.

    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 developed a small utility program that I carry around with me, to different organizations

    I would love to see the program in action.

    Regards,
    Naimesh Patel

    (0) 
  4. Lucas Tรฉtreault

    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.

    (0) 
  5. Paul Bakker

    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

    (0) 
    1. Lucas Tรฉtreault

      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.

      (0) 
      1. Rick Bakker

        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.

        (0) 
        1. Juwin Pallipat Thomas Post author

          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

          (0) 
        2. Lucas Tรฉtreault

          Rick Bakker wrote:

          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.

          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:

          ***Sort the internal table based on print payee

          *      SORT gt_disb_details ASCENDING BY print_payee.

          *      LOOP AT gt_prt_req_disb INTO lwa_prt_req2.

          ***Execute loop for particular BP of print request (as in table gt_prt_req_disb)

          *  TYPES:

          **   BEGIN OF lty_contract,

          **         ranl TYPE ranl,

          **    END OF lty_contract,

          *

          ***Range table for BPs

          *    BEGIN OF lry_payee,

          *      sign      TYPE char1,

          *      option    TYPE char2,

          *      low       TYPE crec_gp_kk,  “Print Payee

          *      high      TYPE crec_gp_kk,  “Print Payee

          *    END OF  lry_payee,

          ***Drawings table

          *    BEGIN OF lty_vdausz,

          *      bukrs TYPE bukrs,  “Company Code

          *      ranl TYPE  ranl, “Contract Number

          *      dtrans TYPE  vvdtrans, “Flow data key: System date

          *      ttrans TYPE  vvttrans, “Transaction data key: system time

          *      ntrans TYPE  vvntrans, “Transaction data key: Consecutive number

          *      partnr TYPE bp_partnr_new,  “Business Partner Number

          *    END OF lty_vdausz,

          *      ltyt_vdausz TYPE STANDARD TABLE OF lty_vdausz,

          ***Loan Details

          *BEGIN OF lty_loan_detail,

          *      bukrs       TYPE vdarl-bukrs, “Company code

          *      ranl        TYPE vdarl-ranl, “Loan NO

          *      hdn_kunnr   TYPE vdarl-hdn_kunnr,”Primary Borrower

          *      partnr      TYPE vdgpo-partnr, “actual paid person

          *      address_no  TYPE zfcc_add_list_vw-address_no, “Address number

          *      roletyp     TYPE vdgpo-roletyp, “Role type

          *      gsart       TYPE gsart,     “Product Type — Added by HALDERP_SAP

          * END OF lty_loan_detail,

          * ltyt_loan_detail TYPE STANDARD TABLE OF lty_loan_detail.

          *

          *  TYPES:

          **  ltyt_contract     TYPE STANDARD TABLE OF lty_contract,

          *         ltyt_disb_details   TYPE STANDARD TABLE OF ty_disb_details,

          *         lryt_payee          TYPE TABLE OF lry_payee .

          *

          *  DATA: lwa_contract        TYPE ty_contract_1,

          *        lt_contract         TYPE tyt_contract_1,

          *        lt_contract_tmp     TYPE tyt_contract_1,

          *        lt_prt_req          TYPE gtyt_prt_req_disb,

          *        lwa_prt_req         TYPE gty_prt_req_disb,

          *        lt_prt_req2         TYPE gtyt_prt_req_disb,

          *        lwa_prt_req2        TYPE gty_prt_req_disb,

          *        “”–Below change – 2011-12-27 -starts

          *        lt_bp_role          TYPE ltyt_loan_detail, “gtyt_prt_req_disb,

          *        lwa_bp_role         TYPE lty_loan_detail,”gty_prt_req_disb,

          *        “”–Below change – 2011-12-27 -ends

          *        lwa_prt_req_tmp     TYPE gty_prt_req_disb,

          *        lv_date             TYPE sy-datum,

          ***Changes starts 2011-11-17 – Chandan Musib

          *         lt_fax_details     TYPE bapiadfax_t,

          *         lwa_fax_details    TYPE bapiadfax,

          *         lt_return          TYPE STANDARD TABLE OF bapiret2,

          *         lwa_return         TYPE bapiret2,

          **         lt_disb_details  TYPE tyt_disb_details,

          *         lwa_disb_details   TYPE ty_disb_details,

          *         lwa_regup          TYPE regup,

          *         lv_payee           TYPE crec_gp_kk,

          *         lv_old_print_payee TYPE crec_gp_kk,

          *         lv_fax             TYPE char1,

          *         lv_ranl            TYPE ranl, “Loan no

          *         lv_role            TYPE bu_partnerrole,

          *         lt_all_disb        TYPE tyt_disb_flow,

          *         lt_all_disb_tmp    TYPE tyt_disb_flow,

          *         lt_internal_disb   TYPE tyt_disb_flow,

          *         lwa_internal_disb  TYPE ty_disb_flow,

          *         lt_vdausz          TYPE ltyt_vdausz,

          *         lwa_vdausz         TYPE lty_vdausz,

          *         lt_loan_detail     TYPE ltyt_loan_detail,

          *         lwa_loan_detail    TYPE lty_loan_detail,

          *         lv_timestamp       TYPE tzntstmps,

          *         lv_partner         TYPE bu_partner,

          *         ls_but021_fs       TYPE but021_fs,

          *         lv_skip_flag       TYPE flag.

          *

          *  FIELD-SYMBOLS: <lfs_prt_req2> TYPE gty_prt_req_disb,

          *                 <lfs_contract> TYPE ty_contract_1.

          ***Changes ends 2011-11-17 – Chandan Musib

          *

          ** Determine If We Should Continue Processing Statement.

          *  CHECK: wa_continue EQ ‘X’.

          *

          *  IF p_dis_dt IS INITIAL.

          *    p_dis_dt = sy-datum.

          *  ENDIF.

          **Get the required contracts for which the disbursemnt or refund happened

          *  lv_date = sy-datum.                                       “‘20101105’

          *

          *

          **Get the external disbursement data

          *  IF gt_regup IS INITIAL.

          ***gt_regup is not initial it means that during tracking number

          ***population this data processing is already done.

          *    SELECT   *

          *       FROM regup

          *       INTO TABLE gt_regup

          *      WHERE laufd = p_dis_dt AND

          **          kunnr in s_dis_bp and

          *            xvorl = space AND

          *            vertn IN s_dis_ln AND

          *            vbewa IN (‘0001’ , ‘8005’ , ‘3090’, ‘0020’,

          *                     ‘0021’, ‘0022’,’0023′, ‘0024’, ‘0025’).

          ****For TPP Payment method(P)—Disbursement notice will be generated only

          *** on demand. No disb notice is expected at on demand process

          *    IF sy-subrc = 0

          *        AND sy-batch = ‘X’.

          *      DELETE gt_regup WHERE zlsch = ‘P’.

          *    ENDIF.

          *  ENDIF.

          *

          ***For External disbursements and spl. credits

          *  IF  gt_regup IS NOT INITIAL.

          ***Check whether FI document numbers are reversed or not

          *    SELECT vdbeki~ranl  “Loan Number

          *         vdbeki~dbudat  “POsting date

          *         vdbeki~sstorno “reversal indicator

          *         vdbepi~sbewart “Payment Method

          *         vdbepi~bcwhr   “Payment amount

          *         vdbepi~scwhr   “Payment currency

          *         vdbepi~zlsch   “Payment Method

          *         vdbepi~kunnr   “BP Number

          *         vdbepi~ddispo  “Payment Date

          *         vdbepi~dtrans  “Flow data key: System date

          *         vdbepi~ttrans  “Transaction data key: system time

          *         vdbepi~ntrans  “Transaction data key: Consecutive number

          *         INTO TABLE lt_all_disb

          *      FROM     ( vdbeki AS vdbeki

          *      INNER JOIN vdbepi AS vdbepi

          *        ON vdbepi~mandt    = vdbeki~mandt

          *       AND vdbepi~bukrs    = vdbeki~bukrs

          *       AND vdbepi~rbelkpfd = vdbeki~rbelkpfd

          **       AND vdbepi~rebzg    = vdbeki~rvzblg

          *       AND vdbepi~ranl     = vdbeki~ranl  )

          *      FOR ALL ENTRIES IN gt_regup

          *     WHERE vdbeki~bukrs    EQ  ‘FCC’

          *       AND vdbeki~ranl     =  gt_regup-vertn “s_dis_ln

          *       AND vdbeki~dbudat   LE  gt_regup-budat “p_dis_dt

          *       AND vdbepi~sbewart  IN (‘0001’ , ‘8005’ , ‘3090’, ‘0020’,

          *                       ‘0021’, ‘0022’,’0023′, ‘0024’, ‘0025’)

          *       AND vdbepi~zlsch    = gt_regup-zlsch.

          *

          *    IF sy-subrc  = 0.

          *      lt_all_disb_tmp = lt_all_disb .

          ***Get FI Documents for Refund, for Refund reversal indicator is 3

          *      DELETE lt_all_disb_tmp WHERE sbewart NE ‘3090’

          *                               AND sstorno NE ‘3’.

          ****delete reversed documents

          *      DELETE lt_all_disb WHERE sstorno NE ‘ ‘.

          *

          *      APPEND LINES OF lt_all_disb_tmp TO lt_all_disb.

          *      REFRESH : lt_all_disb_tmp.

          *

          **get the actual payee names

          *      PERFORM get_actual_payee_number USING gt_regup

          *                                            lt_all_disb

          *                                   CHANGING gt_contract_1.

          *    ENDIF.

          *  ENDIF.

          *

          **Get the required contracts for which only internal disbursemnt happened

          *  SELECT vdbeki~ranl  “Loan Number

          *       vdbeki~dbudat  “POsting date

          *       vdbeki~sstorno “reversal indicator

          *       vdbepi~sbewart  “Payment Method

          *       vdbepi~bcwhr   “Payment amount

          *       vdbepi~scwhr   “Payment currency

          *       vdbepi~zlsch   “Payment Method

          *       vdbepi~kunnr   “BP Number

          *       vdbepi~ddispo  “Payment Date

          *       vdbepi~dtrans  “Flow data key: System date

          *       vdbepi~ttrans  “Transaction data key: system time

          *       vdbepi~ntrans  “Transaction data key: Consecutive number

          *       INTO TABLE lt_internal_disb

          *    FROM   vdbeki AS vdbeki

          *    INNER JOIN vdbepi AS vdbepi

          *      ON ( vdbeki~mandt    = vdbepi~mandt

          *     AND vdbeki~bukrs    = vdbepi~bukrs

          *     AND vdbeki~rbelkpfd = vdbepi~rbelkpfd

          *     AND vdbepi~rebzg    = vdbeki~rvzblg

          *     AND vdbeki~ranl     = vdbepi~ranl )

          *   WHERE vdbepi~bukrs    EQ  ‘FCC’

          *     AND vdbepi~sbewart  = ‘0002’

          *     AND vdbepi~ddispo   = p_dis_dt

          *     AND vdbepi~ranl     IN  s_dis_ln.

          *

          *  IF sy-subrc = 0 AND lt_internal_disb IS NOT INITIAL.

          ****delete reversed documents

          *    DELETE lt_internal_disb WHERE sstorno NE ‘ ‘.

          *

          *    IF lt_internal_disb IS NOT INITIAL.

          *      SORT lt_internal_disb ASCENDING BY ranl.

          *

          ***Retrieve data from Drawing table

          *      SELECT  bukrs   “Company Code

          *              ranl     “Contract Number

          *              dtrans   “Flow data key: System date

          *              ttrans  “Transaction data key: system time

          *              ntrans   “Transaction data key: Consecutive number

          *              partnr  “Business Partner Number

          *              FROM vdausz

          *              INTO TABLE lt_vdausz

          *              FOR ALL ENTRIES IN lt_internal_disb

          *              WHERE bukrs   = ‘FCC’

          *                AND ranl    = lt_internal_disb-ranl

          *                AND dtrans  = lt_internal_disb-dtrans

          *                AND ttrans  = lt_internal_disb-ttrans

          *                AND ntrans  = lt_internal_disb-ntrans

          *                AND sbewart = ‘0002’. “(Only for Internal disbursements)

          *      IF sy-subrc = 0.

          *        SORT lt_vdausz ASCENDING BY ranl.

          *      ENDIF.

          *

          ***Append lines into gt_contract_1

          *      LOOP AT lt_internal_disb INTO lwa_internal_disb.

          *

          **READ TABLE gt_regup INTO lwa_regup

          **      with key laufd = p_dis_dt

          **               vertn = lwa_internal_disb-ranl

          **               zlsch = lwa_internal_disb-pay_meth.

          *

          *        ws_contract_1-ranl = lwa_internal_disb-ranl. “Loan No

          *        CONCATENATE lwa_internal_disb-ranl+0(10) ‘000’

          *               INTO ws_contract_1-cf_no.  “CF No

          *        ws_contract_1-pay_meth = lwa_internal_disb-pay_meth. “Payment *Mod snip to make things more readable, but there was another 400 lines of commented out code…

          (0) 
          1. Esti van Wyk

            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 #%@!” ๐Ÿ™‚

            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!

            Exactly – if your comment ( or commented code ) does help you answer the questions above, it’s not helpful.

            (0) 
            1. Lucas Tรฉtreault

              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.

              (0) 
              1. Paul Bakker

                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

                (0) 
                1. Robin van het Hof

                  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

                  (0) 
        3. Robin van het Hof

          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.

          (0) 
        4. Custodio de Oliveira

          Rick Bakker wrote:

          Not once have I looked at code and thought “Wow, too many comments!”

          Not once have I looked at code and thought “Great, lots of comments!”

          (0) 
        5. Jelena Perfiljeva

          Rick Bakker wrote:

          Not once have I looked at code and thought “Wow, too many 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.

          (0) 
    2. Rainer Hรผbenthal

      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.

      (0) 
  6. Matthew Billingham

    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//

    (0) 
    1. Matthew Billingham

      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!

      (0) 
      1. Paul Bakker

        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!

        (0) 
        1. Robin van het Hof

          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 ๐Ÿ˜‰

          (0) 
          1. Simone Milesi

            Heck, developers should have no access whatsoever on a production environment other than to the logs and traces.

            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.

            (0) 
            1. Matthew Billingham

              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!

              (0) 
          2. Matthew Billingham

            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.

            (0) 
        2. Matthew Billingham

          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!

          (0) 
  7. Tomas Buryanek

    Yes, even one misleading, redundant, wrong… comment is too much.

    [clicking on “Add Comment” and hoping it is not such case] ๐Ÿ™‚

    (0) 
  8. Jelena Perfiljeva

    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…

    (0) 
    1. Gareth Ryan

      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.

      (0) 
  9. Shyam Sunder Goyal

    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 .

    (0) 
  10. Phillip Morgan

    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  ๐Ÿ˜‰


    (0) 
    1. Matthew Billingham

      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!

      (0) 
  11. Chris Bosler

    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.

    (0) 
    1. Jim Tasker

      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!

      (0) 
      1. Paul Bakker

        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

        (0) 
        1. Custodio de Oliveira

          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:

          While comments are neither inherently good or bad, they are frequently used as a crutch. You should always write your code as if comments didn’t exist. This forcesyou to write your code in the simplest, plainest, most self-documenting way you can humanly come up with.

          Cheers,

          Custodio

          (0) 
          1. Rick Bakker

            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.

            (0) 
            1. Rick Bakker

              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?

              (0) 
              1. Robin van het Hof

                You mean, 80% of the code is understood by only 20% of the developers?

                Again, I cannot stress this enough, but:

                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.

                This is how our professors taught us coding at school ๐Ÿ™‚

                (0) 
                1. Rick Bakker

                  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.



                  (0) 
                  1. Robin van het Hof

                    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,

                    it allows the 3 higher-level methods to read more like a series of comments

                    Indeed, Spanish abbreviations is not a good choice, you might as well name your variables a, b, i and n for that matter ๐Ÿ˜‰

                    (0) 
          1. Paul Bakker

            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..

            (0) 
            1. Simone Milesi

              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? ๐Ÿ˜€

              (0) 
            2. Matthew Billingham

              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.

              (0) 
            3. Lucas Tรฉtreault

              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. 

              (0) 
              1. Rick Bakker

                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!

                (0) 
                1. Lucas Tรฉtreault

                  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……….

                  (0) 
                2. Matthew Billingham

                  “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.



                  (0) 
    2. Custodio de Oliveira

      Chris Bosler wrote:

      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. 

      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

      (0) 
  12. Gareth Ryan

    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.

    (0) 
  13. Radha Ravichandran

    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 ๐Ÿ˜›

    (0) 
  14. Michelle Crapo

    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.

    (0) 

Leave a Reply