Title: COMMENTS- A Personal Perspective

A high level computer program written by a human being in a 3GL such as C, C++ or JAVA is changed by a process, usually a compiler or an interpreter, from an easily understood language into object code that is only understood by computers and geeks [no offence to geeks]. With today's knowledge available, 3GL's are usually written in such a way, by programmers, that they are self-commenting through the use of identifier names and style. This I agree with heartily, however this is the professional way of doing things i.e. corporate code. Programs written to industry standards in the commercial world are paid for.

To get to this point, one has to learn from the beginning. This requires study and practice by example, great reams of explanation from authors of what a certain statement or group of statements is doing, and over the top commenting to get the point across, and so the learning process has begun.

The books I have read usually make two points about comments

With C only the multi-line comment was available, with C++ and JAVA both are available and used. C++ and JAVA programmers usually prefer the single line comments, as they are easier to spot in documentation, although the multi-line comment must be used for embedding comments into executable code. This is not recommended. There would follow a brief discussion of where to use and not use comments with regard to the working of a program and avoiding the confusion of clashing comments with statements so as not to cause syntax errors, but no real insight into how they are used commercially. It isn't necessary.

Recently I was following a thread on ACCU-General 'Comments in code' which for me was revealing in as much as there were not just two sides to the debate i.e., good comments on the left and bad comments on the right, but many varied and different views on commenting and its repercussions and I now feel I have to put my thoughts down so that they can be criticised.

Bad Examples;

  // adds old sales and new sales to get total sales
  totalSales = oldSales + newSales;

  // sends Hello World to the screen
  cout << "Hello World" << endl;

  return(true);  // return statement

and what I consider a good example,

  // this function is specific to DOS enviroments.
  // it generates a software interrupt
  // making calls directly to the BIOS
  c.index = int86(0x16, &r, &r);

I consider the first examples bad because they describe exactly what the code is saying in repetitive verse and contribute nothing constructive towards enlightenment, however they are useful at the beginning of the said learning process, when everything is new and being verbose is acceptable, which is where we all start before reaching the intermediate levels.

I consider the last one good because it describes exactly what will happen which is not obvious from the code and is therefore useful in being able to follow on through what ever processes are likely to occur later on in the program. It has been said that bad commenting can be destructive and I only feel that this is the case where the commentator has not grasped the logic of the problem being solved, perhaps this is because there are two involved i.e., a programmer and a commentator, but I would expect this to be unusual.

I think you can avoid errors if you comment code while working on it, and I don't mean great reams of explanation, but small snippets that will be useful when looking back at the code in a few days time. There are two common mistakes that many of us make: assuming no one else will read your code (in the case of a hobbyist this might be true), that you will always remember what you wrote and why in the future. Comments enhance the quality of the code that we produce and benefit everyone who follows along the path of programming, and I hope that it will continue to do so.

My perspective is that comments need to add enough value so that you do not stop reading them. Every weak comment adds to the likelyhood that all comments will be ignored.