How to create Swift Comment and what is it for?

Swift Comment

Tested on: Xcode 12.2, Swift 5.3

Comment allows you to document your code and tell other developer or the future you what the code means when you look back on it. This helps you understand why you wrote a certain code in this way. Similar to other programming languages, comments allow you to document your code.

By writing a comment, Swift compiler will only run Swift Code and ignore all the comments you write inside the application. In this comment's reference the following topic will be cover:

  1. How to create a single line comment?
  2. How to create a multi-line comment?
  3. Comment shortcut
  4. How to write a good comment?





1. How to create a single line comment?

You can write any text you want after the // and the compiler will ignore such lines from // to the end of the line.

Swift Code :

// This is a single line comment
var str = "Appdevelopments.co"// This is a single line comment on the side
print(str)

Output :

Appdevelopments.co

You can stack up multiples comments for you to write a paragraphs.

Swift Code :

// This is
// allow you to write a paragaphs.
var str = "Appdevelopments.co"// This is a single line comment on the side
print(str)

Output :

Appdevelopments.co




2. How to create a multi-line comment?

When using multi-line, there is a better way than the above example. Anything between /* and */ is considered a comment and it will be ignored by the compiler.

Swift Code :

/*
 This
 is a mutiple
 line comment
*/
var str = "Appdevelopments.co"
print(str)

Output :

Appdevelopments.co




3. Comment Shortcut

When commenting on a block of code, it is hard to do it one and a time. A faster way of commenting large block of code is

  1. Highlight or select the block of code you want to comment
  2. Command + / shortcut to comment or uncomment.



4. How and when to write a good comment?

Inaccurate comments are worse than no comments at all. As they can mislead someone understanding of a code. Writing unnecessary comments can create a mess in your script. Therefore, it is important to have a good comment so that the future you, will not be complaining.


DON'Ts

Comment on a bad code: Sometimes you know that your code is messy and even you, yourselves have a hard time understanding. Rather than writing a long comment to explain your code, you should clean up your code instead!

Redundant Comments: You should not comment on something that already make sense. Writing this comment makes your script messy. For example,

Swift Code :

currentLevel += 1 // This increase the current level by one

Function can explain: Do not write a comment if you can convert the code into a function which the function can explain itself. For example,

Swift Code :

// This check if a user is an new user or not
if (acc.currentLevel == 0) {
  ......
}

Changing it to a simple method help you to understand the code without any comments.

Swift Code :

if (acc.isNewUser) {
  ......
}


DOs

Informative comments: Sometimes it is impossible to use a function to convey the meaning of the code. It is better to write informative and descriptive comments for you and other developers to see.

Intention comments: Writing what the code will be doing and the intended or expected results. If it is a function, you can also write the expected outcome of it.

Warning comments: Sometimes it is better to warn other developers of the consequences of running the following code or to tell other developers of the possibility of crushing the application.

Expected input (For methods): For a function, you can comment on the type of parameters that are expected to input and their data types.