Computer programming is about learning how to solve problems with a computer – it's about how to get a computer to do all the tedious work for you. The basic development cycle, or process of writing a computer program, is to determine the steps that are necessary to solve the problem at hand and then tell the computer to perform those steps. Our first problem, as we begin exploring this process, is to learn how to write, build, run, and verify a minimal C program.

In this chapter, we will cover the following topics:

• Writing your first C program
• Understanding the program development cycle
• Creating, typing into a text editor, and saving your C program
• Compiling your first C program
• Running your program, verifying its result, and, if necessary, fixing it
• Exploring different commenting styles and using them
• Employing guided chaos, followed by careful observation for deeper learning

The knowledge gained with these topics will be essential for further progress. So, let's get started!

To complete this chapter and the rest of this book, you will need a running computer that has the following capabilities:

• A basic text editor that can save unformatted plain text
• A Terminal window where commands can be entered via the command line
• A compiler to build your C programs with

Each of these will be explained in more detail as we encounter them in this chapter.

The source code for this chapter can be found at https://github.com/PacktPublishing/Learn-C-Programming-Second-Edition. However, please make every effort to type the source code in yourself. Even if you find this frustrating at first, you will learn far more and learn far more quickly if you do all the code entry yourself.

We will begin with one of the simplest, most useful programs that can be created in C. This program was first used to introduce C by its creators, Brian W. Kernighan and Dennis M. Ritchie, in their now-classic work, The C Programming Language, which was published in 1978. The program prints a single line of output – the greeting Hello, world! – on the computer screen.

This simple program is important for several reasons. First, it gives us a flavor of what a C program is like, but more importantly, it proves that the necessary pieces of the development environment – the Operating System (OS), text editor, command-line interface, and compiler – are installed and working correctly on your computer system. Finally, it gives us a first taste of the basic programming development cycle. In the process of learning to program and, later, actually solving real problems with programming, you will repeat this cycle often. It is essential that you become both familiar and comfortable with this cycle.

This program is useful because it prints something out to the Terminal, also known as the console, telling us that it actually did something – it displays a message to us. We could write shorter programs in C, but they would not be of much use. Although we would be able to build and run them, we would have very little evidence that anything actually happened. So, here is your first C program. Throughout this book, and during the entirety of your programming experience, obtaining evidence of what actually happened is essential.

Since Kernighan and Ritchie introduced the Hello, world! program over 40 years ago, this simple program has been reused to introduce many programming languages and has been used in various settings. You can find variations of this program in Java, C++, Objective-C, Python, Ruby, and more. GitHub, an online source code repository, even introduces its website and its functions with a Hello World beginner's guide.

Hello, world!

Without further ado, here is the Hello, world! C program. It performs no calculations, nor does it accept any input. It only displays a short greeting and then ends, as follows:

#include <stdio.h>
int main()
{
    printf( "Hello, world!\n" );
    return 0;
}

Some minor details of this program have changed since it was first introduced. What is presented here will build and run with all C compilers that have been created in the last 30 years.

Before we get into the details of what each part of this program does, see whether you can identify which line of the program prints our greeting. You might find the punctuation peculiar; we will explain this in the next chapter. Additionally, notice how some punctuation marks come in pairs, while others do not. There are five paired and five unpaired punctuation marks in total. Can you identify them? (Note that we are not counting the punctuation, that is, the comma and exclamation point, in the Hello, world! message.)

There is another pairing in this simple program that is not so obvious at this time but one that we will explore further in the next chapter. As a hint, this pairing involves the int main() and return 0; lines.

Before we jump into creating, compiling, and running this program, we need to get an overview of the whole development process and the tools we'll be using.

Tip

If you are eager to begin creating your first program, you can jump ahead to the next section. If you do, please come back to the Understanding the program development cycle section to complete your understanding.

There are two main types of development environments:

