Commenting in Swift

// Don’t run this line!

Image for post
Image for post
Photo by Mika Baumeister on Unsplash

Look, documentation and commenting of code is extremely important. You should be doing it. You should be doing it now.

Not sure how? Read on and find out about single line comments, multiline comments, nested comments and how comments can help you when you option-select your function.

Difficulty: Beginner | Easy | Normal | Challenging

Prerequisites:

  • Be able to produce a “Hello, World!” iOS application (guide HERE)

OR

  • Use Swift Playgrounds to follow with the code (guide HERE)

Terminology

Comments: A way of including text in your code that will not be executed by the compiler

Compiler: A program that converts instructions into a machine-code or lower-level form so that they can be read and executed by a computer

Documentation: Text (or diagrams) to describe computer code

Forward slash: The / character

Function: A group of statements that together can perform a function

You SHOULD be writing code that isn’t executed…WHAAA

You might be wondering why you would ever want to include text that isn’t run as code.

The reason is actually quite simple. Code is for computers, and is often prized for brevity, maintainability and simplicity. Now I have missed out another of the advantages of well-written code, and that is self-documenting code.

Self-documenting code is code that is human readable and easy to understand for, well, humans.

This means your code should be perfect in many respects.

Can you see the possible issue here?

Yes. You aren’t perfect. You…aren’t perfect. You make mistakes and it is difficult to do everything in a perfect manner.

So your code might not be perfectly logical for the reader of your code. This might even be because what you want iOS to do is quite difficult and complicated (business logic can actually be tricky sometimes, and sometimes that is nobody’s fault).

To help people out reading your code you might want to feature documentation. iOS won’t be interested in your amusing / helpful witterings but your colleagues certainly will not only be interested but grateful for your help and the care you have taken in making your code interesting to understand!

Basic comments

There should be no problem here. Swift knows to ignore lines that are proceeded by two forward slashes, that is a line is a comment if it has // in front of it .

So the following will, do absolutely nothing. Now do bear in mind that if you usually typed in some normal human-readable text, the Swift compiler would give a rather upsetting error:

// This is ignored

this even works with code that would usually be executed. So a print statement will no longer run

// print ("This will never print")

because it is proceeded by the secret code — the double forward slash // makes that line a comment.

Multiline comments

If you have a great deal of comments to make something particularly clear to a human Swift has you covered. Well, of course you could proceed multiple lines with the double backslash, I do appreciate that. However, It is easier to have one start symbol for the comment, and one symbol for the end of the comment.

Start of comment: /*

End of comment: */

This means that you can write a whole host of things between those two symbols, and be very happy about it.

/*
This is an example of a multiline comment
so the next print statement will not actually print anything
print ("will not print")
*/

Nested Multiline comments

Why would you need to do this? Probably you’d be copy and pasting things around your code and put a comment within a comment.

Who wouldn’t want their life to be easier?

/*
This is an example of a multiline comment
so the next print statement will not actually print anything
print ("will not print")
/*
This beautiful comment is within the other one, which is just above it.
Ok?
*/
*/

Commenting your code

Option-Command-/ is your shortcut to commenting nirvana.

You’ll want to select a property (the start of the line is ideal) and then press Option-Command-/ to add a rather attractive comment (this particular comment has /// at the beginning).

Image for post
Image for post

The same can be done with functions. So if we have a simple function it will add /// at the beginning when we press Option-Command too.

Image for post
Image for post

Now there is a more interesting type of function. The following example has both input parameters and output parameters.

func takeInputProcessToOutput(input: String) -> String {
return "This is the output: " + input
}

Now we would need to describe the input and output parameters for the function. This would help future programmers (or yourself in the future, because you are going to forget, remember!) to know how the function is used and even what it does (although technically your name of the function should make this clear).

Image for post
Image for post

Now the best part of all. You can find out information about any function using the Swift compiler by pressing option on the keyboard while clicking on the function. When you do that, you get information about the function (actually the comments that are written above).

Image for post
Image for post

Commenting your code — Some rules

  • When you are using comments make sure that every comment only as complex as it needs to be — simplicity is key. You’re trying to make things as easy as possible
  • Use multiline comments where necessary
  • Use comments, but don’t overuse them. Don’t write comments which aren’t needed.
  • Use comments on the same line as active code
  • Don’t duplicate the code in your comments. Comments add why the code works, well-written code should describe how
  • Comment code even if you are a lone developer. Treat yourself as a colleague, which makes alot of sense as you’ll not remember anything of now in the future

Extend your knowledge

  • Apple have a nice document about comments right (HERE)

The Twitter contact:

Any questions? You can get in touch with me here

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store