This is the third article in the Making Sense of C series.
In the last article, we decided that we were going to come up with a way to add notes (more commonly known as comments, which we'll use throughout the rest of the series) to the file that our compiler was going to ignore. In practice, this will allow you to explain things about the code that won't be clear from reading the code itself. For example, you may need to explain the algorithm you're using, the structure of the code, why you did X instead of Y, etc., but the computer doesn't care. For this tutorial, I'm going to need to explain what certain lines of code are doing, and the best way to do so is to write a note near the line.
So now, you have a problem: you need to be able to write things that the compiler will ignore but other people can read, which we call comments.
Since our computer will only be able to process the keys on the keyboard, our file can only have the standard printable ASCII characters (though we'll probably add support for Unicode later after we invent it). Our only option is to mark the comments with a sequence of ASCII characters.
Since we haven't established what the language looks like, it could be anything.
Python and bash (which both came after
C), for instance, use
# to comment
out everything after it, which makes sense since many of the other symbols are
already used up.
HTML (which also came after
--> to comment out
everything between them, which makes sense since
the main metacharacters in html.
Dennis Ritchie (the guy who made
C) decided to support both single line (like
in python and bash) and multiline (like in html) comments in
Single line comments use
// and comment out the rest of the line while
multiline comments use
*/ and comment out anything between them.
Not commented out; // Commented out // Entire line is commented out. /* Also commented out but now it can go onto multiple lines. The compiler will never do anything with this line, but the person reading the source code will be able to see it. */
In the rest of the tutorial, I will mostly use comments to explain how
in the code.
The comments that have
// do stuff in them indicate that you could do
anything valid in
C that you want, so I can't be specific.
Comments should be used sparingly because your code should be clean enough to read on its own. Good code is self-documenting is thrown around so often that a version of it is in the Wikipedia article for comments in programming.
The Wikipedia article lists several use cases for comments, but I'll explain two easy ways to avoid using unnecessary comments:
arepresents the sum of the first five million digits of π. You should call it something like
sum_digits_of_pior shorten it to
sum_digitsif it's clear that you are referring to the digits of pi.
calculateunless it will just evaluate an arbitrary expression like a calculator would. If you have a function to calculate the sum of the first n digits of
pi, you should call it something like
sum_first_n_digits. Again, you can shorten it if it would still make sense in the context of the code.
k. If you need to use more than
k, you should probably stop and clean up your code.
Now, I want to make an explicit exception on what I've said about comments for your company policy. If your boss tells you to write a comment for every character on the screen, you write a comment for every character on the screen. Don't blame me if you get fired for not fulfilling a job requirement.
You may try to convince your boss that you shouldn't need to comment everything, but do what he or she says until your boss changes his or her mind.
Although I told you to use comments sparingly, I will use them frequently throughout this tutorial to help you better understand what's happening. If I were to write any of the code I'm going to write for actual use, I would have way fewer comments.
So far, we've decided that we're going to put our code into a file and give our
compiler the name of the file so it can turn it into machine code.
We've also established that if we don't want the compiler to read parts of the
file we give to it, we either use the character sequence
// to comment out the
rest of the line and the two character sequences
*/ to comment out
everything between them.
Our file should now look like
first statement; // Here's why I used the phrase "first statement" // instead of "statement one" second statement; third statement;
I decided to get comments out of the way early on because you don't need to know
C to understand comments and because I'll need to use them
throughout the tutorial to explain what code does.
In the next article, we're going to be Coming Up with Our First Program in
C, which will help us figure out what features we need to implement in