Comments, Whitespace and Code a Human Can Read

Amara and Kenji hand in the same tile-ordering program. Both compile with no warnings. Both print the right answer.

Amara's takes ten seconds to read. Kenji's takes ten minutes, and he wrote it yesterday. Nothing in this lesson changes what a program does; all of it changes how long the next person needs to understand it.

The compiler is the one reader in your life who never complains about your style. Every other reader does, and one of them is you in six months.

Two comment styles, and where each one fits

A comment is a note for humans. The preprocessor removes every comment before the compiler sees your code, so a comment can never change what a program does.

C gives you two forms.

// runs to the end of the line. It came in with C99, and it is what you want for a short note beside a line or above a small group of lines.

/* ... */ can span as many lines as you like, and it ends only when you close it. Use it for a paragraph at the top of a file or a function.

Two rules come with the second form. It does not nest, so the first */ closes it. And if you forget the */ entirely, GCC says error: unterminated comment and everything after your /* has silently become a comment.

So // is for a sentence and /* */ is for a paragraph, and an unclosed /* can swallow a whole function.

A comment says why, not what

This is the one rule that separates a useful comment from noise. The code already says what it does. A comment earns its place by saying something the code cannot.

Noise, and everybody writes it at first:

total = total + marks;   /* add marks to total */

Useful, because it explains a decision:

total = total + marks;   /* the retake mark replaces nothing, it stacks */

Four kinds of comment are almost always worth writing. Why this approach and not the obvious one. Where a number came from. What a line assumes about its input. And a warning to the next person about a trap.

One kind is always worth deleting: a comment that repeats the line beside it. It doubles the reading and it goes stale the moment the line changes.

So if a comment would survive being read out with the code hidden, it is probably saying something useful.

Names: the cheapest documentation there is

A name is a comment that the compiler checks for you, because a wrong name is still spelled the same way everywhere.

C allows letters, digits and the underscore in a name, and a name may not start with a digit. That leaves you a choice of style, and this track uses snake_case: small letters with underscores between words, as in total_marks and boxes_needed.

Three tests for a name:

• Would a stranger guess what it holds? total_score yes, ts no.
• Does it say the unit or the kind? delay_seconds beats delay, and is_valid beats flag.
• Is it honest? A variable called area that holds a perimeter is worse than one called x, because it tells the reader something false.

Short names are fine for short lives. A loop counter called i is a tradition, not a failure, because it exists for three lines. A variable that lives for fifty lines earns fifty characters of thought.

So a good name removes the need for a comment, and a bad name cannot be rescued by one.

Indentation and braces: the one style this track uses

The compiler ignores your layout completely. Every line below is the same program to it, and only one of them is a program you want to inherit.

This track uses one style, stated once, so that every example you read is laid out the same way:

• Four spaces per level of indentation, never a tab, and never a mix of the two.
• The opening brace of a function on its own line, and its closing brace in the first column.
• One statement per line. Two statements on one line save nothing and hide one of them.
• A blank line between groups of related lines, the way paragraphs work in a book.
• A space around every binary operator: a * b, not a*b.

Other projects choose differently, and they are not wrong. The Linux kernel uses tabs eight wide and puts the brace on the same line. What matters is that a file, and ideally a project, picks one and never argues again.

So the style you use is a decision you make once, and the one thing that is always wrong is two styles in one file.

Whitespace the compiler ignores, and the reader does not

Whitespace means spaces, tabs and blank lines. Between tokens, C treats any amount of it as one separator, so int a = 5; and int a=5; are identical to the compiler.

Two places where it is not free. You cannot split a keyword or a name, so in t a; is an error. And inside a string literal, every space is a real character that gets printed.

The useful consequence: you can spread one long statement over several lines to line up its parts. The compiler will not mind at all.

So layout is for the reader, with exactly two places where the compiler is watching.

One honest note about this track

Every program in this track was compiled and run before it was published, and the output blocks are real output, not predictions. The tool that does it is verify-code.mjs, and it compiles every code block in both languages.

If a program here misbehaves for you, look first for a typing mistake, then tell us. That is the same promise the printed book makes. It is why you can trust an output block enough to compare yours against it.

// A single-line comment. Runs to the end of this line.

/* A block comment.
   It can span as many lines as you like,
   and it ends only when you close it. */

int marks = 90;   // a comment may sit after code too

#include <stdio.h>
int main(void){int l=5;int w=3;int a=l*w;printf("Order %d boxes\n",a);return 0;}

Order 15 boxes

#include <stdio.h>

int main(void)
{
    int room_length = 5;
    int room_width = 3;

    int boxes_needed = room_length * room_width;

    printf("Order %d boxes\n", boxes_needed);
    return 0;
}

Order 15 boxes

#include <stdio.h>

int main(void)
{
    /* Room measurements in metres, from the site survey of 12 March.
       Both are whole numbers because the supplier only cuts to the metre. */
    int room_length = 5;
    int room_width = 3;

    /* Tiles ship in boxes of one square metre, so the area is the box count. */
    int boxes_needed = room_length * room_width;

    printf("Order %d boxes\n", boxes_needed);   // the shop wants boxes, not area
    return 0;
}

Order 15 boxes

i = i + 1;   /* add one to i */

/* fix this later
    printf("Order %d boxes\n", boxes_needed);
    return 0;
}

/* Boxes of half a square metre each. */
int boxes_needed = room_length * room_width;

int main(void)
{
    int a = 1;
	int b = 2;
        int c = 3;
}

#include <stdio.h>

int main(void)
{
    /* Marks out of 50, doubled to give a percentage. */
    int physics = 37;
    int chemistry = 41;

    /* Average of the two subjects. */
    int total = physics + chemistry;

    printf("%d\n", total * 2);
    return 0;
}

#include <stdio.h>
int main(void){int p=37;int c=41;int t=p+c;printf("Total %d\n",t);printf("Subjects 2\n");return 0;}

#include <stdio.h>

int main(void)
{
    int reading = 512;
    int calibrated = reading - 12;
    int percent = calibrated / 5;

    printf("Tank at %d percent\n", percent);
    return 0;
}

Next you will compile and run a program yourself, in the Playground and, if you want, on your own machine with gcc.