TLDR; People seem to be nervous about releasing code to Github in case it isn’t good enough, or it reflects badly on them. I release code that I created that I found useful. Over time it leaves a trail of code that builds into a portfolio. If I judged it, I would leave no trail. Release. Build a portfolio.
In my Open Quality Conference talk “Your Open Source Portfolio and Profile” I encouraged people to release as much as possible. By doing this regularly you organically build a portfolio.
Some people don’t like to do that because…
- they think their code is not good enough
- they think they will be judged
- they think the code isn’t ‘big’ enough
And the danger is… they never release any code, they never build a portfolio, they never learn to use Github.
I’ve released over 100 repos on Github.
They are not all High Quality Super Apps.
Some people might not view any of them as High Quality… I don’t care.
I wrote them, because at some point they added value to me, or my learning. I released them to demonstrate what I learned and because someone else might find them when they need it. They might be at the exact point I was in my coding journey when I created the code so this might be just the right code example to help them move on to the next step they need to take.
I Want You to Share
This is part of an intermittent series of posts looking at some of the repos, why I released it, what I learned. And hopefully, you’ll see that:
- “Hey, I have better code than that”
- “I have a code example as small as that”
- “I didn’t know I could release something in that state”
And as I write them up, I’ll see if I can add any polish to the repo to make my profile better.
So first up… “Find Dupes and Delete”
Find Dupes and Delete
I think this was the first repo I ever created.
I released it because:
- I didn’t know GIt, I was mainly using SVN and needed to learn this new and upcoming technology
- I knew no-one was going to be watching my profile, and no-one would see it anyway
- It was a simple enough example to start with
Why I wrote this?
I had initially converted my cd collection to wma because I was on Windows, and then I got an mp3 player and needed to convert the files. And I ended up with a lot of duplicated files.
I looked around for tooling to find dupes, but after hunting for an hour or so, I thought it would be easier to write my own script.
Is it a Script?
The concept of ‘script’ might suggest a scripting language. But I already knew Java, so I wrote it in that.
What is interesting about this tool is that it isn’t an app, it isn’t a script, it is an
I often write small tools as
@Test methods because they are easy to:
- hack out in the middle of a project
@Disabledthem so they don’t interfere with a project
- run from the IDE without having to package into an app and write a
- refactor into an app later if I need to
I wrote up this approach as blog posts:
As an example, the code that I run every month to automatically collate all my Patreon content into pdf ebook for subscribers, is a set of 4 tests that I amend some configuration data for, then run in sequence, to create the pdf (often 100+ pages). I’ve used this for over two years, and it still runs as
@Test because I find it easy to configure from code. I don’t need to refactor it into an app, code in the IDE is a perfectly good GUI for this user and this use-case.
And the script that I use to automatically generate the images for these blog posts? … still an
@Test method in a project.
Is it good code?
- It isn’t really a project, there is a
srcfolder but no
- the class isn’t in a package
- to run this you’d have to copy it into a project with JUnit 4
- I have hard coded paths, I didn’t amend this to make it easy for people to re-use
- it’s not super robust
- It is easy enough to read
- It does have a
readme.mdso I know what it is for
- It is public domain so… does it matter?
We don’t necessarily need to package it up for other people. If it is simple enough then it is often easy enough to use. Code on its own can show up via a Github search or on the code search engines. People may simply be looking for examples of how to use a particular code construct or library.
Of course, if is an application, then it really should be runnable, and you should include the full source. Uploading a ‘zip’ to Github isn’t the best way to showcase your skills (although I’m pretty sure I have at least one repo where I’ve done that).
Should I have released it?
If I was an employer, looking on Github and the employee had this code, I would view it favourably.
- It solves a problem
- It isn’t badly written, but it could be improved
- It is an
@Testmethod, so it can get away with not being packaged as a maven project
- It can act as a talking point to find out “What has the person learned since then?”, “What would they change now?”
- It demonstrates a basic familiarity with Github
- It is a practical example of tactically automating without any frills or complications
When people ask me for help via email or on Patreon I often ask them to send me their github link so I can have a look at sample code that illustrates the problem they are working with, or I can help them boost their confidence or improve their profile with a few tweaks to their released material. If they haven’t released anything, then the advice will lack context and they may not take action on it.
Something like this I might now release as a gist instead of a Github repo.
But, I’m happy that it was a repo because I learned from creating it.
If you do create a repo as small as this then do add a
readme.md, in fact, always add a
readme.md it doesn’t take long. And if you create a project on Github, creating one with a readme by default can make it easier to clone and get started.
I don’t know if I would be able to find this code if it was on my hard drive, it might still be there, but having it on Github means I can delete stuff like this and not bother about it.
If I was to release this today I would have it packaged in a project with a
pom.xml to define the dependencies and make it eaiser to run, but if I did that… because it was easy to run, I would have to amend it first to make sure it didn’t run until the path to scan and delete files from had been configured.
This repo got me started. If I hadn’t released this, I might not have released any of the other code that I have created.
The most important thing I take from this, as I review it now, is to just get started:
- find some code that works
- create a repo
- write a
readme.mdthat explains the code
- add the code to Github
Then keep going.
I didn’t start with 100+ repos and 000’s of lines of code. I started with “Find dupes and delete”.
You don’t have to pressure yourself into writing a lot of code regularly.
You don’t even have to release code. If you can write markdown, then you could create a
readme.md that is a list of ‘cool web sites I visit’ or ‘best songs to listen to while watching birds paddle in the rain’ or ‘an awesome list’.
Start small. Build incrementally. Add value for yourself or others. Iterate.