It will make them better, promise

Steven Curtis

Feb 2·4 min read

I’ve written one or two articles on Medium in my time, and most of them are based around creating a journal around my programming adventures, primarily coding in Swift.

Then I discovered that it is all too difficult to read

What is worse is that I made the same mistake multiple times, in different ways. You might think that isn’t possible, but I’m here to tell you that it is, in fact possible.

Code blocks

So what I started doing, in the beginning was to simply write code in one of Medium’s code blocks:

print ("Hello, World!")

It is all clear, understandable and easy.

I spent a lot of time copy-pasting this box into different articles. Yet there was always a shortcut that could have come to my rescue:

Mac: Command⌘ + Option + 6

Windows: Control + Alt + 6

Linux: Control + Alt + 6

or, you know what, you can write the backtick symbol three times (```) on a new line and you’ll jump into code block mode. This gives you a block like the following:

This is fine. Then I started to have some articles that were on multiple lines.

import UIKitclass ViewController: UIViewController {override func viewDidLoad() {super.viewDidLoad()let foo: NSArray = NSArray(array: [5, 6, 7])let bar = foo as? [Int]print(bar?.reduce(0, +))}}

Yes, I can get rid of the bold with a Command⌘ + B, but the formatting is absolutely awful. I spent some time using spaces and tabs to try to make my work less poor. I wish I had that time back for Animal Crossing or something, as it was simply wasted doing that.

Images of code

I thought it a great idea to give dark mode images of Swift code. In some examples of this, I would take screenshots of my code in Xcode and paste them into Medium. I understood that some really like to copy-paste code, and to help them out I’d use gists.

That is, I’d go to https://gist.github.com and copy-paste my own code in.

at the bottom of the screen there is a button to “create secret gist”, and by pressing the arrow beside this we can replace this with “create public gist” which is of course the right option to allow other people to see my work. I could then get the share link from the Gist (by selecting it and then copy-pasting the link itself).

Now using https://carbon.now.sh I can get a nice image of this code, and use this link underneath as a subtitle!

Which is all quite nice, right.

WRONG.

Improving Gists

When a user clicks on the Gist they get a redirection notice. That isn’t the greatest. Then we see the horror that is missing syntax highlighting, that is it is all rather black and white.

To solve this we only need to change the name of the gist to (in Swift’s case) something .swift (OK, think of this as *.swift).

Here I’ve created a better.swift gist:

Actually readable

The best solution

Now that there is a gist with highlighting, why not use that directly in the Medium post?

By selecting the address of the gist it can be copy-pasted into Medium, and the gist will appear.

Users can now copy and paste directly from this work (good for them) and nobody has to spend time creating and saving all of those image files.

This is so much better for everybody involved.

This is the way that things should be done.

Conclusion

If you follow along with my posts you will see the “old” way of doing things popping up every so often. This is partly because I’ve a lot of articles to still publish, but don’t fear I’m getting through them and over time you’ll see more of the Gists published in the Medium articles over time.

This makes things easier to read, and even easy to maintain for me over time too. So it is better for everybody — which should help everybody!

The Twitter contact:

Any questions? You can get in touch with me HERE