How To Properly Document Code

I worked for a job that taught me how to code documentation. 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.

There is certainly a better way to document which can be utilized if you use Github, and you may track each and every change on a revision level. Github keeps revisions upon revisions so you can always refer back to a much older version if necessary. However, if you are not using Github or you are just wanting to add extra documented code, you can try this method.

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

  // FILENAME: dashboard.php
  // STATUS: ACTIVE
  // DATETIME: MM/DD/YYYY
  // 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)

DATETIME lets me know the date and time this file was created.

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 five 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. (Grabbing user input, adding to database, updating Table1, Table2, and Table3 of database, returning user back to the 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 best and recommended practice to keep at it. You should always comment everything you do, especially in areas that aren’t so clear, such as if and else conditions, arrays, and for loop statements. 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. In fact, don’t think you’ll ever be able to read code a few years from now and immediately understand it.

DOCUMENT AND CODE EVERYTHING.

I only document the remainder of the file if there is some complicated code in it. I mean, after writing something that connects to the same database a hundred 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. Anyway, it is 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.