Code Documentation – before, after, and during coding

Sometimes you just need to started on some design for work on a larger ticket or new feature, you want to get your thoughts down and maybe start plotting out a code flow or some potential classes but what app do you reach for?

So much of the time I reach for Google Docs, for my personal or professional work. It’s easy, automatically backs up your work, and makes it very simple to share the document or convert it to another format. Opening a Google Doc, and starting to type out some pseudo code can be frustrating with the automatic capitalization or the code just not displaying as you would like. I have found the Code Blocks extension extremely awesome with that. Putting in code next to text is a breeze with it.

Helpful tip – If you are using Google Docs you can change up your preference to not annoyingly capitalize the first letter in a sentence (which is rather annoying for your Ruby classes which like to start with a non-capitalized letter).

Sometimes you just want to work on a spike story or share research that you had to done on a particularly hard debugging process or obscure part of your application. For this type of information, I like the use Confluence, a GitHub readme, or even the GitHub pull request itself. Just depending on if it is something I am currently fixing (it will go in the GitHub PR, preferably with screenshots if it a UI type fix), research for tickets or design coming up (Confluence, so easy to share and searchable for other developers) or if it is something that is needed for the code itself, like metadata or installation information, a readme works well. As a developer, I am trying to improve my git commits and PR for future development and maintenance. I highly ecourage anyone working in Git to check out Tekin Süleyman’s awesome “A Branch in Time” talk. Also his blog post on creating useful git history has some great Git tips and tricks, and really makes you think about how your git comments today, and effect someones code tomorrow.

For UML and flow diagrams, LucidChart, is my current app of choice. It is an online diagramming tool that has a lot of flexibility on what you want to show. Coming up with your flow diagram isn’t too hard, just make use of the typical shapes and lines. For me drawing the lines for the code that is calling a self.method was the hardest, but LucidChart has some pretty good tutorials that can walk you through the process, and help you with all the keyboard shortcuts that make you work life happier.

For the documentation of the code itself, I love writing code that is self documenting. For years with writing Java, if your code needed to have comments above it so other developers could understand what it was doing, it was probably too complicated. Writing comments were not encouraged, and refactoring out methods, and patterns to be better descriptors were the norm. Now with Ruby and the software I develop on, there are more comments in the code base. There doesn’t seem to be any stigma with code comments. Sharing information on how to use a command object, or the usage of an API or providing context on a classes public contract all seem to be valid use cases for inline code comments. I am getting used to using comments effectively in Ruby, and the not bring over any Java stigmas that I might have carried over about comments. I still do lean towards refactoring out code into smaller chunks with self descriptive method names, but do understand when code comments are helpful. All my method names tend to be more verbose, and I am still working on remembering to snake case everything.

There are so many different things that we have to document as developers that it is so important to figure out the best tools and applications that work for you. So, you as a developer, can document code effectively, efficiently and hopefully in a way that other people can find it and use it. Because the only thing worse than not documenting code, is not using code documentation.