Tag: best practices

Metasyntactic variable

Metasyntactic variable

A “standard list of metasyntactic variables used in syntax examples” often used in the United States is: foo, bar, baz, qux, quux, corge, grault, garply, waldo, fred, plugh, xyzzy, thud. The word foo occurs in over 330 RFCs and bar occurs in over 290. […]

Due to English being the foundation-language, or lingua franca, of most computer programming languages these variables are also commonly seen even in programs and examples of programs written for other spoken-language audiences.

Semantic Versioning

A lot of my work these days is all around web projects, where versions aren’t particularly used.  Code is written, tested, and deployed multiple times a day, rather than once in a while.  But if you are doing scheduled releases with major and minor changes, backward compatibility and so forth, please consider using Semantic Versioning.

In systems with many dependencies, releasing new package versions can quickly become a nightmare. If the dependency specifications are too tight, you are in danger of version lock (the inability to upgrade a package without having to release new versions of every dependent package). If dependencies are specified too loosely, you will inevitably be bitten by version promiscuity (assuming compatibility with more future versions than is reasonable). Dependency hell is where you are when version lock and/or version promiscuity prevent you from easily and safely moving your project forward.

As a solution to this problem, I propose a simple set of rules and requirements that dictate how version numbers are assigned and incremented. For this system to work, you first need to declare a public API. This may consist of documentation or be enforced by the code itself. Regardless, it is important that this API be clear and precise. Once you identify your public API, you communicate changes to it with specific increments to your version number. Consider a version format of X.Y.Z (Major.Minor.Patch). Bug fixes not affecting the API increment the patch version, backwards compatible API additions/changes increment the minor version, and backwards incompatible API changes increment the major version.

Readme Driven Development

If you’ve ever had a project without a README file hosted at GitHub, you know the recommendation message to create one.  When I first saw that message, I thought it was a bit weird, but, I guess, fine.  It never bothered me enough to search for any explanation – I just ignored it, or created a README file.  Apparently, there is an explanation – Readme Driven Development by Tom Preston-Werner, one of the GitHub co-founders.

By writing your Readme first you give yourself some pretty significant advantages:

  • Most importantly, you’re giving yourself a chance to think through the project without the overhead of having to change code every time you change your mind about how something should be organized or what should be included in the Public API. Remember that feeling when you first started writing automated code tests and realized that you caught all kinds of errors that would have otherwise snuck into your codebase? That’s the exact same feeling you’ll have if you write the Readme for your project before you write the actual code.
  • As a byproduct of writing a Readme in order to know what you need to implement, you’ll have a very nice piece of documentation sitting in front of you. You’ll also find that it’s much easier to write this document at the beginning of the project when your excitement and motivation are at their highest. Retroactively writing a Readme is an absolute drag, and you’re sure to miss all kinds of important details when you do so.
  • If you’re working with a team of developers you get even more mileage out of your Readme. If everyone else on the team has access to this information before you’ve completed the project, then they can confidently start work on other projects that will interface with your code. Without any sort of defined interface, you have to code in serial or face reimplementing large portions of code.
  • It’s a lot simpler to have a discussion based on something written down. It’s easy to talk endlessly and in circles about a problem if nothing is ever put to text. The simple act of writing down a proposed solution means everyone has a concrete idea that can be argued about and iterated upon.

Consider the process of writing the Readme for your project as the true act of creation. This is where all your brilliant ideas should be expressed. This document should stand on its own as a testament to your creativity and expressiveness. The Readme should be the single most important document in your codebase; writing it first is the proper thing to do.