Disclaimer
I am still learning how to organize my projects.
I am in no way an expert and my advice should be taken with a grain of salt. I have however noticed certain problems with my previous setup, I've adjusted it and immediately saw improvements.
I'd like to share my story and hopefully help some of you.
Feel free to leave your advice down below if you see something stinky
Foreword
We've probably all heard the famous saying : ,,Go and clean your room!''
And probably all of us, sometimes in our lives, have answered :
,,I can't right now! I'm like doing something really, really important!''.
As a self-proclaimed ''creative'' person, I have defended my creative mess with all my strength.
I've explained in thorough detail how 20 layers of t-shirts across my chair actually helps my everyday decision making and how my table is not messy, it is perfectly organized in well thought-out sections that speed up my process of finding things.
But the harsh truth about creative mess hit me on top of my head many years down the line.
I've been told that creative mess, at the end of the day, is still a mess.
Me : ,,How dare they, those pathetic simpletons will never grasp the astronomical importance and the technical complexity with which I'm conducting these creative procedures that enable me the efficiency and productivity of nothing short of a God!''
I humbly thought to myself.
As my view has once again fallen upon the creatively designed 20 layers of t-shirt lounge chair, a small voice from the back of my head whispered : ,,Maybe they're right...''.
And unfortunately, they were right.
With watery eyes, I mumbled : ,,Goodbye, 20 layer/high profile/one of a kind/customized lounge chair worthy of nothing short of a God...goodbye.''.
Table of contents
- Illusion of a clean work space
- What happens now?
- Examples
- Closing words
1.Illusion of a clean work space
Don't get me wrong, creative mess is a wonderful thing, until someone other than you needs something from it.
I still remember when I tried to navigate my brother, over a 20 minute phone call, to read some numbers off of the specific document buried away in my room.
All things have a tendency of succumbing to entropy, even more so if those things are not taken care of.
I had the uncomfortable privilege of experiencing such fate with software projects, mostly my own.
At the beginning of a project, be it a bigger software application or a smaller website, sooner or later the code will pile up.
As little bits of your code are being added in your application over a longer period of time, you don't have a feeling like things are getting messier, just like the frog doesn't experience water getting slightly warmer, until it's cooked alive. Too dark, Kristijan...too dark.
But how should I know before hand how to organize my projects?
I don't want to be cooked alive!
No worries, young padawan.
I am here to tell you that...I have no idea.
Like, I'm still learning this stuff myself, it depends...it's super hard...I can't even...I mean, where to start?
Nahh, I'm just kidding...well, not entirely.
Organization of your projects and how detailed it must be definitely depends on the technology you're using, how robust the application is and definitely on how many people are working on it.
There isn't one size fits all in this case, unfortunately.
But what I have noticed as a consistency, throughout the projects I was working on, is the collaborative effect of the team in establishing the architecture, the scale of it and defining the necessary steps that each developer can follow in order to write better, consistent and clean code while keeping the file structure concise and neat.
If I can sum it up in a few steps, it would be :
- Talk first, code later
- Clearly define the architecture and the necessary tools
- Write down, if you have to, the rules that ensure consistency and clean environment according to the predefined architecture
- Don't crash and burn
2.What happens now?
Taken into account the steps I've aforementioned, let's put it in perspective.
Recently I've marched into a project, which I'll post more about here pretty soon, that is in-visioned to unify Nasa API's in one place.
This is my story.
1) Talk first, code later
By talking about the project, you put yourself in a different position.
Preferably in a position of someone who will be using the app, since we as developers often get stuck in a mindset of someone creating the app.
You discover new angles from which you can tackle certain problems and hopefully start thinking about design that is suited for the users, not the design that you want to see.
With that in mind, I wrote down the key points of my application, alongside with the key issues that I will potentially face.
Of course, you can not cover every little detail in this segment, but it's kinda important to set the proper base of your project, upon which you can fluently build every future release.
2) Clearly define the architecture and the necessary tools
Architecture was supposed to be designed in a way where we could efficiently and fluently grab the results from the API, map it to our predefined models, functionally sort the data and feed it to the front end.
That communication needed to be as fast, fluent and clean as possible.
During the talk bit, we clearly all agreed upon using Java Spring on the back-end and Angular 7 as our main front-end tool (triggered comments ahead). Even though it can be robust at times and it definitely serves more as a tool to handle big enterprise applications, it perfectly met the requirements and needs we all had.
Just a heads up, not a line of code was written yet.
3) Write down, if you have to, the rules that ensure consistency and clean environment according to the predefined architecture
Immediately, the clear and concise Git flow instructions were written down.
Source control is a major thing and a quality Git flow can really save the day down the line.
Alongside of that, agreement was made regarding how our folders should be structured and what the naming convention shall be.
An example of our app folder is as follows :
It is slightly different at the current stage
Therefore, everyone was able to easily orient themselves within a project and maneuver their way through the application.
Everyone was informed and on-board regarding the naming conventions and logic flow of the application, which means we all followed the hierarchical rules about what our services should do, how our components should look like - or in the case of Angular, how dumb should they be - and last but not least, how our syntax would look like.
We've also used tools like Prettier to keep our TypeScript/Javascript syntactically consistent + tools like Husky & E2E test tools to make sure our code is somewhat bulletproof - I'll touch upon this subject a bit more in future posts.
4) Don't crash and burn
Seriously, it's easy to get tangled up in all the procedures, workflows and get burned by the process of trying to make everything perfect.
It's nearly impossible to predict everything, it is crucial for you to remember that mistakes will find their way into your projects and you will inevitably have to go back and fix some things.
Don't stress too much about it. Know that you're doing your best and keep at it.
3.Examples
If you are further more interested in the subject, check out the links below for further detail :
- https://thehelloworldprogram.com/web-development/creating-files-folder-structure-web-pages/
- https://developer.mozilla.org/en-US/docs/Learn/Getting_started_with_the_web/Dealing_with_files
- https://softwareengineering.stackexchange.com/questions/176803/how-to-organize-my-sites-file-system-properly
- https://onextrapixel.com/building-web-apps-file-and-directory-structures/
- https://stackoverflow.com/questions/24199004/best-practice-to-organize-javascript-library-css-folder-structure
I've applied this principle to the smallest of my projects.
For example, my web portfolio, which is composed of only HTML, SCSS and Vanilla Javascript, has the following structure :
Now if anyone needs to get into my room, figuratively speaking, and needs to do some adjustments in my services part of the room, he or she would be able to do so effortlessly.
Closing words
What is the connection between your room and your code?
I still don't get it man.
I talk a lot. Let me summarize.
As I started to keep my living environment in check, suddenly like the stars aligned, I gained greater insight how everything is at the length of my hand and I knew where every little thing is.
Finally I didn't have to spend too much time looking for trivial things, and most importantly, if anyone needed anything from my room, it was extremely accessible and organized.
The same principles, in my humble opinion, should be applied to our software projects.
Sooner or later someone will inherit your code.
Make sure it represents your coding skills as much as your organization skills.
Keep your room clean.
Top comments (0)