• Interpreted: In an interpreted environment such as Python or Ruby, the program can be entered, line by line, and run at any point. Each line is evaluated and executed as it's entered, and the results are immediately returned to the console. Interpreted environments are dynamic because they provide immediate feedback and are useful for the rapid exploration of algorithms and program features. Programs entered here tend to require the interpreting environment to be running as well.
• Compiled: In a compiled environment, such as C, C++, C#, or Objective-C, programs are entered into one or more files, then compiled all at once, and if no errors are found, the program can be run as a whole. Each of these phases is distinct, with separate programs used for each phase. Compiled programs tend to execute faster since there is a separate, full compilation phase that can be run independently of the interpreting environment.

As with shampoo, where we are accustomed to wet hair, lather, rinse, and repeat, we will do the same with C – we will become familiar with the edit, compile, run, verify, and repeat cycle.

Edit

Programs are generated from text files whose filenames use predefined file extensions. These are known as source files or source code files. For C, the .c file extension indicates a C source code file. A .h extension (which is present in our Hello, world! program) indicates a C header file. The compiler looks for .c and .h files as it encounters them, and because each has a different purpose, it also treats each of them differently. Other languages have their own file extensions; the contents of a source code file should match the language that the compiler expects.

To create and modify C files, you will need a plain text editor. This is a program that allows you to open, modify, and save plain text without any formatting such as font size, font family, and font style. For instance, on Windows, Notepad is a plain text editor while Word is not. The plain text editor should have the following capabilities:

• File manipulation: This allows you to open a file, edit a file, save the file and any changes that have been made to it, and, finally, save the file with another name.
• The ability to navigate the file: This allows you to move up, down, left, or right to the beginning of the line, end of the line, beginning of the file, end of the file, and more.
• Text manipulation: This allows you to insert text, delete text, insert a line, delete a line, selection, cut, copy, paste, undo/redo, and more.
• Search and replace: This allows you to find text, replace text, and more.

The following capabilities are handy but not essential:

• Automatic indentation
• Syntax coloring for the specific programming language
• Automatic periodic saving

Almost any plain text editor will do. Do not get too caught up in the features of any given text editor. Some are better than others; some are free, while others are costly and might not immediately be worth the expense (perhaps later, one or more might be worthwhile but not at this time), and none will do 100% of what you might want them to do.

Here are some free plain text editors that are worth installing on your computer and trying out:

• Everywhere: Nano, which runs in a Terminal window; it has a moderate learning curve.
• Linux/Unix: This consists of the following:

a. Vim or vi: This runs in a Terminal window; it has a moderate learning curve. It is on every Linux/Unix system, so it's worth learning how to use its basic features.

b. gedit: This is a powerful general-purpose editor.

c. Emacs: This is an everything and the kitchen sink editor; it has a very large learning curve.

• Windows: This consists of the following:

a. Notepad: This is very simple – sometimes too simple for programming – but included in every Windows system.

b. Notepad++: This is a better version of Notepad with many features for programming.

• macOS only: This runs BBEdit (the free version), which is a full-featured GUI programming text editor.

There are many text editors, each with its own strengths and weaknesses. Pick a text editor and get used to it. Over time, as you use it more and more, it will become second nature.

Compile

The compiler is a program that takes input source code files – in our case, the .c and .h files – translates the textual source code found there into machine language, and links together all the predefined parts required to enable the program to run on our specific computer hardware and OS. It generates an executable file that consists of machine language.

Machine language is a series of instructions and data that a specific Central Processing Unit (CPU) knows how to fetch from the program execution stream and execute on the computer one by one. Each CPU has its own machine language or instruction set. By programming in a common language, such as C, the programmer is shielded from the details of machine language; that knowledge is embodied in the compiler.

Sometimes, assembler language is called machine language, but that is not quite accurate since assembler language still contains text and symbols, whereas machine language only consists of binary numbers. Today, very few people have the skills to read machine language directly; at one time, many more programmers were able to do it. Times have changed!

When we compile our programs, we invoke the compiler to process one or more source files. The result of this invocation is either a success and an executable file is generated, or it will identify the programming errors it found during compilation. Programming errors can range from a simple misspelling of names or omitted punctuation to more complex syntax errors. Typically, the compiler tries to make sense of any errors it finds; it attempts to provide useful information for the problem it has found. Note that try and attempts are merely goals; in reality, the compiler might spew many lines of error messages that originate from a single error. Furthermore, the compiler will process the entire source code when invoked. You might find many different errors in different parts of the program for each compiler invocation.

