General Guidelines to follow when Organizing your Coding Projects

When I first decided to start coding, I looked at various languages, IDEs, textbooks, and online resources in order to learn how to code. One thing I wish I had added to that list was methods of organizing code. By that I’m not referring to code that is understandable on a micro level. I’m referring to the overall structure and organization of your code.

Having a solid structure to the programs you create can be both a time saver and a headache saver. This is a very minor issue when creating short programs but when working on more complex projects, making a few wrong decisions regarding overall organization in the early stages of the project can cause your workspace to become a disaster. It can become all but impossible to navigate through the code you have written even if you may understand what each individual line of code does. Expanding upon the code you already wrote can also become extremely challenging.

If you’ve had that sort of experience before, then it becomes easy to see why it is important to have well organized code.

Here are some general principles you can follow when attempting to keep your code organized:

1. Have the names of your files and subdirectories be self-explanatory. You should be able to tell from a glance what each file and folder contains, why they exist in the first place, and what came from what.

2. Choose your file names carefully and be explicit with naming. If you aren’t careful, it becomes all too easy to suddenly realize that you have several components or files with similar names. The only way to figure out what everything does would then be to look up each file or component one by one. If the code that makes up these components looks similar as well, then you could be in for an even bigger headache.

3. Plan ahead. Instead of jumping into coding straight away, spend time thinking about what your project will probably look like in the future. Would it make sense to create extra folders to keep yourself organized? Should you rename an existing file so as to avoid confusion later?

4. Take the time to make sure you understand how your existing code works before implementing new changes. There are many ways to solve problems when you code. Sometimes you might favor one solution over another and that’s totally fine. It is important to keep in mind though, the fact that the first solution that comes to mind might not be the best long term solution. That easy fix you came up with could very well end up hamstringing your efforts to work on your project somewhere down the line. A very significant portion of your code could end up relying on that “fix” you came up with. Building out a new feature could then become not only a matter of figuring out how to create that new feature, but also how to refactor huge swathes of existing code.

5. Write it down. When realizing you might have issues remembering how certain parts of your project come together, a useful strategy is to grab a pen and paper and just write down how things come together in a very clear and succinct manner. That way you won’t have to constantly keep referring to the same files in order to remember how your code works.

6. Don’t keep everything in just a few files. This might feel convenient at first, but as you expand your code, it can become extremely difficult for both yourself and others to read your code and figure out how everything comes together. Tracking down bugs can also become extremely challenging when you have 500–1000+ lines of code inside of a single file.

7. When organizing your code, avoid creating tens (or hundreds) of files each containing nothing more than a snippet of code. While it’s good to split up your code into several (or more) files, you can easily overdo this. Not only does naming these files become a problem, but now you have to waste time looking through huge numbers of files and updating your existing code can become all but impossible.

8. Be consistent with naming conventions. Try to stick with one type of naming convention throughout your program.

9. Leave comments in your code. Comments are your friends. They can help both you and your colleagues understand your program not just on a micro level, but on a larger scale as well. For example, at the top of a file you could have a comment saying something like “receives information from component x”. That could help you avoid looking through various files in order to remember what something does.

At the end of the day, it is important to remember that not one size fits all. The way you structure your folder hierarchy and the number of individual files you have can (and should) vary depending on the size of your website.

Being able to organize code is an extremely important skill for any developer and the earlier one starts refining this skill, the better. The best way to improve at organizing your code is to reflect on your previous choices and the benefits or consequences of these choices. There are many ways to organize your code and knowing the difference between the useful methods and the dangerous ones is vital to becoming a better developer.