Cover Image by Memed_Nurrohmad from Pixabay
Whether you're doing your own lesson plan as a self-taught programmer, attending a bootcamp, going to a college, or are in any other learning situation, it's important to stay organized and keep track of projects you care about or need to submit.
How you choose to organize your projects is up to you. I'm in my final semester of college, and I've seen it done in a variety of ways. I also see this question asked online occasionally, and it's one I asked before too. There are a few good tips I've learned, and I thought I'd share them in a short post.
I currently keep my projects in GitHub repositories and will refer to that method in this article, but you can check out some good alternatives here as well.
Public vs private repo
Hands down, you want to make your GitHub repository private.
Typically, other students are also in the class working on the project at the same time as you. If you make your repo a public one, that means everyone can see your code. That includes your classmates.
Many, many, many professors and teachers will say that if someone else uses your code, you are also at fault for letting them have access to it. Doesn't matter if you intended for it or not.
Even when the class is over, I wouldn't recommend making it public. Future students may copy the code, and that serves no good purpose.
Plus, your class may have some special rules about whether you're allowed to make certain code public or not. It's always best to err on the side of caution and keep the repo private.
If you want to show someone your code, you can always share it with them privately. A simple way to do that would be to send them the project in a zipped file via email or on the cloud (OneDrive, Google Drive, etc). If you need to work with a partner on a project, you can add them as a collaborator and that will let them access the private repo.
One course per repo or one project per repo?
Should you make one GitHub repo for each programming class? And then store every project in that repo?
Or is it better to make one repo for every project?
Again, it's really up to you. You could try both out and see which
one you like more.
Here are a couple of pros and cons for using one repo for one class, with a sub-folder for each project.
| Pros | Cons |
|---|---|
| All the code for your class is in a single location. | Harder to use the GitHub search feature for an individual project. If you search for a particular phrase, any relevant results will appear, possibly for multiple projects. This can make it harder to navigate the results. |
| Quickly refer to the other files when working on a project in your code editor. | If each project is a stand-alone project, and especially if they are unique to each other, then it may not make sense to keep them together in one repo aside from the fact that they were part of the same class curriculum. |
I usually prefer to make one repo for every project. It feels more organized to me that way, generally speaking.
But I have used a single repo to keep multiple projects that were part of the same class a couple of times before. In those cases the projects were either building on top of the same code (so really it was one project split into multiple), or they were just very closely related so it made sense from an organizational perspective to me.
The README
Always include a README. If you have one repo for each project, then you should have one README for each of them.
If you have one repo with multiple projects, I'd suggest a main README for the repo as well as one README inside each project folder.
The main repo could just have the basic description of the class or types of projects, and you could even have a section that describes each project with a link to that project folder.
README basics
Don't get stuck on trying to make your READMEs look perfect. Remember, you can always add onto them later. For now, just include the most basic essentials.
It may depend on your project, but generally you will want the following in your project README:
- Project description
- How to run the project
- Any special requirements to run it
As you work through the project or towards the end, you can add other features too. Screenshots are wonderful to include, or examples of using the project or what the output will be, and if necessary what it means.
Since it's a private school project, you will probably be the only person to ever see the code. However, keep in mind that you may want to show someone your work later on (like when applying for a job). Even if you are the only person who will ever see it, it is still a good idea to document the project as if someone else may eventually see it or work on it.
Writing a good README will become easier as you get more practice. Another nice thing is that after you have a README for one project, you can always copy that file and use it as a starting point for future projects.
You can even use a README generator such as this one if that makes it easier for you. For private school projects though, this probably isn't needed quite as much.
README usefulness
You might not think you need a README at the time of working on the project. After all, you're well aware of how to run it while you're actually working on it. However, it may prove to be very helpful to you later on.
Maybe months later you will be working on something else, and realize that you have a problem similar to one you experienced in a past project. So you want to look at it again.
Well what if there is no README? You'll have to remember which project it was (perhaps solely based on the repo title) and how to run it. Even if it seems obvious to you at the time, it may not be obvious at all after you've moved on from it.
README template
If you don't have any READMEs to go off of yet, I have a couple of resources for you. One is a list of awesome READMEs. This is a great source for inspiration.
You can also copy the snippet below into a README.md file as a basic starting point.
# Project Title
> Short description of project.
## Quick Start
1. Clone or download the repo
2. Run `npm install`
3. Run `npm start`
If you need a cheat sheet for markdown (used for formatting README files), there is a great resource for that here.
Conclusion
How you organize your school projects is ultimately up to you. You should do whatever will help you be most successful! That can look different from person to person. If you aren't sure what that looks like for you yet, don't worry. Just try out things you think might be good, see how you feel about it, and make changes as needed.
Just remember to make your school repos private and always include a basic README file. You'll thank yourself later!
This article was originally published on my personal website's blog, Joy Bytes.
Top comments (0)