Game Programming Basics - Learning C# by Programming Games - page 37

3.4 Program Layout

3.4.1 Comments

For the human reader of a program (another programmer, or yourself in a couple
of months, when you have forgotten the details of how your program worked), it
can be very useful to add some clarifying comments to a program. These comments
are completely ignored by the compiler, but it makes for a more understandable
program. There are two ways in C# to mark comments in your code:

• everything between the symbol combination / ∗ and ∗ / is ignored (can be multiple

lines of comments)

• everything between the symbol combination // and the end of the line is ignored

It is useful to place comments in your code to explain groups of instructions belong-
ing together, the meaning of parameters, or complete classes. If you use comments,
do it to clarify the code, not to write the code again but in words: you can assume
that the reader of your code knows C#. To illustrate this, the following comment line
adds to the clarity of the instruction:

// Set the background color to olive green.
GraphicsDevice.Clear(Color.Olive);

This line is also a comment, but it does not clarify what the instruction does:

// Pass the value Color.Olive to the Clear method of the graphics device.
GraphicsDevice.Clear(Color.Olive);

While testing your program, you can also use comment symbols to temporarily
remove instructions from the program. Do not forget to remove these parts of your
code that are commented out once you finish the program, because they can lead to
confusion when other developers look at your source code.

3.4.2 Layout

There are no strict rules about how to distribute the text of a C# program over the
lines in a text file. Usually, we write every instruction on a separate line, even though
this is not necessary for the compiler to understand the program. Sometimes, if it
makes a program clearer, the programmer will write multiple instructions on a single
line. Also, sometimes a single instruction that is very long (containing method calls,
and many different parameters) can be distributed over multiple lines (we will see
this later on in this topic as well).