As I work along with some legacy code for my capstone project, I get to a very complicated and long JavaScript file. To my surprise, the functions (and the variables to go along with them) are not named in any sort of descriptive manner, nor are there good notes left behind. Instead of jumping in and making the changes I need, I’m spending hours and hours just trying to decipher what these functions are supposed to do!

I’ve run into this a few times before and it’s taught me a very valuable lesson: Can somebody who has never seen your project before look at your code and be able to understand the general idea of what it does? If you have to think about that when coding, then the answer is probably no.

Let me give you an example. I am currently updating some maps that overlay location markers. These maps were created about 5 years ago by a previous developer. I was hoping that I could jump in, add a few items, and jump out, all preferably within a day’s work. However, now I’m looking at the coding and I have no idea how it’s working together. There are variables named “s” and “u”. Oh, thank you for that descriptive name so I know what that does!!

Then, the previous developer used those same letters to preface certain functions. For example, “u_pts()”. I already don’t know what “u” stands for, so I definitely won’t know what this function does. It’s mildly infuriating.

This is where I go back to me questioning if another developer can understand your code. I should be able to walk into a project and spend some time figuring out what the code does without having to spend time figuring out what a variable is named for. Instead of “s”, put “species_name” or something specific. Sure, it takes one extra second to type out, but it will help tremendously. That goes along with functions too. Name a function in a way that describes what it does. Also, PLEASE leave notes above the function to describe, in detail, what it does, what it changes (if anything), and what the expected output should be.

These should be common practices among programmers. I know many professors who enforce this readability, as they should! It was taught to me in my very first programming class years ago. Always give your functions and variables names that mean something.

*I’ll give you one pass: using “i” instead of “index” in a small for loop. That one I’ll let slide (though you could just say index…).