Provide readable comments that explain in plain language (non-C++) what's going on. 

Suppose that your car breaks down in the middle of nowhere with no other cars in sight. The problem is not tools or parts; they are in the trunk. The problem is that you know absolutely nothing about the car, and when you open the trunk, you have no clue as to where the parts go or how to fix the problem. 

Just about to despair, you glance down and see two car repair books in the trunk. You pick up the first one and realize that it is a book written by advanced, expert mechanics for advanced, expert mechanics. The book uses technical jargon you've never heard. You toss the worthless repair book over your shoulder and pick up the next book. The title is Car Repair for the Un-Mechanic. Glancing through the opening pages, you begin to smile. The second book assumes that you don't know a rotor widget #4 from a tactile stem #3B-7. The second book explains, in uncluttered and nonmechanical language and with a friendly style, exactly how to fix your problem. 

You find that the second book contains the very same facts that the first one does. Of course, the first book does not help your plight one bit. It teaches you nothing and explains nothing. It assumes that you know enough to write the book yourself. The second book explains every concept in easy-to-understand language, and in 10 minutes, you fix the car just in time to drive to the cafe across the street for dinner. (You thought you were in the middle of a desert or something?) 

Which of the following is true of this car story: 

  1. It has a point to it. 

  2. It mistakenly got mixed in with this book at the printer. 

  3. It proves that this book's author cannot focus on one subject for very long. 

Obviously, the story has a point (and also hints at number 3). The point is that people react much better to material that is not technically above their heads. Of course, any subject is easy if it is explained well enough. If thermonuclear space transportation were explained in a simple manner, you could understand it. 

By their very nature, Visual C++ programs are cryptic, even to established C++ programmers. As the previous lesson explained, programs rarely remain in one form. The life of a programmer includes not only writing new programs, but updating programs written earlier. As you write a Visual C++ program, add whitespace so that the program is easier to read. Even more important, add comments as well. 

Comments are not Visual C++ commands. As a matter of fact, Visual C++ ignores any and all comments in your programs. Comments are nothing more than messages that explain what the program does. Comments are for people, not for the computer. 

If your Visual C++ programs contain only Visual C++ code and no comments, they will be virtually impossible to figure out later. Remember that Visual C++ is cryptic and extremely difficult to read. Many companies that employ programmers require that their programmers put comments throughout every program they write. Why do you think these companies require comments? It is because people change, jobs change, and companies must ensure that a program written by one person can be understood by the next person. 

No comments: