Category Archives: Programming

Symfony Live London 2014

Symfony Live London was last Friday which was great, and I’d recommend it to anyone in the Symfony world.

I’ve said for a while that Symfony is the lead in the Clean Code area of PHP, so it wasn’t surprising that many of the talks were about that, rather than Symfony itself. I stuck with track one all the way through, and all of the talks could be considered talks more about clean code than Symfony. Many were about writing code that works easily with Symfony but not for it. Matthias’ talk could have just as easily been called “The Framework Trap”, to go along side Jakub’s.

One of the disappointing aspects of the conference for me was that it felt a lot like receiving lectures at university for some talks. “Here’s, academically, how you fix this problem in a controlled, greenfield environment.” The best talks I saw looked at specific issues, like Konstantin’s. He was telling a story here, rather than teaching. Teaching by storytelling has been the way humans have learned for thousands of years, and there’s not nearly enough of it now.

I’d love to go to a conference dedicated to people telling stories about working on their (possibly legacy) projects and making them better. Some of the talks should be able how they did that and completely failed – losing months of dev time and ultimately ending up with a worse product. Technical discussions on how they realised they were crowbarring a design pattern that didn’t fit (emphasis on how they realised). MyBuilder could come and tell their story. phpBB could tell us how their move to Symfony was. I’d pay for that.

Dangling underscores

A pull request at work sparked a bit of conversation[1] about using underscores in JavaScript to describe a function as being private. It was this code specifically:

Because our logic isn’t as separated from our database as we’d like, many of our API tests touch the ES database. In order to avoid futsing up our actually data, we just want to make sure it’s only ever talking to indexes starting with “test_”.

My suggestion was that we should refactor this so that we don’t need to be exposing what should be a private method.

The argument was that this is a private method; it’s convention in JS to just use this underscore syntax. But that argument really just comes down to “that’s the way it’s always been done.”

This was fine back in the dark days of JavaScript, but we’re much more organised these days. And as our industry grows more mature it’s our responsibility to keep up with it.

Leaving something public really limits how much you can change later – regardless of it being an “underscore private method” you’re still letting others see it, and you’ve no way to know that it’s safe to delete that method once you’ve changed your implementation.

Even if you know that’s not a concern,[2] it’s still a good habit to get out of. And a free one at that.

[1] Which had nothing to do with the feature set being added, as always seems to be the case: comment on the low hanging fruit, rather than the structure or flow of the code.

[2] In this example, the proxy probably won’t be used again and has no need to be extended.

On keeping git clean for pull requests

There’s lots of places that you can find talking about how to write a good commit message. Some will even give good technical reasons for doing so, but only a few will give you actually good reasons. When’s the last time you had to use git log --oneline or send a commit via email? Maybe Linus does this everyday, but you don’t.

The one reason I find most important when you’re thinking about the git history as a whole (not just on a per-commit basis) is during peer review. In my current work place and my last the way we did code reviews was by a collogue pushing to github, and opening a pull request. It was then someone else’s job to review and pull that in. That seems to be a very popular workflow from talking to a number of tech teams the past few months whilst interviewing.

Forget about being easily able to look back in the project’s history and see why something was changed, or being able to see a good message on git bisect. They’ll come incidentally with the following method.

Review is the one stage in product development when you’ll be reading commit messages the most, but it seems like no commit messages I’ve encountered recently, at the very least on my team, are written for that part of the process.

Failing to describe the scope of the message

The first thing I want from a commit message is to know the mindset I should be in whilst reviewing. What are you trying to achieve with the code change you’ve introduced? This Doctrine commit message could be slightly better by saying “always add ‘isEmbeddedClass’ to the serialise array”. I could look at the commit message, and at the code change and see “yup, this is doing exactly what the author wanted it to do.” From that point, I can start thinking of side affects the code change might have on edge cases.

The problem with “fix bug” is that I can’t tell what issue with the code you’re talking about, and so the only review I can do is “yep, that’s syntactically correct”. I can still think about potential side affects, but I’ve no idea if the original writer has thought about and accepts them.

Splitting one unit of work across too many commits

A unit of work should be valuable in some way. A commit should hold one unit of work. If we were to revert this one commit from your pull request, how many other commits would have to be reverted too before we got to a working piece of code? It should be as few as possible without affecting other features.

This usually happens when you’re working in stages and commit each stage. That’s fine at giving you good rollback points, but they should be merged together later on when you’re self-reviewing. An example of this is in the BrowserQuest repo, two commits right after each other with the same commit message: ae773f and 9c1d5.

A more common (and more annoying) issue is when a file has been forgotten to be added, and so the second commit is “lol, forgot to add this file”.

These are exactly what  --amend flag to git was added for; instead of adding a new commit, just push the changes into the last commit.

Never mix styling or whitespace changes with functional changes

Most teams with an old codebase have the idea to clean as they go along – that’s a good idea (rather than a huge, up front investment).

These commits should be on their own, because I’m not even going to read them. Your team mates should just be able to auto-merge these commits in (especially in a language like PHP where whitespace doesn’t matter).

The problem is that if you’re changing from tabs to spaces, the git diff will say that every line has changed. Your functional changes will get buried and it won’t be possible to see if anything will have unexpected side effects.

On Let’s Code JavaScript

I’m really enjoying Let’s Code Test Driven JavaScript, from James Shore.

His aim is to release videos overtime, showing how he’s developing an arbitrary application. Using JavaScript and Nodejs and driving the development with tests. Not just the code, but the set up as well.

The videos also come with DRM free download links.
The videos also come with DRM free download links.

It’s subscription based, but with a free trial (all access to the content, for seven days). I discovered this whilst in-between jobs and had no income, so in a time where money is heavily budgeted it’s a testament to James’s work that I decided it was worth the money.

In fact, I think it’s so important to the dev space that I’ve linked to LCTDJS in what I usually reserve for ad space on this blog. You guys need to be watching these videos, even if you already know how to write node apps – the test driven component is brilliant and getting to hear some of James’ ideas should make this a really compelling subscription.

The videos are fairly short. I think they’ve been designed that way so they’re commute friendly. I can’t imagine sitting on a train watching these videos, but maybe you can. The shortness is pretty helpful for me since I’ve now got something to watch whilst eating that’s actually productive (instead of endless Youtube). Despite being short, I’ve not yet watched an episode and thought “well, that was a waste of ten minutes”. I’ve always walked away with a new idea to think about. And there’s such a backlog of videos for me to catch up on, if you need more just watch another.

The videos manage to kick off at a really good point – assuming you know how to program. What you’re learning really is the methodology behind programming (the thing that good programmers focus on). Where you should be spending your time. The code is often secondary to how well it’s tested. The best practices talked about in the series really should be sitting along side industry standards set out in Clean Code.

The videos start by adding build automation and linting. Nothing to do with getting the app working, just making it work cleanly. The emphasis on this throughout the series is why I keep watching. I don’t care to watch a guy telling me the problems and features needed in a collaborative painting app. I care about how the code is designed, and how to think about the choices that come up.

The chapter I’m on at the moment is about deploying the code. It’s not something that would have been consider a software developers job in the past, but now people in our job are going to find themselves more often in the command line. Faster deployment means developers are the ones pushing to live, not administrators. So it’s interesting to see how you can wrap tests around deployment. Had you every thought about TDD for things that aren’t strictly code? Because you should be.

My favourite aspect of the series is the warts and all approach. It would have been easy for James to have edited the videos in a way that just shows how to do TDD. But he also leaves in the walls he runs into. My favourite episode so far is episode 31. He starts the episode realising what he’s worked on recently is a waste of time, and then ends it by running straight into a bug. This is exactly how I program. More than likely how you do to. It’s amazing to see that these problems aren’t a reflection on me as a programmer, but they’re just part of the daily trials of every programmer.

After the Ignorant Period

I just finished reading a longform post by Michael Bromley on how he used to feel he was a much better programmer than he actually was.

I followed the example studiously, faithfully implementing all the ingenious and no-doubt cutting-edge techniques – those handy “mysql_” functions for data access; string concatenation for building queries; separating functions into a “functions.php” file; including a “header.php” and a “footer.php” to maintain consistency site-wide; shunning the bulky overhead of the object-oriented approach (whatever that really meant) in favour of lightening-fast procedural code. My skills were increasing exponentially!

This is exactly how I felt – not even that long ago actually. Even at university, I didn’t surround myself with anyone that would say they were brilliant programmers. I was the only one of my close friends that would be very comfortable going in for a weekly “viva” (coding test), and fairly confident I’d do well. And I always did.

I went onto my placement year still in that mindset. I am the best programmer I know. Oh, gosh. I couldn’t have been more offensively wrong. My overestimation of myself grew from my isolation from others who were passionate about software development, and so my story echos the same as Michael’s.

I wrote an abstraction layer over a few mysql functions: database.php. Not that I had any idea of what an abstraction layer was, and I further had no idea how awful that implemenation is. I leave that code up on github not because I’m proud of it, but because it’s a good reminder. Smarter people have written database abstract layers better than you, Shane. Just leave it to them.

My thought process quickly changed from the above, to actually wanting to learn more once I joined MyBuilder. Surrounded by a wonderful team who were smart, and better than that, willing to point me in the right direction and teach me.

That’s when I got into the opposite problem of Michael’s though. Holy shit, everyone’s a much better programmer than me. It’s pretty intimidating to go to talks and see smart people talk about really smart topics. And then you realise they’re only two years older than you or the same age.

I recently realised this feeling of inferiority was just because we never get to see how that Super Respectful Programmer handles their work. In my mind, they have this grand idea, they sit down for half an hour, and bam: an awesome finished product.

When in reality they do exactly the same as I do. They stare at the screen knowing that the bug they’re running into is a really simple one. They do sometimes go down the wrong path, and have to back out half an hour of commites sometimes. This is all hidden though. But these rockstars often aren’t super geniuses – they’re just like you, maybe with a bit more persistance and practise.

Watching the Lets Code: TDD Javascript videos has really put my mind to ease about that. Watching someone “warts and all” has been refreshing. I’ve respected James Shore for a while now, and I had no idea that he hits as many silly mistakes as me. Mistakes that take seconds to fix, but still make me feel stupid. Even with collegues – unless you’re standing over their shoulder watching – you’re not seeing how often they spend a few seconds staring blankly at their screen, unsure what’s going on.

The point I’m making is the same as Michael’s post, but that it can go both ways. Isolation from others leads you to completely misunderstand your capabilities – making you too egotistical, or underestimating yourself.