Introduction to C programming/Lectures/Readability

For any code that isn't one use then throw away (and trust me- there really is very little of that), the most important thing you can do to make your life easier is to keep the code readable. If its easily read, its more easily maintained. If its more easily maintained, your life will be much more pleasant in a year when you have to fix a bug. There are 4 key items in keeping code readable- good names, commenting, formatting, and good design. The last requires a bit of experience to do. And since I harped on names in the Variables lesson, and will again in the future, the point of this lesson will fall on the other two.

Comments

Comments are lines of text in your source code that the compiler doesn't execute. Comments can contain anything you want- ascii art, paragraphs of text, single sentences, math formulas. It allows you to stick an explanation into your code, so you can remember what you were doing and why you were doing it when you come back to it later.

Multiline vs Single line comments

C supports two types of comments- single line and multiline. Single line comments do just what they sound like- they make the rest of the line they're on a comment. A single line coment looks like this:

//This is a comment

You can put code and a comment on the same line, like this:

statement; //This is a comment

If you do that, the comment should explain the line. I would suggest not doing this, it can be very hard to read.

A multiline comment allows you to write more than 1 line of comments. This is useful for paragraphs of information. A multiline comment looks like this

/*Comment line 1
Comment line 2
Comment Line 3*/

You don't actually have to use multiple lines- anything from the opening /* to the next */ is commented, regardless of where it is.

What to comment

The hard part of commenting is learning what to comment, and what not to comment. Beginners typically fall into two groups- those that comment everything (this is bad, because it starts to get annoying to both write and read the comment) and those that comment nothing (this is bad, because instructors can't know what you were trying to do and because 6 months from now you can't understand it either). Since the first group can be difficult to understand, here's an example of bad commenting that I've actually seen. In this code, we are trying to average 5 numbers.

total = number1; //Set total to number 1
total += number2; //Add number 2 to total
total += number3; //Add number 3 to total
total += number4; //Add number 4 to total
total += number5; //Add number 5 to total
total /=5; //Divide total by 5

All those comments, and not one of them actually tells us what the code does! Now here's the right way to do it:

/*Average number1 through number5*/
total = number1; 
total += number2; 
total += number3; 
total += number4; 
total += number5; 
total /=5; 

Now you know what the code is trying to do. Much better.

The general rule of thumb I follow is- comment what, not how. That means comment what you are trying to do (average numbers, read data from a file, create a network connection) not how you are doing it (adding numbers together, dividing by 5). If you follow this, you should have a decent understanding of what code does by reading the comments. And you should have a much easier time debugging as well- if the code doesn't seem to be doing what the comment says it should be, one of the two is wrong.

Keeping comments up to date

Sometimes, when you debug a program you change how it works. Its essential that when you do so, you make sure that the comments still match up correctly with the code. If you don't, the comments and the code get out of sync, and debugging the mess in the future becomes much more difficult. Remember, if you fix the code but not the comments, you've only done half the job!

Formating

The other major thing you can do to keep it readable is to format it nicely. The main thing you can do there is to change your spacing, both horizontally and vertically.

Vertical spacing

If all your text is scrunched up on top of each other, its hard to read. Luckily C doesn't force you to do that, C allows you to insert blank lines anywhere you want (the only exception is in the middle of a string constant). The best thing to do is to use blank space to separate different bits of work. To keep up with the example from commenting, if I averaged 5 numbers then used then compared it to a national average, I'd insert a few blank lines between the averaging and comparing, to keep it pretty. It works out nicely this way- you can tell when a program is changing gears by looking at the blank lines.

Horizontal spacing

You can also space things over as far as you want horizontally- either with spaces or tabs. You shouldn't do this however you like though. You may have noticed that whenever I wrote my if statements in the last lecture, I wrote them like this:

if(condition){
  statement;
  if(condition 2){
    statement 2;
  }
}

Notice how the statements are indented. You can tell what if they belong to by looking at the spacing. This is the default around the programming world. Write like this, and your code will be much more readable to others. How many spaces you use per block is up to you- 2-4 or 1 tab is normal. Just keep it the same throughout your code, and you'll be fine.

Operator spacing

You'll notice in a lot of code, people will put spaces around operators. For example, they'll use this:

a = 1;

instead of:

a=1;

Either way is fine, but the second can be more readable on long lines.

Breaking up lines

When lines get very long, it can be annoying to read them. People don't like to scroll horizontally for some reason. To avoid this, you can break up a line. For example this:

a=number1+number2+number3+number4+number5+number6+number7+number8;

can become

a=number1+number2+number3+number4+
      number5+number6+number7+number8;

The only general rule to follow when you do that is that the second line should be indented, and it should be indented in such a way its easy to realize it isn't a new block. Typically you do that by indenting it farther, like I did here.