A Trail of Code

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.

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

https://github.com/eviltester/findDupesAndDelete

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 @Test

I often write small tools as @Test methods because they are easy to:

hack out in the middle of a project
@Ignore or @Disabled them so they don’t interfere with a project
run from the IDE without having to package into an app and write a main method
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 src folder but no pom.xml
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

But…

It is easy enough to read
It does have a readme.md so 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 @Test method, 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.

Reflections

Something like this I might now release as a gist instead of a Github repo.

https://gist.github.com/eviltester

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.md that explains the code
add the code to Github
publish

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.