Comments

You may have noticed lines like these:

// lives at the start of the game

// the player loses one life

// the player picks up an extra life

When you write two slashes like this // followed by some text, you're adding an explanatory comment. Zig ignores these lines when compiling, but your future self (and anyone else reading your code) will thank you. A few days from now, when the details are less fresh in your mind, those comments can save you a lot of time.

Writing comments is good practice. That said, if a comment gets too long, it might mean you're being overly explicit - or maybe the code itself is too complex. In that case, ask yourself whether your variable, constant, or function names are truly self-explanatory. If not, consider simplifying or rethinking how you're doing things.

Don’t worry - modifying and reworking source code is something everyone does. Programming is an iterative process.

If you write comments like these:

/// This program tries to predict

/// the future of humanity, therefore...

or like this:

//! This is yet another attempt to write the program

//! that predicts the future. The last one failed,

//! but I'm sure this time...

Zig uses them for automatic documentation generation, through its build system, something we’ll cover in one of the final chapters of the book.

Also, this type of comment can only be used in very specific places in the code, so for now, we’ll set them aside.