Still write programs in C.

2.5. Rules for writing C programs

formatting

C is an unformatted language. This means that there are hardly any restrictions on the external design of C programs and that it is the responsibility of the programmer to ensure that his programs look good. The C compiler is fairly undemanding when it comes to the clarity of the programs. For your own sake, however, you should ensure that the program code is easy to read. Freedom of format means in particular that a line break is not interpreted as the end of an instruction, as in some other programming languages ​​(e.g. BASIC). The following versions of our "Hello world"Programs are equally acceptable to the C compiler, albeit more difficult to read for humans:

Insisting on the readability of programs is more than just an exaggerated love of order: Contrary to popular belief, most programmers spend most of their time not writing new programs, but maintaining, developing and debugging existing programs. Confusing and cryptically written code embarrassed the author after just a few weeks when reviewing his own work. It is even more an unpleasant task to understand poorly readable program code of others. Creating maintenance-friendly programs begins with following a few basic rules when formatting the source code:

  • Tabs should consistently be set to a certain number of spaces. A value of 4 spaces per tab is recommended.
  • Most style guides stipulate that program blocks must be indented according to their logical affiliation. You should place the opening and closing brackets of a block in such a way that its beginning and end are easily visible. Whether the opening curly bracket is on its own line or directly follows the function arguments or loop instructions is a matter of taste. It is only important that you consistently adhere to the spelling that you have chosen.
  • Lines should not exceed a length of 80 characters (this is the value that can be displayed on a page in the usual screen display).
  • Especially with complex code, curly brackets should, if possible, be provided with a comment that provides information about the purpose of the program block at hand. .
  • The generous use of blank lines does the rest to make the program more readable.

Commenting

There are two types of programs: intelligible and incomprehensible. In order not to produce a program of the second kind, in addition to a clear programming style and clear formatting, abundant and meaningful comments are required. It is better to state in comments why you are using this or that instruction rather than specifying what the instruction does. For example, it is relatively easy to see from program code that the value of a variable is being increased; what is more important in understanding why it is increased.

Most programmers swear by their own formatting and commenting habits; Nevertheless, the common forms of designing the C source text are ultimately reduced to a few basic patterns. The design proposals presented here are therefore not to be understood as rules, but as recommendations. The rule, however, is that a program must be as clear and precise as possible.

Every program should begin with a comment that explains what the program is called, what it does, and how it is used. Depending on the context in which the program is created, the name of the author, the date of the last change and any additional explanatory notes should appear in the first comment box. It goes without saying that different standards apply here for the hobby programmer than for the professional software developer.

The beginning of program blocks should also be provided with comments that explain what to expect in the next section. Likewise, before defining functions, it should be made clear what the function does and which arguments are passed to it. When defining variables, it is also helpful if explanations show what the respective variables are all about.

Since the program source texts are plain text files, there is no possibility of highlighting text by italics, bold print, underlining etc. Alternatively, the use of comment boxes, the use of arrows and the drawing of lines are available to give comments the necessary attention to be sent.

Comment characters are also often used to "hide" parts of the program code from the compiler that still require revision; this procedure is called "commenting out". It must be ensured that such a commented out C code does not contain any comments (or comment characters), because C does not allow the nesting of comments.

Names for variables and functions

In C, variable and function names are combinations of letters and numbers, with the first character being a letter. The underscore "_", which is treated as a letter and can therefore also appear as the first character of a name, is also permitted. The reserved words of C itself are excluded from the assignment of variable and function names.

Valid names are, for example:

Invalid names are on the other hand:

The ANSI standard requires that a C compiler differentiate between the first 31 characters of names used internally; Due to the limitations of some linkers, only 6 characters are required for external names (names that were defined in other C source files). In practice, this means that problems can arise when referring to external names if only the first 6 characters are considered significant. In any case, it should be tried out or the documentation should be used to find out where the limits of the linker are. Most modern C development systems go far beyond this very low minimum set by ANSI. In any case, there is no reason to be dissuaded from assigning long, self-documenting function names.

It is noticeable that in our "Hello world" program both function names, namely main () and printf (), are in lower case. It is essential to pay attention to the spelling when using function and variable names, as C distinguishes between upper and lower case - or, as it is called in English, case-sensitive is. PRINTF (), Printf () and printf () are therefore three different functions for the C compiler.

However, not all linkers are case-sensitive. However, if this is the case with a linker, it would fail because of the PRINTF () function: After all, the standard C function stored in one of the libraries is called printf (). If the linker does not differentiate between the spelling, it would bind functions whose names differ only in upper and lower case to the program at random. When calling standard library functions, the spelling must be strictly adhered to, and it is lower case by default. Any name can be chosen when assigning names for self-defined functions. The names of various functions and variables should not only differ in their spelling.

Several conventions have meanwhile become established for assigning informative variable names. Which one you want to follow is largely a matter of taste, even if the representatives of the different spellings are often firmly convinced of the superiority of their system. It is only important that one consistently adheres to the method of naming that has been chosen, so that programs obey a consistent principle for function and variable names and are therefore easier to understand.

Easily understandable names are similar in that they use prefixes or suffixes to document the type of the variable. The standard prefixes and suffixes _ptr (for pointers, e.g. next_ptr), _p (also for pointer), _file (Variables of the type * FILE, e.g. in_file) or n_ (for number, e.g. n_Sign) developed.

As an alternative to the affixes just mentioned, which are added to the name with an underscore, the so-called Hungarian notation is a good alternative: It was introduced by Microsoft during the development of Windows and is therefore sometimes referred to as Microsoft notation. This method also uses prefixes that designate the data type of variables or return values ​​(for functions). The name itself is in mixed spelling, with the first character of each partial word capitalized. (e.g. szFirstName).

The following table gives an overview of the most common Hungarian notation prefixes, of which, however, there is no complete list. The list given here has been compiled from various sources and cannot claim to be complete. Sometimes the same prefixes are used to designate different data types, which could lead to ambiguity problems.

The data types in capital letters are common substitute names for frequently used data types in C. In most C systems, these are predefined within definition files with the help of typedef or #define.

prefix Data type
cchar
by BYTE (unsigned char)
uch UCHAR (unsigned char)
sshort integer
n also for short int (conflicts with s)
usunsigned short int
iintegrity
uiunsigned int
w WORD (unsigned integer)
b BOOL (usigned short)
llong
ulunsigned long int
dw DWORD (unsigned long int)
x usually short int, for the x-coordinate of graphics
y usually short int, for the y-coordinate of graphics
H HANDLE (WORD)
fn Function, generally used for pointers to functions
s Strings (not necessarily NULL-terminated)
sz Character strings (NULL-terminated)
p pointer
lplong (or far) pointer
npshort (or near) pointer