README Driven Development

Today I had an excellent idea, only to discover that someone had already had that excellent idea some time ago.

I’m in the process of designing and writing an npm module, but before I go ahead and write it I want some feedback on whether it’s going to be useful. Rather writing a docs/slides/e-mails to descibe what I intend doing I had my excellent (but, it turns out, unoriginal) idea…

“Why don’t I write the README.md that I’d expect to check into GitHub, get some feedback, and then write either write the code or adjust the README.md until the feedback is good!? Hey! I’ve just invested README Driven Development!!”

It turns out it’s not a stupid idea, and because of this Tom Preston-Werner blogged about it in 2010….

http://tom.preston-werner.com/2010/08/23/readme-driven-development.html

Anyway….it’s a good idea, even if it’s not an original idea, and I’m finding it very useful.

I make sure my README.md has the following parts:

  1. Installation (how will people get the code once I’ve written it)
  2. Code examples of it in action (the cannonical use cases for what you’re wrting)
  3. Links to further reading (information that will be useful to the user of your code)

I want to make sure that others can quickly give feedback that the approach makes sense, the sample code looks good, and that they’d want to use the code. If you can’t write a README for what you’re about to build, show it to people, and have them say “Hey! That would be really useful!” then you need to ask yourself to hard questions about what you’re writing and whether it has value.

If you take this to an extreme, perhaps you should only start writing the code when your GitHub repo gets some stars, or people start opening issues saying “Where’s the code? I want to install this package and can’t find it on npm!”. Thsi would be similar to Lean Startup techniques where interest in a service or product is determined by building a basic marketing site and seeing if people click the “buy now” button, or sign up for more information.

One thing to keep in mind if you’re doing this in public on Github: make it clear, somewhere near the top of your README.md, that the library/code/package you’re describing doesn’t exist yet. I like to include this in the Installation section of the README.md, by striking out the actual instructions and adding a note like this…

README Driven Dev Warning to Developers

A Week Playing with Vue.js

I’ve spent the last week playing with Vue.js and associated modules. I have to say…I’m impressed with how quickly and easily I’ve been able to throw together some little web apps.

If you’re interested in what I’ve done, here’s the summary:

Pokemon-Vue-er: a Pokemon Search app

This was my first experiement into Vue.js, and I’ve already blogged about it here and here.

The app makes use of axios to make API calls to a Pokemon API, and Vue.js to render the results.

Pokemon Vue-er

Vuex-Notes-App: a Notes app that uses Vuex for state management

I started following a tutorial to build a notes app in Vue.js that used Vuex (the flux library build for Vue.js) and quickly realised it was written for Vue/Vuex version 1.x. I decided to keep going, using the basic structure of the app, but to write it in the latest versions of Vue/Vuex.

Vuex Notes App

Vigenere-App: encode and decode text usign the Vigenere Cipher

This app allows you to encode and decode text using the Vignere Cipher (a series of Ceaser ciphers). I build this app after a conversation with my daugher about a book she’s reading.

Vigenere App

Conclusion

I’ve particularly enjoyed using Vue.js…a joy that I’ve yet to experience with React. It’s been easy to get my head around, and has allowed me to get on and build things. If you’ve not had a chance to play with Vue.js yet, I’d recommend giving it a go.

Other things I’ve discovered this week include:

  • Surge.sh is a fantastic way of showcasing front end code
  • Vuex, as a mechansim for managing state in apps, makes a lot of sense and was easy to get up and running
  • axios exposes a very clean API for making, and processing, HTTP requests
  • I still like Python more than Javascript…but ES6 goes a long way to making JS a bit better

Playing with axios (and Vue.js) - Part 2

If you want to read Part 1, you’ll find it here

The reason I’d started to play with axios was because I’d started reading some articles about Vue.js and how will axios worked with it. So, I figured the best thing to do was to create a small app, written using Vue.js, that used axios to retrieve data.

The app allows you to enter the ID of a Pokemon, and it then retrieves some basic details and displays them. It’s hardly rocket-science, but it’s allowed me to play with a number of Vue.js concepts. I’m going to continue to add more features over time (to try out more of Vue.js).

Vue.js

I’m really impressed with Vue.js. I’ve recently been getting my head around React, and so this detour into Vue.js has come at a point where I’m still learning React. What’s striking is how quick it is to get up and running with Vue.js. My app does hardly anything, but I was able to create a component-based app, with basic routing, in no time at all. I’m going to go back to my React tutorials soon, but I’ve really enjoyed being productive with Vue.js.

Surge vs GH-Pages

At first, I was going to deploy this app to GitHub pages. I’d found an npm package that helped with this, but I ran up against a couple of issues.

While trying get things working I read a post that recommended Surge.sh, so I gave that a go. It is SO EASY to deploy to Surge, and so I ripped out the GH pages deployment and will be using Surge.sh for all of my future HTML/JS web apps.

Conclusion

In the end, the use of axios in the app was pretty trivial. The learning curve required to get up and running with axios and Vue.js was very shallow, and I felt productive with both in a short amount of time. I’ll be playing with both of these in the future.

Playing with axios - Part 1

It’s often the case that I start doing one thing and end up falling down a rabbit hole of interesting articles. Today, I was reading an e-mail from Codeship, and ended up reading through an article on their site Consider VueJS for Your Next Web Project.

At the end of that article I spotted recommendation that axios was the recommended way to make http requests within Vue.js, and so it was that I spent this morning having a quick play with axios.

axios is a really clean way of making http requests, and I was pretty impressed with how easily I could get a simple CodePen.io page up and running. I didn’t need anything other than the README.md on the axios GitHub repository to get something up and running.

My Codepen example makes use of the Pokemon API…my goto free API if I want to try something out. It’s sets up some base url config, makes a GET request for a specific pokemon, and then writes some stuff to the console.

See the Pen axios - simple pokemon api example by Martin Peck (@martinpeck) on CodePen.

It’s hardly the most comprehensive example of axios in action, but I hope you can see how simple it is to use axios and how readable the code looks.

I’ll be playing with this more in the future.

I'm Loving Jupyter Notebooks

I’ve become a big fan of the programming language Python, and have been using a number of tools to play around with the language. I’m also helping my son learn Python, and walking him through various coding illustrations.

I’ve tried a variety of tools and IDEs, including…

  • IDLE
  • The Python REPL within a terminal
  • Geany IDE
  • Visual Studio Code
  • Sublime Text
  • repl.it
  • trinket.io

All of these options have their good and bad points, but the one I’ve really fallen for is Jupyter Notebooks, from http://jupyter.org/

Why Jupyter?

I find that Jupyter is a great place to experiement with Python, but in a way that I can save and re-use those experiements. It has the casual stype of a REPL, but is document-centric so I can save my session. It also makes it really easy to take an experimentation session and augment it with comments and notes.

Installing Jupyter

I would strongly recommend not using the visual installer for Jupyter. Instead, install it as any other package, within a virtual environment. I do this so that I can control exactly which version of Jupter, and any other dependencies, I’m using. I can also then commit those package requirements into git more easily.

Here’s what I do:

  1. Create a virtual environment in whatever way you normally do this (for me, that’s python3 -m venv venv within the folder I’m going to store my notebooks)
  2. Activate that venv, and then pip install jupyter

This will install Jupyter Notebook within your virtual environment.

  1. pip install anything else you might want
  2. Run jupyter notebook to start the local notebook webserver

At this point, your browser should open and you should be ready to go.

Finally

I shall be sharing some notebooks in the near future. That’s the other thing I love about Jupyter Notebooks; it’s so easy to upload them to github.com and then either share them directy from there, or via the Jupyter website.

}