What comments are
A comment is text in your source code that Swift deliberately ignores. It does nothing when the program runs. Comments are notes for people: why the code is written a certain way, what a section is for, or what to fix later. They also let you switch a line off temporarily without deleting it.
Swift has two kinds of ordinary comments.
Single-line comments
Type // and everything from there to the end of the line is ignored. The comment ends by itself at the line break, and the next line is code again:
// Next line will greet the user:
print("Hello user!")
Hello user!
A comment can also follow code on the same line. The code before // still runs:
print("Hello user!") // This line greets the user
print("This is not a comment!")
Hello user!
This is not a comment!
Multi-line comments
For longer notes, start with /* and end with */. Everything between them is ignored, however many lines it spans, including code:
/* This is a
multi-line comment
print("This will not run")
Next line will greet the user:
*/
print("Hello user!")
Hello user!
Swift allows multi-line comments to be nested, so a block that already contains a /* ... */ comment can be wrapped in another one:
/* outer /* inner */ still a comment */
print("end")
end
This makes it safe to comment out a chunk of code that already holds comments.
Commenting out code
Putting // at the start of a line turns that line off, which is handy when you are testing:
print("first")
// print("second")
print("third")
first
third
Gotchas
- Inside a string,
//is just text.print("a // b")printsa // b, because the characters are part of the string and not a comment. - Comments don't print. To show text in the console, use
print. A comment such as// Helloproduces no output. - A forgotten
*/. If a multi-line comment is never closed, everything after it is part of the comment, and the compiler reports an unterminated comment. - Comments that repeat the code.
// print a numberaboveprint(5)adds nothing. Write comments that explain why, or summarise what a block does.
Documentation comments
A comment that begins with three slashes, ///, is a documentation comment. It is still ignored when the program runs, but tools such as Xcode show it as help text for the function or type declared right below it:
/// Adds two numbers.
func add(_ a: Int, _ b: Int) -> Int {
return a + b
}
You will not need these in this lesson, but they are the standard way to describe a function in Swift code.
The exercise
The exercise gives a program that prints a few lines about a person called Andy. The task is to document it: on line 1, above the existing print lines, add a single-line comment that says Story of Andy. The comment is not printed, so do not use print. Start the line with //:
// Story of Andy
print("My name is Andy")
print("I started coding at 15 years old")
The program prints the same lines as before. The new line only helps the reader.
Key takeaways
- Comments are ignored by Swift and exist for readers.
//comments out the rest of the line./* ... */comments out everything between the markers, over any number of lines, and can be nested.///marks a documentation comment for the declaration below it.- Prefer comments that explain why the code does something.
