Antique shop with clutter

Beginner’s Tip: Organize Your Coding Projects

When you first decide you want to learn how to code, it’s typical to experiment with a number of different languages, code editors, IDE’s etc. Which makes it challenging to figure out what the best way to organize your coding projects will be. I too went through this struggle and I want to share a few of my thoughts on managing many projects in many different languages and environments.

First, a quick preface

Having a solid structure to the way your projects are stored on your local machine can be both a headache saver and a time saver as well. Especially in the early days of coding, we all tend to create many, many small projects that we usually like to keep around for sake of reference.

I for one, accumulated more than a hundred tiny micro-projects and code snippets within just a couple of months. This was mostly due to the speed at which I was following tutorials, but I also spent a lot of time spinning up projects for the sake of quick experiments. Experimenting was, and still is, the number one way I learn to code.

Having those projects available for reference while I was working on larger ones, helped me a ton, and I imagine most – if not all – beginner coders will use this repository of micro-projects as a handy reference to help get them through more interesting pieces of work.

The problem, obviously, is that when you’re new, you also have no idea how all of this code should be organized. If you make a few wrong decisions in the early beginnings your local workspace can quickly become a disaster, and impossible to navigate.

At all stages of your career (especially the early stages) you’ll come across problems that you’ve solved before. It’s pretty handy to reach into a “tool bag” and find a piece of code or a pattern that you’ve implemented and documented before.

So to help you achieve that convenience, here are a few of the things I did wrong, and what I do now to keep my projects better organized.

What not to do

Improper use of hammer and wrench

Nesting

This is by far the biggest mistake I made when I first learned to code. I tried to organize tiny little projects (many of them were just code snippets) into a deeply nested hierarchy of directories.

This nipped me in the butt for two reasons: 1) I eventually couldn’t keep track of what belonged where, and 2) when I graduated to using a command line, it become way too much typing to find projects.

The main problem for me was that I was in a highly experimental stage of my career. I didn’t know exactly what my first programming job would be, and I didn’t know for sure which language or stack of technologies to focus on.

In the early days, my decisions were largely guided by which tutorials suited my learning style best. If I found a source of information (YouTube videos, articles, books and other resources) that played well to my learning style, I would adopt that stack for that reason alone.

So I would try to categorize things and I ended up with a folder structure similar to this:

python
C++
javascript
java

My intent was to achieve something like this:

python
-- snippets
-- algorithms
-- -- sorting
-- -- searching
-- data-structures
-- -- collections
-- -- -- linked-lists
c++
-- snippets
-- algorithms
-- -- sorting

etc etc...

At the time, I liked this, and if you’re also suffering from indecisiveness like I was, you might think this a decent way to organize your code projects.

But it’s not. It’s terrible. The intention is pure. But it does not play out the way you would hope.

The problem is that you often come across situations where a project belongs in two or more of the categories you oh so cleverly laid out. In the early stages, you can probably refactor the folder structure to accommodate for the oversights. But eventually, these folders become so bloated that re-arranging folders in your file system will actually chew up a lot of your system resources and actually slow your machine down.

So then you start putting the needed refactoring off. You decide that it’s such a hassle and time consumer that you need to block out an entire afternoon or a Saturday to fix it. So you just press forward throwing scripts and snippets into folders you’re not sure they belong.

Then one day, a month or maybe even two has gone by, and refactoring this folder structure can no longer be achieved in a single day. You just start losing track of what goes where and what might be duplicated and what’s not. It can become difficult to keep track of what’s properly backed up and what isn’t also (which will lead into another tip further down).

I let it get so bad, that it took about 2 weeks of dedicating 2-4 hours a day recovering from this horrid mess 😐

The other problem, which I won’t spend as much time discussing, is that this structure is not command-line friendly. The example above uses command-line friendly names such as, this-spinal-case-name instead of space-separated like This Name. I’ll come back to that in the “What to do’s” section.

But even if I did use that convention back then (which I didn’t…), it still would have been a nightmare. It’s just too much typing, and because everything is broken down into such granular directories, it’s also not possible to create and manage aliases for quick navigation.

No matter your chosen path, you will eventually use a command line. Depending on what you do, it’ll be sooner than later, but you will without a doubt eventually use one. So don’t ever use a folder structure like that! Ever!

Don’t organize by language

This really stems from the “Do not” stated above. However you could strive for a flatter folder structure but still organize by language, so I want to warn against doing this as well.

Conceptual Aside:

One thing I highly recommend for new developers is picking a base language as early as possible. The sooner the better. Technically if you have a language to focus on, organizing by language shouldn’t even really be a problem. However, realistically you’ll probably jump around from one language to another in the early stages before you find your focus.

If you did organize this way, I wouldn’t dislike you or anything dramatic like that. You could do worse things. But organizing scripts and files this way was a major pain point for me personally. It may work out for you, but I advise against it.

The thing is, a lot of your projects may, over time, start including more than one language. If you’re learning web development this will certainly be the case, and it will be true right from the get-go. HTML, CSS and JavaScript are your minimum language stack for web development. Other disciplines will eventually lead you into making use of more than one language as well (even if it’s just a query language like SQL, or styling like XAML).

