“Good code is its own best documentation. As you’re about to add a comment, ask yourself, “How can I improve the code so that this comment isn’t needed?” Improve the code and then document it to make it even clearer.” ~ Steve McConnell
Resuming my code documentation story. Ideally this one should be the first part but I actually got the idea of writing a story on documentation from comment tags. So, if you’ve not read the first part you can check it below.
Let’s begin with a comment tag.
MARK:- A comment tag to structure a code base into different segments over source editor and navigator. This is one of the widely used comment tags in Swift documentation.
Now, we will move a step further to usage of Markdown syntax in Swift. With the release of Xcode 7, developers can apply rich text formatting to the text of their documentation. I am only listing down the few major syntaxes available but you can deep dive more by clicking the link above.
Basics first.
A single-line documentation comment is characterised by three slashes (///). Multi-line documentation comments is enwrapped inside a delimiter (/** ... */). Let’s see some common markdown syntaxes.
- #string# : It makes the text as a header.
- **string** : It makes the in between text bold.
- *string* : It turns the text into italics.
- * string : Creates an unordered list of items with bullets.
- 1. string : It creates an ordered list of items.
- A code block is created by using a delimiter of three back ticks(`) or tildes(~).
- Paragraphs are separated by blank lines.
Our code documentation is incomplete without the use of keywords which come with default formatting styles. Below is a list of widely used keywords.
- - parameter name:
- - returns:
- - remark:
- - precondition:
- - requires:
- - warning:
I’ve documented a complete class using Markdown syntax, keywords, pragmas and comments. Check out the video below to enjoy the beauty of documentation.
P.S.
I’ve surely gone overboard in the video to show you the maximum documentation options available.
Summary:
The project should have a good documentation and guides, but it should be minimal in the source code. Avoid over-documenting. External API documentation adds an advantage of separate code and documentation.
Bonus tip:
You can quickly document your code by using this keyboard shortcut I found while watching one of Sean Allen’s video on his YouTube channel.
Cmd+Option+/
I conclude my documentation story series with a funny gif.
I would love to hear from you
You can reach me by the following channel(s):
Feel free to drop suggestions in the comment section.
Thanks for reading. Happy code documenting!
