To program some of the very early computers, programmers had to rewire the machine. The programers got a large circuit board called a plug board, which was filled with little holes where they plugged in wires to create the program. Once they had programmed the board, they slid it into the computer and ran the program.
Computers soon evolved to the point where programmers could program them in text. They typed their program on a machine that output punched cards, dropped the thick deck of cards into the card reader, and the computer did the rest. Editing the program was as simple as replacing cards, but woe be to the programmer who dropped the program and scattered the cards.
Today we use text editors, which are certainly an improvement over punched cards and plug boards, but they do have their limitations. Knowing these limitations can help you to write code that will always be readable.
C can accept files of almost any size, but there are some practical limitations. The longer a file, the more time and effort it takes to edit and print it. Most editors tend to get a bit slow when the file size gets to be more than about 3,000 lines. Keep yours within this limit.
Not only are there length limitations, but width limits as well. The old punch cards contained 80 columns. Because of that, most terminals and printers at the time were limited to 80 columns. This limitation has carried over to present-day computers. For example, the PC screen is only 80 columns wide.
The code that fell off the right side is referred to as mystery code. So you need to limit the width of your program files to 80 characters. Actually, you need a slightly smaller limit. Program printers such as cpr print line numbered listings. Line numbers take up space, so a better limit, and one with enough history to be taken seriously, is 72 characters.
Early terminals had fixed tabs. Every eight characters you had a tab stop whether you liked it or not. You couldn't change them since they were built into the machine. This fixed tab size became an industry standard that is still in force today. If you type a file containing tabs under UNIX or DOS, the tabs come out every eight characters.
Many editors allow you to set your own tab stops. If you are programming in C with an indention size of 4, it is convenient to set the tab stop in your editor to 4. That way, to indent all you have to do is hit the Tab key. The problem with is that your tab setting is non-standard. If someone else edits your program, they won't know about your tabs and will assume that your code is indented strangely. Also, many printing programs and older programs default to a tab size of 8. Some, like DOS, can't be changed.
Note that tab size and indentation level are two different things. It is perfectly acceptable to use a tab size of 8 and an indentation level of 4. You would then use four spaces to reach the first level of indentation, a tab to reach the second, and so on.
Finally, there is the character set. There are 95 printing characters in the standard ASCII set. The PC extended this set to include foreign characters and a line drawing set. It is possible to use the PC character set to draw interesting shapes,
Well-written code can help a programmer understand what is going on, but the best form of communication is the comment. Comments are used to explain everything. Without comments, a programmer has to go through the long and painful process of decrypting the program to figure out what the heck it does.
The comment can convey a variety of information, including program design, coding details, tricks, traps, and sometimes even jokes. There are many types of comments, from important ones that you want make sure the programmer doesn't miss to explanations of the tiniest details.
The programmer, on the other hand, is limited to a single size, single face, monospaced font and personal imagination. Over the years a lot of imagination has been used to make up for the limitations of the medium.
Computers are becoming more and more graphically oriented. Screen layouts, windowing systems, and games all require sophisticated graphics. It's not possible to put graphic comments into a program yet, but you can make a good attempt by using ASCII line art.
Even with the crude drawing tools in the 95 standard ASCII characters, you can produce a recognizable picture. This type of comment actually conveys graphically the relationships among the constants shown.
If you do 1/0 programming, you know that hardware designers like to pack a lot of functions into a single byte. For example, the serial 1/0 chip that controls the COM ports on a PC contains a variety of packed registers.
These registers are documented in the chip's data sheet. Unfortunately, most programmers don't carry around a complete set of data sheets, so it is very useful to copy the register specification into the
This can be turned into a nice comment and a few defines. (How to write the #define statements is discussed in See Preprocessor .)
Here, the heading comments are boxed. This not only makes them stand out, but it easily identifies them as containing important and generally useful information. The first line of the heading block contains the name of the program and a short description of what it does.
Sometimes a programmer discovers the hard way that his program contains traps or pitfalls. This section should warn about potential problems. For example: "Don't compile with stack checking on. This is a clever program, and it does strange things with the stack."
Briefly explain how to use the program. Oualline's law of documental states: 90 percent of the time, the documentation is lost. Of the remaining 10 percent, 9 percent of the time the documentation is for a different version of the software and is completely useless. The 1 percent of the time you have the correct documentation, it is written in Chinese.
This section lists any restrictions that the program might have, such as "This program is designed to process the output of PLOT5 program. It does not do extensive error checking and may behave strangely if given bad input."
Often a programmer will find it useful to copy or adapt an algorithm from a book or other source (as long as copyright laws are not violated). But give credit where credit is due. Listing the source of any special algorithms in this section gives the people who follow you a chance to check the original work.
it's not unusual for a number of people to work on a single program over the years. This section lists those who worked on the program, gives a short description of what they did, and tells when the work was done. Revision control software such as RCS and SCCS will automatically generate this information.
This particular example is a bit long. It was created to show practical uses of every section. But it illustrates a problem with style guidelines: there is a strong temptation to overdo it. All too often, a programming team will form a style committee, toss around a bunch of ideas for documenting the code, and end up throwing them all into the header. This is almost guaranteed to produce confusing headers that are themselves a maintenance headache.
Too much information is a burden on the programmer. It takes time to type it in and to maintain it. Comments that take a lot of time to create and maintain tempt the programmer to take shortcuts. The result is incorrect or misleading comments, and a wrong comment is worse than no comment at all .
We've listed a general set of heading sections. You may need additional sections, depending on your environment. For example, a student may be required to put in an assignment number, social security number, and teacher's name. Professional programs may require a part number. Shareware must include a paragraph that asks the user to pay a license fee, along with an address to which users can send money.
Some programmers put a list of the public functions in the heading comments. This is not recommended. First, all the public functions are already listed in the header file for this module. Second, keeping this list up to date requires work, and frequently a programmer will forget to make the updates.
Some people include another section: Globals Used. This is very useful information, but it is difficult to get and maintain. It takes a lot of work to keep this section current, and frequently a programmer will get lazy and ignore it. It is better not to have a Globals Used section than to have one that is wrong.
It is best to put your comments in the program as you are writing it. If you start your program with a set of heading comments, then you should have a pretty good idea what you are planning to do. It helps focus your thoughts.
Avoid the two-step process of coding and later going back and adding comments. This method has several problems. First, you are likely to forget what you did. What may be obvious when you write it may not be so obvious when you re-read it.
Another good reason to write comments while you're writing the code is psychological. When the code is done, you're probably going to feel that the program is done. Adding comments then becomes a chore to be completed as quickly as possible. Generally, this means you'll put in too few comments.
The heading comments always seem a bit long to the person creating the program. To the person trying to maintain it, they always seem far too short. Balance is the key to good commenting. Make your comments short enough so they aren't bothersome to put in, yet long enough to give other programmers a good idea of what's going on.