Hacker News new | comments | show | ask | jobs | submit login
Ask HN: How should I document an existing web app?
7 points by benmcf on Mar 20, 2017 | hide | past | web | favorite | 3 comments
I'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'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'm wondering what my options are. As I see it I could:

a) Potentially overdo it: express everything I'm able to learn about the app in various UML diagrams, tables and written guides.

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.

c) Something in between the two. Maybe comment the code myself, maybe using JSDoc style or something to make ongoing documentation easier.

Any advice would be much appreciated.

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

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.

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
  // 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.

Guidelines | FAQ | Support | API | Security | Lists | Bookmarklet | Legal | Apply to YC | Contact