Instead, I’d recommend a “sandbox” for each language, and we’ll get to what I mean by that in the next section.

What you should do

You don’t have to follow everything I do exactly. Everyone has their own preferences of course. But for those who are just starting out, I think following closely to how I organize projects is going to save you a lot of headaches down the road – which is why I’m sharing this.

Use GitHub

This is the first major commitment – no pun – you should make as a newbie. You don’t necessarily have to use GitHub (you could use GitLab or Bitbucket), but you should definitely be hosting your projects online and be using version control software such as Git.

If you don’t know what Git or GitHub is I’ll briefly explain. Git is a tool that helps you keep track of different versions of your software (or small projects). Have you ever wanted to experiment with code but were afraid of messing up your current project? Without versioning software like Git, you would probably copy your entire project and name it something like my-project-branch or something.

With Git, you can achieve something similar but with the benefit of not having to manage merging code from one branch to the other manually. It’s also incredibly powerful for working with teams, and it’s the standard for how open source projects are built today.

Another major use of Git, is the ability to revert back in your code base. If you need to go back and see what a section of code looked like 2 days ago or a month ago – you can.

GitHub, on the other hand, is a place where you can store your Git projects which are called repositories. By using GitHub or another similar host, you’re creating backups of all your work, and once you’re used to working with Git/GitHub it’s fast and easy too.

My biggest mistake as a newbie was not learning Git, and not using a host like GitHub. I lost a ton of awesome projects because I hadn’t managed my backups as well as I thought, and one day my primary hard drive crashed. If I had been using GitHub, those projects would still be alive today.

So why does this help you stay organized?

Well for one, GitHub will organize your projects for you. Instead of nesting language-specific projects inside of a “JavaScript” folder or a “C++” folder, you just tag your project and it becomes filterable by those tags.

It also leaves you with a flat hierarchy of projects that is easy to search through no matter how many projects you end up with.

The other reason is that it takes some of the headache away when it comes to managing backups. It’s probably not a good idea to rely solely on GitHub for anything proprietary, but for small projects, it’s better than no backups.

If you want to learn Git, but haven’t yet, I recommend this course on Codecademy as a good start.

For learning GitHub, honestly just going to https://github.com/ and signing up for an account will walk you through a “getting started” guide, and that’s all you really need to know to start off. It’s Git that has the larger learning curve. Once you know Git, learning how to use the basics of GitHub is trivial.

Also, a side note: Bitbucket and GitLab offer nice services for hosting Git repositories as well, and the advantage is that you get unlimited private repositories for free. GitHub, by contrast, only gives you unlimited public repositories – you have to pay for private.

Copy GitHub Locally – Use A Flat Folder Structure

Once I spent some time working with GitHub, I realized how easy it was to work with a flat folder structure. So I decided to reflect that organization on my own machine.

This is how I organize now (on Windows in this example):

-- C:\Users\Dan\batcave
-- -- project-1
-- -- project-2
-- -- project-3
-- -- project-etc

Of course, my projects aren’t actually named “project-1”, but there is no hierarchy now. From my home or user directory I have a folder called “batcave” and inside there are projects – which with the exception of this article, I actually refer to as repositories.

This makes it way easier to find what I’m looking for. If I want to group a bunch of code snippets together I can just make a project called “python-snippets” or “python-sandbox”. The difference is that this is not a folder containing a bunch of other subfolders, but rather an actual workspace.

So for the python-sandbox example, I have a script named: quicksort.py which is a sorting algorithm implemented in Python. There’s really no reason for me to store it in a long chain of folders, I already know what the file is just by reading the name.

In the world of JavaScript this structure is even more handy, because I configure all of my build tools to work within that workspace as well. So if I have an ES6 sandbox, for example, I only have to configure my transpile scripts once, instead of once for each tiny project or script. This obviously makes way more sense than my old way of doing things.

Use A Cloud IDE For Small Projects

It’s unfortunate to see how far behind the times software development is. Office administrators have had cloud applications for making documents, slide shows, spreadsheets and all the other typical office applications in a collaborative, accessible way that keeps your local machine nice and tidy for years.

It’s only recently that software developers have had access to cloud IDE’s, and they are for the most part only realistic for web developers.

However, they can still help tidy up your local machine, by moving some of your smaller projects onto the cloud.

So what is a cloud IDE? It’s an IDE that runs in your web browser. Usually, you will get a virtial box running a Linux OS such as Ubuntu, and a bit of memory and storage for each project you host on the service.

My current cloud IDE of choice is c9.io. The free version gives you unlimited public workspaces. Think of a workspace on c9 as it’s own machine running Ubuntu, with enough storage and processing power for most small to medium sized projects.

It’s especially nice for sandbox projects, because they never need to be on your local machine. You can still have a Git repository on GitHub to backup the code base, but the code and all of your assets (images, videos, icons etc) also are living on your c9 workspace.