A complete, runnable program consists of our compiled source code – the code we write – and predefined compiled routines that come with the OS, that is, code written by the authors of the OS. The predefined program code is sometimes called the runtime library. It consists of a set of callable routines that know how to interact, in detail, with the various parts of the computer. For example, in Hello, world!, we don't have to know the detailed instructions to send characters to the computer's screen – we can simply call a predefined function, printf();, to do it for us. printf() is part of the C runtime library, along with many other routines, as we will discover later. In the next chapter, we will explore the role of functions. How text is sent to the console is likely to be different for each OS, even if those OSes run on the same hardware. So, the programmers are shielded not only from the minutiae of the machine language, but they are also shielded from the varying implementation details of the computer itself.

It follows from this that for each OS, there is a compiler and a runtime library specific to it. A compiler designed for one OS will most likely not work on a different OS. If, by chance, a compiler from one OS just happens to or even appears to run on a different OS, the resulting programs and their executions would be highly unpredictable. Mayhem is likely.

Many C compilers for every OS

You can learn C on many computer platforms. Common compilers in use on Unix and Linux OS are either the GNU Compiler Collection (GCC) or the LLVM compiler project, Clang. For Windows, GCC is available via the Cygwin project or the MinGW project. You could even learn C using a Raspberry Pi or Arduino, but this is not ideal because of the special considerations required for these minimal computer systems. It is recommended that you use a desktop computer since many more computer resources (such as memory, hard drive space, CPU capability, and more) are available on any such computer that can run a web browser.

Important Note

You should be aware that there are many variants of C. Typically, these are created by hardware vendors for the specific needs of their customers or by other groups who wish to retain extended features not approved in the standard specification.

Also, be aware that there are areas of the C specification that are undefined; that is, the standards committees have left those implementation details up to the creators of a given compiler for a given hardware system.

In this book, we will describe and focus strictly upon what the C standard provides. However, our approach will be such that we will emphasize how to verify program behavior so that we will always know when our program behaves differently. Because compilers are written by humans and not autogenerated from a specification, we subscribe to the guidance: trust but verify.

A note about Integrated Development Environments

On many OSes, the compiler is installed as a part of an Integrated Development Environment (IDE) for that OS. An IDE consists of a set of programs needed to create, build, and test programs for that OS. It manages one or more files associated with a program, has its own integrated text editor, can invoke the compiler and present its results, and can execute the compiled program. Typically, the programmer never leaves this environment while developing. Often, the IDE streamlines the production of a standalone working program.

There are many such IDEs – Microsoft's Windows-only Visual Studio, Microsoft's multiplatform Visual Studio Code, Apple's Xcode for macOS and other Apple hardware platforms, Eclipse Foundation's Eclipse, and Oracle's Netbeans, to name a few. Each of these IDEs can develop programs in a variety of languages. Nearly all of the programs used in this book were developed using a simple IDE named CodeRunner for macOS.

We will not use an IDE to learn C. In fact, at this stage of your learning, it is not advised for several reasons. To begin, learning and using an IDE can be a daunting learning task in and of itself. This task can and should be put off until you have more experience with each of the individual parts of the program development cycle. IDEs, while they have common functions, are sometimes implemented in vastly different ways with far too many different features to explore. Learn C first; then, you can learn an IDE for your desired environment later.

Installing a compiler on Linux, macOS, or Windows

Here are the steps to follow to install a C compiler on the major desktop computer environments – Linux, macOS, and Windows. For other platforms, you'll have to do some investigation to find the compiler you need. However, since those platforms want you to use them, they'll likely make those instructions easy to find and follow:

• For Linux, perform the following steps:

1. If you are running a Red Hat Package Manager (RPM)-based Linux, such as Red Hat, Fedora, or CentOS, enter the following command on the command line:

$ sudo yum group install development-tools

2. If you are running Debian Linux, open a Terminal window and enter the following command from the command line:

$ sudo apt-get install build-essential

3. Verify your installation by entering the following command on the command line:

