
How should i document my code? - jonloldrup
I have been working on a hobby project in JavaScript&#x2F;three.js + browserify for 5 years now.<p>I&#x27;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.<p>However, I haven&#x27;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&#x27;s it. I miss documentation that explains all the &#x27;glue&#x27; and the big thoughts in the code. I always wish I had this, whenever I revisit code that I wrote a while ago.<p>So what&#x27;s the best approach to this? Is there any kind of systematic approach to this task, beyond autogenerating API docs using &#x2F;<i></i> ... *&#x2F; comments? Or any kind of guideline I should have in mind when starting this project? What&#x27;s the best practice when embarking on documentation projects like this?
======
afarrell
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...](https://developer.gocardless.com/getting-
started/api/introduction/)

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/](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
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
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
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
I wrote up an article on this: [https://medium.com/@jcahill84/insurmountable-
documentation-s...](https://medium.com/@jcahill84/insurmountable-
documentation-shortfalls-131aa6be7f62)

------
deanWombourne
Using only Kafka -
[http://thedailywtf.com/articles/Who_is_Gregor_Samsa_0x3f_](http://thedailywtf.com/articles/Who_is_Gregor_Samsa_0x3f_)

------
mattbgates
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
in limericks or haiku