The benefit here is that you can access this workspace from any computer with a web browser and don’t have to install anything.

It’s also incredibly fast to spin up a new workspace when you want to run an experiment or try out some new library or framework.

You can use it c9 for professional work as well, which I do, but it has some draw backs.

The main downside has been the editor. I haven’t found a way to configure things like linting the way I want, and I also prefer other editors like Sublime and VS Code, which can make working in c9 a bit of a pain at times.

Another issue, is that if you want to use it for any desktop applications that require a GUI, then c9 isn’t going to work. It’s really only meant for web development.

So although you can’t move your entire development environment over to the cloud, you can probably move enough to help clean up your local hard drive. Recently I’ve been trying to keep as few projects on my local machine as possible. If I haven’t been working on a project for a while, I’ve been in the habit of deleting it – if I need it, it’s as easy as git clone path/to/repo

What it becomes especially useful for is whenever you want to follow a “getting started” guide for a new framework or library you’re interested in, or maybe just a tutorial on YouTube or whatever.

Name Projects With spinal-case

I briefly mentioned this above in this article, how I used to name projects with capitalized letters and spaces. If/when you start using command line interfaces this will be a huge pain.

Here’s a simple example:

I create a project in my home directory under batcave and call it, My New Project. Here is how I would navigate to that directory from a CLI.

cd batcave/"My New Project"

I actually have to remember those quotes or this command won’t work. Also in *NIX systems, you have to remember the case too, because those file systems are case sensitive, so “My new Project” is not the same as “My New Project”.

If instead, I had named this project using spinal case like my-new-project, this is how I would navigate via CLI.

cd batcave/my-new-project

So much easier!

It is also a lot less prone to error as well, which means I don’t have to retype mistyped commands as often.

What About IDEs That Organize For You?

Most IDEs (Integrated Development Environments) will create a workspace directory for you and all of your projects will automatically be saved there.

Personally, I’ve just left defaults as is, and if I want to find a project that I started in Visual Studio or Eclipse, I just open those directories. It hasn’t been an issue for me to just go with the default organization.

Most IDEs are set up to keep you out of the command line, or if there is one it’s integrated anyway. So there’s no reason to worry about ease of navigation in your favourite shell. Usually, if you dig into advanced settings, you can change the shell that the integrated command line uses too, so that eliminates most inconveniences related to that.

One gotcha of using a full-fledged IDE though, is that I’ve found Git is usually a bit of a pain to set up at first. There are usually files that are specific to your IDE setup, that don’t need to be in your repository. In the past, I’ve just googled for common .gitignore files, and with some minor tweeks, I’m good to go.

Summary

Okay, so to recap:

  1. Leave IDE defaults alone.
  2. Use a cloud IDE when you can (most have decent free services).
  3. Learn Git. (This should probably be ranked number 1).
  4. Use GitHub, Bitbucket, or GitLab for hosting your projects.
  5. Keep your local repositories flat. No nested folders of folders!
  6. Spinal case your project names.

Like I said at the beginning, I messed this all up really bad when I started out. Not knowing exactly how to keep my projects organized was a massive pain point for me, which is why I’ve gone into such depth with this article.

I hope other newbies that are in the same shoes I was can find this article hugely beneficial and avoid the headaches I endured for my mistakes.

Also, I’m interested in hearing what solutions others have come up with for keeping things organized. If you have better, or more interesting alternatives, let me know in the comments below!

And don’t forget to spread the love if you enjoyed the read. Like me on Facebook, tweet me, whatever – I appreciate all of it!

Cheers,

Dan

 

 

 

 

 

4 thoughts on “Beginner’s Tip: Organize Your Coding Projects”

  1. Good stuff, Dan. It can definitely pay off to change the default folders that are set up by the IDE, though. For example, with Visual Studio, my projects end up in C:\%userprofile%\Documents\Visual Studio 2015\Projects” and there are spaces in that. This is how I have used it for ages, by default, and reading your post, I can see where it has caused me problems that I’ve ignored.

    I have done a bunch of the c# exercises on exercism.io, and to upload you have to use the command line, and I’ve now gotten in the habit of using the quotes, but at first, and when I go back after a break, I always end up botching the first attempt.

    I do sort my projects into a hierarchy, though. I’ve got a folder for my church projects, one for IoT projects, one for code katas, and so forth. I think this is a good idea, but I do believe that you are right in that the hierarchy should not go deep at all.

    Great tips. Thanks!

    1. Ah, yeah that’s a good point Rich. I guess if you’re IDE doesn’t have a great integrated command line it can definitely be an issue with the long path name and spaces.

      I think your shallow hierarchy is probably fine, and of course, it comes down to preference. I prefer going completely flat. Especially on a lighter laptop, I notice searching is much faster in a flat folder structure than a nested one.

      Thanks for taking the time to read and comment!

  2. Thanks for the helpful tips Dan. I’m totally doing the noob mistakes myself, nested folders, not using git or cloud IDE’s. In the near future I’m going to make the changes you suggest!

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.