$ cc --version

From the preceding command, you will observe that you likely have GCC or Clang. Either one is fine. You are now ready to compile C programs on your version of Linux.

• For macOS, perform the following steps:

1. Open Terminal.app and enter the following on the command line:

$ cc --version

2. If the development tools have not been installed yet, simply invoking the preceding command will guide you through their installation.

3. Once the installation is complete, close the Terminal window, open a new one, and enter the following:

$ cc --version

You are now ready to compile C programs on your version of macOS.

• For Windows, perform the following steps:

1. Install either Cygwin (http://www.cygwin.com) or MinGW (http://mingw-w64.org/) from their respective websites. Either one will work well. If you choose to install Cygwin, be sure to also install the extra package for the GCC. This will install a number of other necessary compilers and debugging programs with GCC.

2. Once the installation is complete, open Command Prompt and enter the following:

$ cc --version

You are now ready to compile C programs on your version of Windows.

Note that compilation is a two-part process – compiling and linking. Compiling involves syntax checking and converting source code into nearly complete executable code. In the linking phase, the nearly complete machine code is merged with the runtime library and becomes complete. Typically, when we invoke the compiler, the linker is also invoked. If the compiler phase succeeds (that is, with no errors), the linking phase is automatically invoked. Later, we will discover that we can get error messages from the compiler either at compile time – the compiling phase – or at link time – the linking phase – when all of the program's pieces are linked together.

We will learn how to invoke the compiler later when we compile our first program.

Throughout this book, once you have a working program, you will be directed to purposely break it – causing the compilation of your program to fail. This is so that you can start learning about the correlation of various program errors with compiler errors, so you will not be afraid of breaking your program. You will simply undo the change and success will be yours once more.

Run

Once compilation has been completed successfully, an executable file will be generated. This executable file, unless we provide an explicit name for it, will be named a.out. Typically, the executable file will be created in the same directory the compiler was invoked from. For the most part, we will make sure our current working directory has the same location as the source files.

Running an executable file is performed by invoking it from the command line. When invoked, the executable is loaded into the computer's memory and then becomes the CPU's program execution stream. Once loaded into memory, the CPU begins at the special reserved word, known as main(), and continues until either return; or a closing } character is encountered. The program stops and the executable is then unloaded from memory.

To run an executable, open Command Prompt (on Windows) or a Terminal window (on Linux and Mac), navigate with cd to the directory of the executable file, and simply enter the executable's name (for example, a.out or whatever you've specified).

Note

If you successfully navigate to the same location as the executable and you have verified it exists, but you get an error message from the command interpreter, you likely have a problem with your command interpreter's built-in PATH variable. To quickly work around this, enter the $ ./a.out command to run it. This instructs the command interpreter to look in the current directory for the file named a.out.

As the program runs, any output will be directed to the Terminal or console window. When the program has ended, the command interpreter will present you with a new command prompt.

Verify

At this point in the cycle, you might feel that simply getting your program to compile without errors and running it without crashing your computer means you are done. However, you are not. You must verify that what you think your program was supposed to do is what it actually did do. Did your program solve the problem it was intended to? Is the result correct?

So, you have to return to writing your original program and then compare that to the output your program gives. If your intended result matches, your program is correct; only then are you done.

As we get further into writing more complex programs, we will discover that a proper or good program exhibits each of the following qualities:

• Correct: The program does what it's supposed to do.
• Complete: The program does everything it's supposed to do.
• Concise: The program does no more than it's supposed to do and it does so as efficiently as possible.
• Clear: The program is easily understandable to those who use it and to those who must maintain it.

For most of this book, we will concern ourselves largely with correctness, completeness, and clarity. Currently, hello1.c is not complete, nor clear, and we will understand why shortly.

Repeat

Unlike our shampoo metaphor that we mentioned earlier, which was wet hair, lather, rinse, and repeat, instead of repeating the instructions just once, you will repeat this cycle multiple times.

