It doesn’t matter if you write proprietary or open source code, comments in your code are very important (somehow even more important than readability and functional correspondence to the client’s needs). This is especially true if someone else is supposed or will, one day, look at your code, re-use your code and/or build upon your code.

For example, despite the fact that this source code header explained what the whole source is doing, you can’t tell what processing is done in this paragraph:

           MOVE SPACES TO IDTCLO-L1 OF ACXB01
                          IDTCLO-L2 OF ACXB01
                          IDTCLO-L3 OF ACXB01.
           @ZOBLIG, IDTCLO OF ACXB01, IDTCLO-V OF ACXB01-V.
           @CLR1, "01", "**", IDTCLO OF ACXB01, "3", "Y", "Y", "N",, \
                  IDTCLO-V OF ACXB01-V.
           MOVE IDTCLO    OF CLR1   TO IDTCLO    OF ACXB01.
           MOVE IDTCLO-L1 OF CLR1   TO IDTCLO-L1 OF ACXB01.
           MOVE IDTCLO-L2 OF CLR1   TO IDTCLO-L2 OF ACXB01.
           MOVE IDTCLO-L3 OF CLR1   TO IDTCLO-L3 OF ACXB01.
           MOVE NUMCLO OF CLD01-01  TO NUMCLO    OF TS-INTE.
           INITIALIZE ACD0B-01.
           MOVE NUMCLO OF TS-INTE TO NUMCLO OF ACD0B-01.
           MOVE REFACE OF ACXB01   TO REFACE OF ACD0B-01.
           @READ, "1", ACD0B-01, XX.
           IF ACCESS-OK
              @ERREUR, IDTCLI-V OF ACXB01-V, "ACXX0001"
           END-IF.

This code is definitely not readable. It first uses a standard nomenclature for variables, it uses macros with a good number of unknown variables, we don’t exactly know what can cause an error while accessing the table in the last lines, etc. This is only an example ; you can find this behaviour in many other programming languages.

That’s a reason why I really like tools to auto-generate comments and documentation (like Javadoc, pydoc, etc.). The documentation is in the code and it usually doesn’t block code reading while adequately describing what a section/paragraph/function does. And the tools can generate properly formatted documentation in a lightweight format (usually HTML+CSS, not heavy MS-Word documents). One nice thing: you don’t need to send the code and the documentation for review or upgrade: just send the code and your addressee will automatically get the documentation (s/he will be able to automatically generate it). And, in 2 years, people will still understand what you wrote and they won’t need a specialist to reverse-engineer your code.

By spending a little bit of your precious time to comment your code, others will get a better understanding of what you did and your project, as a whole, will save an impressive amount of time (time that you can spend on a terrace with a refreshing drinks).

Photo: “quote” by Bonnie Peirce (CC-by-nc)

• Computers