Android Simplified. Documenting code

Introduction

• At the best of times the Android documentation can be overwhelming and confusing, at the worst of times it is very overwhelming and very confusing. This series hopes to boil down topics and make them less complex. All the information I used for this blog post can be found HERE

Real world example

• For a real world example of how to document Android code I would recommend looking at the open source WordPress Android app, which can be found HERE. It is also worth noting that each project will have its own format for documenting code.

• If you have not done so yet, I highly recommend checking out the open source WordPress Android app, which can be found HERE. I know it sounds redundant to tell you again, but I can not stress this enough, REAL WORLD EXAMPLES ARE THE BEST TO LEARN FROM.

A Doc Comment

• So, as I am working on releasing a second version of my app, I often come across old code that I have written and have no idea what is going on. I often find myself losing a lot of time trying to figure out what everything does. Obviously, this is a sign that I need to do some proper documentation. I am now using two type of documentation for my project:

1) self documenting code: I am now making an effort to name everything properly, that means not more method names, such as, doTheThing() and f(). All variables, classes, methods, interfaces and so on, are now much more literally named for their purpose.

2) Doc comments: this form of documentation has been the most helpful to me. I am following the rules of Javadoc which state every class and method should have a Doc comment. The doc comment also consists of two parts

• 1) The first part of the doc comment is the description, where the first sentence of the doc comment is used for the description of whatever we are commenting

• 2) the second part of the doc comment are the block tags. There are many block tags but the 4 main ones that I use are, @author which states who created the class, @version which states what eversion of the class I am working on, @param which is used to describe the parameters a method takes, and @return which describes the return type of a method.

• I know this post seems brief but if you are a beginner like me, proper documentation can really elevate your projects to the next level.

Conclusion

• Thank you for taking the time out of your day to read this blog post of mine. If you have any questions or concerns please comment below or reach out to me on Twitter.