Rarely will you be able to go through the program development cycle with only one iteration. Most likely, you have to will repeat parts of it many more times. For example, you might edit the source code, compile it, and find that the compiler failed. In this scenario, you will have to go back to edit the source code and compile it, each time figuring out what went wrong and then fixing it. Once it compiles successfully, you will move on to running and verifying it. If the output is not correct or the program crashes, you will have to figure out what went wrong and start editing the source code again.

Does this sound frustrating? It can be – especially when you don't know why something went wrong or you can't figure out what the compiler or computer is saying is wrong.

Many years ago, when compilers were simpler and not as forgiving as they are today (actually, compilers are still not very forgiving – they've just gotten better at figuring out what we humans might have done wrong with our programs and communicating it to us in better ways!), the very first time I attempted to compile my Hello, world! program on a Digital Equipment Virtual Address Extension (VAX) Virtual Memory System (VMS) C compiler, the compiler gave me 23 thousand error messages. It turns out that I had overlooked a single ; character somewhere. One character. Sheesh!

The point of that story is to reassure you that you will make mistakes, mostly missing or erroneous punctuation or misspelled variables, and you will get frustrated. Part of learning to program is learning how to deal with your frustration and how to become a sleuth to track down the picayune errors that will crop up.

When that happens, get up and take a break from the computer. Take a walk. Have a laugh. Then, get back to work. Don't omit the first parts (that is, laughing and walking around a bit).

A note about debugging

As you go through the program development cycle, and as you get more familiar with the development language, the development tools, and yourself (yes, you are learning about yourself while you program), this will all become second nature to you, as it should. When you make a typing error, or when you get an obviously incorrect result, these are not bugs – they are just mistakes. Bugs are far more subtle.

There is a deeper trap that is very difficult for most beginner programmers to see; that is, their assumptions about what should happen without any evidence of what did happen. Most of the most difficult bugs that I introduced in my code were those that I assumed the program would work on in a certain way, but I did not verify that. When I finally went back to my assumptions and proved them in code, I was able to get beyond my self-imposed bugs.

So, can you avoid this trap?

Yes. Throughout this book, we will attempt to mitigate this subtle problem with a method we will use to develop programs. As we proceed, we will use trial and error, guided discovery, and evidence through observation. Sometimes, we will purposefully break our programs to see what happens. Additionally, we will try to prove each concept so that the expected behavior matches the actual behavior.

This is not to say that even with such an approach, bugs won't creep in. They will. But with careful attention to your assumptions, observed behavior, and the collection of evidence that you have gathered to prove any assumption, most bugs can be avoided.

Now that we have introduced the program development cycles, you are now ready to write your first program. As you progress through this book, you will become very familiar with these cycles.

Let's begin creating our Hello, world! program.

Before we begin creating files, create a directory on your computer where you will save all of the work for this book. Perhaps you can create it in your $HOME directory or your Documents folder. My advice is to put it somewhere inside a user directory of your choice. Let's go ahead with our program:

1. Open Command Prompt, a Terminal window, or a console (depending on your OS).
2. Navigate to $HOME or ./Documents, or wherever you chose to work from, and create a directory for the programs that you'll write in this book. Do this with the following command:

   $ mkdir PacktLearnC

3. Make that directory your current working directory using the following command:

   $ cd PacktLearnC

4. Make a new directory for this chapter using the following command:

   $ mkdir Chapter1_HelloWorld

5. Make that directory your current working directory with the following command:

   $ cd Chapter1_HelloWorld

6. Picking the text editor of your choice – any will do – open the text editor either from the command line or the GUI (depending on both your OS and your preference of which one you wish to use).

From the command line, you might enter $ myEditor hello1.c, or just $ myEditor, and later, you will have to save the file as hello1.c in the current working directory.

7. Enter the following program text exactly, all while paying attention to spacing, {} versus () versus "" (these double quotation marks are the keys next to the ; and : keys) versus <>, with particular attention being paid to #, \, ., and ;:

   #include <stdio.h>
   int main()
   {
       printf( "Hello, world!\n" );
       return 0;
   }

8. Save your work and exit the editor.
9. Verify that hello1.c exists by listing the directory and verifying that its file size is not zero.

Congratulations! You have completed your first editing phase of the program development cycle.

Having successfully entered and saved your hello1.c file, it is now time to compile it:

1. In a Terminal, command-line, or console window (depending on your OS), with the current working directory the same as your hello1.c file, enter $ cc hello1.c.
2. Once this is done and you have a new command-line prompt, verify that you have a file named a.out.

You have completed your first compiling phase of the program development cycle.

Your hello1.c program has been successfully compiled, and you now have an a.out file in the same directory. It's time to run it! Let's get started:

1. In a Terminal, command-line, or console window (depending on your OS), navigate to the directory that holds a.out.
2. At the command prompt, usually indicated by a > character in the first column, enter ./a.out.
3. You should see Hello, world!.
4. If you see that, we can now verify the output of your program.
5. Note that the command prompt, $, is not on the same line as Hello, world!. This means you correctly entered \n in the output stream. If not, you need to re-edit hello1.c and make sure \n occurs immediately preceding the second ", recompile it, and rerun a.out.
6. If Hello, world! is on a line by itself with a command prompt before and after it – woo-hoo! You did it!

If everything works as it should, you should see the following output in your Terminal:

Figure 1.1 – A successful compilation and execution of hello1.c

In the screenshot of our Terminal session, > is the prompt the Terminal gives to indicate that it is ready to take input from us. After the first prompt, we have entered cc hello1.c followed by <return>. The fact that the very next thing we see is another prompt means that the compilation was successful, and we can now run the compiled program. We then enter a.out followed by <return> to execute hello1.c. We should see our desired message, Hello, world!, followed by a prompt awaiting Figure 1.1 – further input.

If the compiler spews out any error messages, read what the compiler is telling you and try to understand what error it is telling you to fix. Always focus on the very first error message, to begin with; later error messages are usually the result of the very first error. Then, go back to the editing phase and examine where your entered program is different from what has been shown here. The two must match exactly. Then, come back to this phase; hopefully, your program will compile successfully (that is, there will be no error messages).

It's always important to remember to do a little dance, and make a little joy, get down tonight! when you've successfully completed something. Programming can be very frustrating, so remembering to celebrate even your small successes will make your life a little bit more joyful through all the frustration. Too many programmers forget this incremental and regular step of celebrating with joy!

As we progress through this book, we'll add more compiler options to the cc command to make our life easier.

Tip

If you skipped over the Understanding the program development cycle section of this chapter, now would be a good time to read it before moving on.

A lot about writing good code is writing code in a consistent manner. Consistency makes it somewhat easier for the reader (or you) to comprehend at a later time. Consistency is very often a good thing. However, there might be times where we need to step out of that consistency, and for some good reason, when we write code, that code becomes particularly twisted or obtuse and difficult to understand. Or, we might write code a certain way that might not be obvious or might not be expected, again for good reason. It is in these circumstances that we should comment on our code – not for the compiler, but for ourselves and others who might be reading our code later, often much later, scratching our/their foreheads and thinking, What? What did I/they intend to do here?

Code comments are a way to explain why a particular piece of code is written in a certain way. Let's explore some of the different ways we can write code comments in C.

Comments in code, when done correctly, are ignored by the compiler. They are only for human edification. Consider the following code comments:

/* (1) A single-line C-style comment. */
/* (2) A multi-line
   C-style comment. */
/*
 * (3) A very common way to 
 * format a multi-line
 * C-Style comment.
 */
/* (4) C-style comments can appear almost anywhere. */
/*(5)*/ printf( /* Say hello. */ "Hello, world!\n" ); 
/*(6)*/ printf( "Hello, world!\n" ); /* Yay! */
// (7) A C++ style comment (terminated by End-of-Line).
   printf( "Hello, world!\n" ); // (8) Say hello; yay!
//
// (9) A more common way 
// of commenting with multi-line
// C++ style comments
// 
// (10) anything can appear after //, even /* ... */ and
// even more // after the first // but they will be 
// ignored because they are all in the comment.

The comments illustrated in the preceding code are not particularly useful comments, but they show various ways in which comments in C can be employed.

Comments with tags (1)–(6) are old-style C comments. The rules for these are simple – when /* is encountered, it is a comment until */ is subsequently encountered, whether it appears on the same line or several lines later. / * (with a space between them) and * / (with a space between them) are not valid comment indicators.

C comments that have been adopted from C++ are shown from tags (7) to (10). When // is encountered, it is a comment until an End Of Line (EOL) is encountered. Therefore, these comments cannot appear anywhere like C comments can. Likewise, / / (with a space between them) is not a valid comment indicator.

C comments are more flexible, while C++-style comments are more obvious. Both styles are useful. We'll use both throughout this book.

Now that we know the various ways we can format comments, let's consider some effective ways for using them.

Some guidelines on commenting code

One of the best guidelines for commenting in code is the same guideline to follow in life. This is sometimes called the Goldilocks Principle, also known as the Three Bears Principle, named after the children's fairy tale, Goldilocks and the Three Bears. The essence of this guideline is not too much; not too little; just right. However, just right is subjective, it depends on several factors, and will be different for each situation. Your own judgment and experience must be your guide to your Goldilock's moment.

Here is a list of essential guidelines to follow when commenting on your code:

• Assume the reader already knows the language: You are not teaching your reader how to code. Do not explain the obvious features of the language. You are explaining the non-obvious aspects of your code.
• Write in full sentences with proper capitalization and punctuation: Comments are not code. They are the words you are writing to yourself or other readers of your code. Your comments will be much less cryptic and more easily understood if you follow this guideline.
• Comment on unusual uses of the language: Every language has oddities and idiosyncrasies that might not be used often or might be used in unexpected ways. These should be clarified and highlighted.
• Try to comment in a way that is resilient to code changes: Very often, as code changes, comments are not necessarily updated to match those changes. One way to mitigate this issue is to put comments in globs at the beginning of functions or to precede blocks of code rather than them being interspersed within code blocks. This is so that if those code blocks change, the comments are still valid. You will see examples of how to do this throughout this book.
• Comment at a high level: Describe the intent of the code and the way it attempts to solve a problem. This guideline goes hand in hand with the first guideline we mentioned. The higher the level the comments are describing, the less likely they will need to be changed as the code changes.
• Convey your intent: With your comments, strive to convey the intent of the code you are writing, why the code is needed, and what the code is trying to accomplish. What the code is actually doing should come from the code itself.

I am often surprised when I revisit a piece of code I wrote 6 months ago. Too often, I find that I am scratching my head asking why did I do this? or what was I thinking here? (both are cases of too little commenting). I also find that when I change code, I have to delete numerous comments that are no longer necessary (a case of too much commenting). I rarely find that I have commented too much when I have focused on the intent of the code (what was I trying to do here).

At one point in my career, I came across a programmer whose comments were completely divorced from the code that was there. I concluded that this programmer initially intended their algorithm to work one way, but then modified the code so significantly that the comments no longer matched the actual code at all. When I saw that programmer's name in subsequent code, after careful inspection, I simply deleted the code comments because I found them to be irrelevant. Please do not do this unless you are absolutely certain you understand the code and that the comments do not match the code.

Learning how to effectively comment on code is a lifelong challenge. I do not suppose you will learn this quickly. You will learn this after years of examining your code and making your code clearer to yourself, let alone making your code clearer to others. As we work through various C example programs, I intend to demonstrate a variety of useful and resilient commenting techniques.

Adding comments to the Hello, world! program

Now that we have explored the various ways we can comment on code and commenting styles, let's copy hello1.c to hello2.c and add appropriate comments.

You can either copy hello1.c to hello2.c with your command interpreter or, in your editor, open hello1.c and immediately save it as hello2.c. Regardless of how you do this, you should have both hello1.c and hello2.c in your Chapter1_HelloWorld directory.

In your editor, modify hello2.c so that it appears as follows:

/*
 * hello2.c
 * My first C program with comments.
 * by <your name>
 * created yyyy/mm/dd
 */
#include <stdio.h>
int main()
{
    printf( "Hello, world!\n" );
    return 0;
}
/* eof */

Note how the * character at the beginning of each line providing a comment makes it clear that there are several lines of comments in a group; the group begins with /* and eventually ends with */. Compile, run, and verify this program. Make sure you haven't introduced an accidental character here or there, which is always possible and should always be verified.

This is now a complete program. We know from the evidence from hello1.c that the program is correct – it displays our intended message in the way we desire. The first six lines of comments provide minimal information about the program's author and the date it was written. This program's heading information can be simple or it can be more comprehensive. For now, we will keep such heading information simple.

The program itself is so simple that anyone who understands C would know that a simple message is printed. No further commenting is required here.

Finally, we mark the end of the file with a comment; the only benefit to such a marking is when there are multiple editor windows open and/or programs get very long. This simple demarcation lets us know we're at the EOF. This final EOF indicator is entirely optional and becomes more of a stylistic preference than a practice with rigorous rationale.

I have found that in every programming language I have used, my commenting style has adapted to the simplicity or obtuseness of the given language. When I programmed in assembler language at university or later in an early version of Fortran 4, I commented on almost every line. However, for C++ or Objective-C, I found I commented only sparsely or in globs – large sections of comments that explain a concept or programming solution.

Furthermore, even within a given language, when the problem being solved is unusual or I am using a novel approach to its solution, more comments are required.

In the remainder of this book, depending on the code sample, we'll explore various useful commenting practices that are effective, even when the code is subject to change.

Now that we have gotten our basic program to work (woo-hoo!), we can turn our attention to learning how to intentionally break it (ouch!). This is so that we can learn more about what the compiler is trying to tell us. What it is telling us isn't always clear, especially while we are learning.

Once you have mastered the language, there would be little need to do this (yay!). However, while we are learning the language, becoming familiar with the various kinds of compiler error messages is essential and, ultimately, will save us many hours/weeks of debugging, which might have been prevented early on in the iterative program development cycle. Please do not skip this essential step as you learn C as it will save you many hours/weeks.

So, using the full program development cycle outlined earlier, inject the following errors into your source file. When you see the error messages, try to correlate them with what you just did to cause them. After each one, correct the error and recompile it to verify the fix:

• Remove { from hello2.c. Save it and compile it. What errors does the compiler give?
• Put { back in its appropriate place and remove }. What errors does the compiler give?
• There are three other paired punctuation marks: <> and (), which occur twice, and "". What errors does the compiler give when you remove the opening of the pair and the closing of the pair? Put them back after each experiment.
• Remove ; from either line. What error messages does the compiler give?
• Comment out the return 0; line. What error messages does the compiler give?
• Change int main() to int MAIN(). What does the compiler tell you?
• Similarly, change printf( to printout(. With this error, you should be able to see what linker messages look like.
• Now, comment out #include <stdio.h>. You should also see linker errors telling you they can't find the printf() function.
• Return hello2.c to its original state. Compile, run, and verify the program is both correct and complete.

If you get more than 23,000 lines of error messages from the compiler, I would really like to know. Please email me with the details of your experiments.

Whew!

In this chapter, you've learned an enormous amount about the program development cycle and how to set up your C development environment. Getting Hello, world! to compile and run is a far larger accomplishment for beginners than they might imagine. You have a working text editor, a working compiler, and you've begun manipulating programs in a command-line interpreter. You have probably experienced frustration to an extent you've rarely experienced before. I, like many programmers before you, feel your pain. We have all lived that pain. And with luck, I'm here to help take some of that pain away. In the rest of this book, we'll explore various ways to optimize this whole experience.

You have begun to learn that programming is about solving problems. While we haven't solved many interesting programming problems yet, you are just beginning your journey from simple programs and problems to far more complex programs and problems. We'll encounter a few of these in later chapters.

Furthermore, you are now aware of ways to make your programs clearer to both yourself – especially months after you've written the code – and to others who might later be tasked with modifying your code for new demands.

To be sure, getting a C++, C#, Objective-C, or JavaScript environment up and running would be similar yet subtly different.

In the next chapter, we will go into much more detail about how Hello, world! works and then modify it in some interesting ways to learn about statements, blocks, and functions – the building blocks of larger and more interesting programs.

Woo-hoo! You did it! Isn't programming fun?