Best Code Commenting Guide For Swift-iOS by Mohit Chug
Hi Readers,
Welcome back to the hustling ground. Today we are going to the best practices to follow while doing the code commenting in swift.
What are code comments?
In simple language, it’s a programmer’s readable explanation of your source code.
Why it’s good to write a comment or document your code?
The answer is it’s too good to write the comments and the documentation while writing your code. So that It will be very easy for you and your team, who will be working on the code with you, to read and understand the code you have written after so much hard work.
Let’s Start and learn how to become the best at writing comments while programming. And Make your code perfect to understand.
Firstly, we will see the type of comments possible in SWIFT. So, as per my knowledge and research, SWIFT supports five types of comments currently.
Type of comments
- Single Line Comments
- Multiline Comments
- Markdown Comments
- Documentation Markup
- Functional Comments
Single Line Comments -
In swift, you can add single-line comments using // as a prefix.
- You can add a Single line comment, over the function, inside the function, and End of the line after the code also.
Example :
// This function will add two integers and return the resultfunc add(_ a: Int, _ b: Int) -> Int { // Inside the function return a + b // This line of code will return the expected result.}
Multi-line Comments -
To add multi-line comments, you need to use the syntax /*…….*/ It will start with /* and end with */ You can write anything inside it.
Example :
/*This function will add two integers and return the resultYou can write anything if you think it is useful for the other developer.*/func add(_ a: Int, _ b: Int) -> Int {// Inside the functionreturn a + b // This line of code will return the expected result.}
Markdown Comments -
To add Markdown Comments, you can use /// “Tripple Slash” there are the comments with Swift Markdown styling, which will allow you to add more rich text formats while writing, Comments.
You can Multiline Markdown comments with the syntax /** ……….. */
/** will start the multi-line Markdown comment and the */ will ends it.
In the above-shown image, you can see the difference between the normal comment and markdown comments.
Documentation Markup :
Swift uses documentation markup comments to generate documentation in Xcode.
I personally believe that every iOS Developer, especially those who develop an SDK should write these comments properly because it will really help a lot to the developers using your code or SDK.
These are mainly used for Classes and Functions but can be used for pretty much anything.
Example:
We have a long list of all the possible options so you can check that list and use it accordingly. This will get rendered in the XCODE on the side panel.
Functional Comments:
In functional comments, we have a total of four types of it.
Diagnostic Derivatives — #warnings(“”) #error(“”)
Annotations — FIXME, TODO, MARK
On a Usage basis, we can divide them into three types.
- Documentary
- Functional
- Explanatory
Documentary -
As we all know, documentation increases the readability and usability of the codebase. So write the proper documentation which is understandable and in the proper format so that the IDE like — Xcode can parse it and show it in GUI.
I highly recommend mentioning it while documenting your swift code.
- Filename
- Project name
- Creation and modification dates
- Author
- Copyright
- Version
- History of changes
- Dependencies
//// AppDelegate.swift// SampleProject//// Created by Mohit Chug on X/X/XX//
Some of the documentary comments you must have seen on top of the file when creating a new file.
Functional -
I have already covered the functional comments above.
Explanatory -
All other comments and documentation parts come under this and you can use it very well.
As per my experience and understanding, everyone can write code, but we should always make sure, that our code should be readable, understandable and well documented.
Hopefully, I have increased your knowledge a little bit and it will surely help you to write better documentation for your code which will be more clear and more advanced than before.
Alongside the Computer Programming Articles, I also write on productivity and also looking forward to sharing my knowledge with you guys in other fields. Do Follow! me on medium and other social media channels to get updates.
I am also open to one-to-one connections if you want to have chat about Tech, Startup, Finance or Life. You can ping me on LinkedIn or connect me through my website, you will find a way there. Let’s grow together.
Coming with more content very soon. Till then #keephustling
Thanks
Mohit Chug 🚀
Let’s Connect on other platforms also.
Visit — https://hustlewithmohit.com
LinkedIn — https://www.linkedin.com/in/mohitchug07/
Twitter — https://twitter.com/hustlewithmohit
Instagram — https://www.instagram.com/hustlewithmohit/
Medium — https://medium.com/@hustlewithmohit
