Tips for documenting your code

Posted by Andy Huggins on December 31, 2015

Over the last few years I have started working on projects that have been built by previous developers. Invariably, there comes a point where I need to add some new piece of functionality, but have no idea where to begin to look for the pertinent pieces of code. I do my best to dive in and search for things similar to names I would probably use. Nothing. I try to trace through the app, following where a request goes in hopes that I can see how a response is built. I see some things, but nothing about the piece I am looking for.

At this point, some time has already been spent, and what do I have to show for it? Not a whole lot usually, maybe some ideas as to how an application is built, but surely not all.

Ask the developer who made it?

Yeah, that would be awesome, but they are no longer with the company, or in doing so, you are preventing them from working on whatever they were working on. I think this is where documentation comes in. Not only does it help you think out ideas, as in, forcing yourself to explain to your future-self or some other future-dev, might help you see that your approach solves the immediate problem, but maybe creates its own problems. Additionally, when you move on to the next (10) projects and have to come back to this project in six months, are you going to remember that you have to go update some array in a parent class?

Yes it takes time to write documentation and things change, but I think we can all agree that something is better than nothing and if you get in the habit of writing docs, and updating docs, then it becomes as second nature as writing code, or using Git.

So what are the tips for documenting?

I like to keep it simple, in almost every project I work on now, I create a "docs" folder in the root of the project folder. I do this so that it is easy to see in a file tree, and feels like it should go there to me. Then I just write Markdown files for anything that is tricky. Also, provide a link in the root README.md file to the table of contents markdown file in the docs folder. This is yet another way future devs can find the docs.

I like doing it this way because it keeps your docs with the project in Git. Meaning every dev who pulls the repo also has the docs in a (dev) friendly format. Full on documentation sites are good, but it's super handy to have it all in your repo as well.

What kinds of things should go in these markdown files?

This is open to your interpretation. Anything that you think is complicated, or not obvious are great places to start. Also, I am not suggesting you explain the code in depth. I generally prefer something like "This is how comments works, you need to add a use statement to any model that is going to use comments. Once you do that you have access to these methods X, Y, Z. X does this, Y does this, and Z does this."

The good thing is, setting up a docs folder takes seconds, the same as creating markdown files, which is one of the biggest reasons I like this style of docs, the effort required is basically as low as it gets.

I prefer markdown over text files for the simple fact that formatting can be added to the docs very easily and it just makes it that much easier to read, in the browser or the text editor.