Tag: source

Comment your code

QR codeIt 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)

A voté !

As every Belgian citizen, I voted today for our legislative bodies (Chambre et Sénat). As always, I was confronted to the same problem: electronic voting. Technically, I’ve no problem to understand and use the system: it’s an ethical problem. I don’t know if my vote is correctly written on the card, even with all the given guarantees and technical details (you can test such a voting machine here or watch a demo of the Belgian system, both in French). Personally, I saw two problems:

  • Source code is not available to any citizen, even if they promised to release it on the day of the polling (see the official website and screenshot below). I don’t think I have enough computer security knowledge to review those sources in detail but I think they have to make them available because 1) it allows a democratic control and 2) they promised it. I usually do not believe in conspiracy theories but … 😉 See update below
  • The old lady in the voting booth next to mine was “helped” by someone she doesn’t know from the polling station. I clearly was able to hear technical instructions but one doesn’t know the exact meaning when the person told her “to point there“. Don’t be mistaken: hopefully this person was there to help her, otherwise the old lady wouldn’t have been able to vote. What I’m criticizing is the fact that all Belgians are not equal in front of the voting machine (although they are all supposed to be equal in front of the law).

I was very happy to see that all the French-speaking political parties presidents were against electronic voting (with some nuances for the MR party). Let’s see how they will act during the next legislature …


(bigger version here)

Update: at 17.00 (5.00pm) files were finally online (here and here, personal copies here and here). I guess they were not able before 15.00 (end of voting time) to avoid code substitution on some machines by hackers, like it happens with the Nedap machines in the Netherlands.