
Ask HN: How should I document an existing web app? - benmcf
I&#x27;m a recent CS graduate and have just started work for a business that is building a web app. Almost all of the work has been done by a single contractor who left with a day&#x27;s notice last week. My role is essentially business analysis and my boss wants me to document the app so that any new developer can understand it quickly. I&#x27;m wondering what my options are. As I see it I could:<p>a) Potentially overdo it: express everything I&#x27;m able to learn about the app in various UML diagrams, tables and written guides.<p>b) Potentially underdo it: try to determine whether the app has been built well enough that any competent developer can figure it out it fairly easily and just provide a readme or something if I judge (with my limited experience) that it has been. Existing comments are fairly minimal, but I believe some developers prefer a commentless approach.<p>c) Something in between the two. Maybe comment the code myself, maybe using JSDoc style or something to make ongoing documentation easier.<p>Any advice would be much appreciated.
======
ivan_ah
I'd say the first step for you (or any new developer that comes to the
project) is to document the data model. What are the tables in the DB? What
data goes where? What tables change on a day to day basis, and which are
"stable". Where are user accounts?

Once that is done, you should document how the system interacts with other
systems. Logins? Single sign on? External APIs that the system calls? External
clients that call the app?

With these things done (which might take some time to figure out), you should
think about writing a HOWTO for new developers. You really don't want to be
the only person working on this, it will be a lot of stress otherwise. Imagine
a new developer joins tomorrow. What should they look at first? This is a nice
tool for showing "code tours" of a new code base you could use:
[https://github.com/partyparrot/codetours](https://github.com/partyparrot/codetours)

------
dozzie
Start with the data flow: what interacts with user, what interacts with other
systems, what exposes a remote API, what components pass data where, and what
data structures are used between them. You'll also need to document what
processes and modules/subsystems are there (cron job? job queue? other
daemon/worker of sorts? and then layout in the code). And build/deployment
process, especially with today's CSS and JavaScript compilers.

------
mattbgates
I had a boss that helped me learn how to document code. It was extremely
important as there were many developers befor me, and there were to be many
after me. We even had a plugin that inserted a few lines for comments.

To this day, I still document my work by pasting this at the top of every file
created:

    
    
      // FILENAME: myfile.php
      // STATUS: ACTIVE / INACTIVE
      // PURPOSE: The purpose of this file
      // NOTES: Any additional [technical/non-technical] notes that this file should have
    

Feel free to use it yourself or add to or modify it.

So it will tell you the filename, if the file is currently in use by the
application (sometimes an old file may be obsolete, but is kept for legacy
purposes), and additional notes to explain the function or purpose of the
file.

This eliminates any questions about what this file actually does which helps
any developers involved to kind of get a sense of figuring out what this file
is in seconds rather than trying to trace it everywhere.

In the notes, you can also list other files that are associated with this file
or anything you want.

You can go through each line or code block and just comment on what it is
doing.

While I don't usually work with other developers. I have made it a habit of
documenting all my side projects in case I ever need to hire anyone or even
just to remind myself of what a file does. I am working on about five
different side projects right now, probably thousands of lines of codes, and
hundreds of files across all. So the fact that I can just open up a project,
track down the file, and know the function of the file definitely saves a lot
of time.

I suggest you comment right in the code itself. If you wanted to create a side
note or wiki-type deal, it is definitely possible. Ultimately, you want the
very top comment code to help you keep track of everything.

Add it to a few files. Go to lunch or something. Come back an hour later. Open
up the file. If you can figure out from the comment you wrote up top what the
file does, you are in good shape and I'm sure others can follow what you
wrote.

I tend to not write a comment for every single line. If I'm reading from the
database, the variables kind of tell me what it is doing, so I don't document
every single line, but I do comment enough to understand what something is
doing in the code, especially if the code is long or complicated.

I don't recommend over complicating your comments of the code. Keep it as
simple and to the point as possible. You are just explaining the purpose of
the code and what it is doing mostly. Act like your boss is going to read it
and he may not understand your job (because he did hire you to do the job). If
you think he's going to question something: your comment is over-complicated.

If you think he can read through it, just the comments, because lets assume he
doesn't understand the "technicality" of the code, he just wants to know the
purpose of this file: your comment is satisfactory.

