Documenting Your Objective-C and Swift Code in Xcode with HeaderDoc and Doxygen

During the development of an application there are various steps involved in the whole process. Some of them are the definition of its specifications, the creation of graphics, the implementation, and the testing phase following the implementation. Writing the code maybe consists of the most important part, as this brings the application to life, but further than that, equally important is the proper documentation of the code. No matter how well-written the code is, if there’s lack of a good documentation accompanying it, future troubles it’s possible to arise. Unfortunately, many developers overlook or ignore the importance of the code documentation, and that’s really bad, as good software is not just good code. It’s more than that.

When talking about documentation, apparently I don’t mean just to add a few lines of comments somewhere in the implementation files. It’s definitely more than that. But first, why is it such a big deal to document the code? Well, there are two cases: Whether you’re working on your own, or you are a part of a team. Let’s see in short each one.

xcode-macbook-featured

If you are the only developer of the under-development application, then it’s reasonable to believe that writing code documentation costs in time, so skipping doing that will bring you right into your target much sooner. Additionally, it’s easy to convince yourself that as you’re the sole developer there’s really no need to do that. But trust me, that’s the worst decision you might make during the app creation period. Suppose that you successfully implement the application, you sell it either on the app store or in a client of yours, and then you put it in the shelf. And after six months or so, you must create a new version of it by adding new features. When you open the project again and look to the existing code, a long before you write the first new line, you realize one killing truth: That you don’t remember almost anything! It’s hard to remember what you did, how you did it, and why! You must follow the one, painful way to wake that project up in your mind, which is no other than taking the project from the beginning and trying to “decode” your implementation line by line. Just a few comments here and there are not helpful, and eventually you end up making a super-effort for a long time until you understand everything. Many of you that you are now reading these lines may have come to that point, and I ensure you that there were times that I’ve been there too. This case is a real nightmare, and you often want to start building the project from scratch. And of course, the scenario described here would just be a… scenario, if we all invested a little time to write proper code documentation.

Read the full tutorial on Appcoda