How should i document my code?

16 points by jonloldrup 9 years ago | 8 comments

I have been working on a hobby project in JavaScript/three.js + browserify for 5 years now.

I've been pretty good at testing my code and refactoring it whenever appropriate. I thus have more than 2500 test cases and I feel that my code is pretty solid.

However, I haven't been so good at documenting my code. I have some comments here and there in the code base, pertaining to certain functions. But that's it. I miss documentation that explains all the 'glue' and the big thoughts in the code. I always wish I had this, whenever I revisit code that I wrote a while ago.

So what's the best approach to this? Is there any kind of systematic approach to this task, beyond autogenerating API docs using / ... */ comments? Or any kind of guideline I should have in mind when starting this project? What's the best practice when embarking on documentation projects like this?

afarrell 9 years ago |

Who is your audience? Folks using your API or folks who are going to dive into your codebase and contribute to it?

For folks using your API, there are two types of documentation you want:

1) Tutorial: Documentation that guides the user through a few steps of working with the API. This should be an integrated experience. The aim is to help a user build a mental model of your project and introduce them to the shape of the major parts of your API.

Example: https://developer.gocardless.com/getting-started/api/introdu...

Since you're doing this for a library that you can write automated tests for, you should consider showing your user how to test. This helps prevent a user from getting lost and gives them a clearer way to integrate with the rest of their tooling.

2) Reference: Documentation that someone can use to look up the answer to a specific question that they have. This is not an integrated experience but should integrate well with their workflow when building something and searching for answers. The goal here is to be highly searchable, which requires thinking about what words they would look for when trying to find it.

Example: https://developer.gocardless.com/api-reference/

This is something I love thinking/talking about, so feel free to email me if you want to videochat and bounce ideas off me. My email is in my profile.

angersock 9 years ago |

My suggestion would be to start at the high level, and work your way down putting emphasis on things that aren't going to change or change much--that way, when you change things the docs won't become as wildly out of date as quickly.

So, document things like "What are the big conceptual pieces of my project?", "How does data flow around?", "If a user sees <X>, what's behind it?".

Then, if you feel it needful, dig down into function-level and deeper stuff.

jonloldrup 9 years ago | |

This sounds like a good suggestion. Now my thought is to pair code files with similarly named doc files. Higher level code files will go first, and only later will I fill in the nitty gritty files.

The next question is: how do I get a good work flow? Due to a handicap, I am limited in my computer keyboard typing, but not limited in typing on my phone. Thus the optimal would be to find an Android markdown editor and an android git client. I'll check out the Play store :)

ramtatatam 9 years ago |

I aim to exercise Contract Driven Development. Write contract first, in python this would be in a doc-string of your stub. Then depending on your methodology either write your tests first followed by implementation (or vice-versa, depending on your preference). Then in the code document things that required you to run research (or more thinking power than usual).

jcahill84 9 years ago |

I wrote up an article on this: https://medium.com/@jcahill84/insurmountable-documentation-s...

deanWombourne 9 years ago |

Using only Kafka - http://thedailywtf.com/articles/Who_is_Gregor_Samsa_0x3f_

mattbgates 9 years ago |

I worked for a job that taught me how to document. I was actually a coder who fixed bugs for auto body software. What made my job easier was probably knowing what the file I was -- what exactly it was doing. I didn't love doing the job, but it taught me what I needed to know.

As I began developing for myself, I would often just not document my code, thinking the best: "Oh I'll know what this does when I see it." Add a dozen projects into the mix: "Yeah, I remember that.. what did it do?" I knew I had to start documenting again. I also figured: Why not document? If I ever need to go back to it or hire someone to work on something, I -- and they -- will not be so lost when looking at it.

So, how I document my code is by adding this template at the top of every page.

  // FILENAME: dashboard.php
  // STATUS: ACTIVE
  // PURPOSE: Shows basic information when user logs in
  // NOTES: Dashboard will display the most recent transactions

FILENAME lets me know what file I am in.

STATUS lets me know if this file is actively being used; or INACTIVE, for not being used at all, or SEMI-ACTIVE (usually for TEST files)

PURPOSE lets me know what exactly is the function of this file within the program I've built.

NOTES are optional, but these just let me know if there is any additional information I need.. such as "Admin use only" meaning this file is used by administrations, not regular users.

Those four keywords give me everything I should probably know about the file. You can add additional lines too, such as one that I might sometimes use: LOGIC. LOGIC explains exactly what the code is doing and how it works in more technical terms. (Grab user input, add to database, update Table1, Table2, and Table3 of database, return user back to Dashboard)

Before you even begin writing code in your file, you should start off with this template. It will keep you organized and make you feel more in control of your code. I mean, I've developed a few programs that have hundreds of files each, and the very first program I wrote: Very little documentation.

You feel like your code is going to crash, burn, and you won't be able to figure it out. By documenting, even if there are issues, you can pinpoint what it is doing and where, and that should lead you to the file you need to focus on.

The rest of the file is usually optional for commenting, though it is great practice to keep at it. If you think you can't pick up something from the code by reading about the file, than you may want to continue documenting throughout the file. I only document the remainder of the file if there is some complicated code in it.

I mean, after writing something that connect to the same database 100 times, I may have only documented the most used files that use that code. For smaller files, if I forget, I can always revert back to the major files to remind myself of what this code is doing.

Anyways, its up to you, but it also helps that if you ever decide to sell your code or someone wants to buy it from you, you've already done the work for them, and imo, it adds a lot of value to your code.

probinso 9 years ago |

in limericks or haiku