Your code is meant to be read and written by humans. While it should be syntactically correct to compile, your naming conventions, comments, and other artifacts of your coding style are of no importance to the compiler. The level of detail and attention you will put into documenting your code can make all the difference to internal or external contributors.
If you honed your craft on Objective-C, you’re not in luck. Apple, which for the longest time used HeaderDoc
, switched to a Markdown-flavored documentation engine. This is for the better, as Markdown is a widely used markup language and you will feel right at home if you have any experience with it.
Yes, this is still a book about Swift, but let’s take a minute to have a look at the Markdown language.
Language is a big word. Unlike with other programming languages, you can become proficient in Markdown in a few minutes.
Markdown allows for a lightweight annotation of your text so it can be structured...