Dysfunctional Directories: 5 tips for organizing a directory
--
As a young dev, I was once given the daunting task of building out a new implementation to a code base that consisted of 1 file with over 5000 lines of code. It lacked comments, a consistent structure or any organization at all. My assumption was that the devs just kept adding new features to the bottom of the file and as long as it ran without errors they passed the ticket.
Learning how to organize a directory or a file can seem tedious at times but it is extremely beneficial for other devs that may inherit this code. There are a couple guidelines to follow for making readable code, here I have included 5 that I have noticed and consistently seen thrown around. Nothing I say here is set in stone and should just be jumping off point for improving accessibility in your code.
1. Create folders
If you are building a project from scratch, file structure is something consider and shouldn’t be rushed. As you program more and more file structure will become second nature, you’ll start making folders before any code is written. Here is an example from a portfolio I built in React.
I utilize 3 directories, Assets, Components and Styles:
Assets: Here I hold all the images, pdfs and other miscellaneous files that I will need later in the project.
Components: This is a best practice paradigm recommended by the people at React but it holds all the pages for the project.
Styles: Instead of packing all the CSS in one file or using inline styling, I abstracted them into a folder and imported each file where needed.
The idea of using folders for similar files improves organization a ton. You could even use sub-folders in the components for reusable actions, API calls and other similar functionalities within the project. Something like this is extremely simple but it is very powerful when re-visiting code bases or for other developers to quickly add contributions or examine your code.
2. Structure your code
This one should be straightforward but have a pattern for your code and be consistent. Declaring all your variables at the top of the file, having your functions/methods together, even indents and making rest API calls in similar fashion are just some ideas I like to practice. It should really go without saying but try to take some time and imagine what the end product should be before writing code.
Having a basic structure in mind before any code is written is a great and super simple to implement. Patterns are easy to pick up and other devs can quickly understand your coding style by the pattens and paradigms you choose to implement. You don’t have to write your code like its a term paper with MLA format but some basic structure goes a long way. Keep similar functions and variables together and append new ones to the end of the list, doing this plus adding comments (Another tip in this blog) can improve readability by a lot. I would say doing this alone will make your code 70% more readable and is probably the most important thing to do so just think a little before you start writing code.
3. Comment, comment and comment
Commenting is under rated especially when you spent a majority of your career as a solo programmer working and haven’t worked with other devs. It might be second nature for you to use a particular block of code but it might not makes as much sense for other devs. When multiple devs are working together it can save a lot of time and headache for them with a couple helpful comments explaining methods or chunks of logic.
Imagine a nasty nested object being deconstructed and repurposed for a method that makes an API call. Instead of having other devs examine tens of lines of code and trying to follow alone with the logic it would save so much more time if one comment just said something like:
// Deconstructing object and grabbing the required parameters to fit for an API callThere are tons of reasons to make comments. I would recommend this blog by RYMS on the importance of commenting. Making it second nature to comment code may be tedious at first but like many of the other tips it will improve your programming abilities.
4. Be modest with your refactoring
I would suggest making the refactoring process a consistent theme in your work. It can be so satisfying to finally get some code working that you may just want to walk away once it runs without errors (sometimes even with errors, as long as it runs right?) However you can clean up so much code and every line counts especially if you have a monolithic project you are contributing to.
However refactoring is a blessing and a curse, too much and you have removed all readability from your code, balance is key. I have spent some time in Ruby and can say it is exhilarating to turn a couple lines of code into one really long change of methods and ternary expressions, however this sacrifices any readability there was in the logic. Coding is a language and a written form of expression just like Shakespeare. Your commits will forever be immortalized in GitHub repos to come, just like Shakespeare’s word selection and plays are highly regarded years after its inception.
Example of refactor (as well as comments):
var randomWord = "Hey";function palindrome(randomWord) {
// Turns a string to an array, reverses it and joins it back to
// make a palindromevar reversedRandomWord = randomWord.split('').reverse().join('');
return reversedRandomWord == randomWord;}
What is right about this block of code? The comments quickly explain what the function is doing without having to read any code. Also the bulk logic of the code is a nice example of chaining multiple methods and refactoring. It would have entirely been possible to include the comparison operator with that logic and it is a simple enough function that with the comment it would make sense, however it may remove some readability. Try to write code that is easy to understand for someone who has never written code before. Your colleagues will be very appreciative.
5. Stay consistent and find your style
This is probably the most important tip, keep writing code and refining your style. Programming is a skill and like any other skill it requires practice to become proficient. Being able to write code using different paradigms is great but developing your own style is key to growing as well. Once you have a style that works for you, you will be surprised how much faster you can write code in the future just because you will know how you want to structure your code. Quickly being able to trace down a function or variable (because they are always in the same place) or not having to refactor a block because you are already writing one-liners/simplified expressions is great for saving time. Just remember to practice and leave comments, for everyone’s sake.
