melreams.com

Nerrrrd

What’s a code smell, anyway?

in best practices, code smell, development

a rugged metal tower, possibly a lighthouse, seen at low tide on a rocky beach with puddles all around
Unrelated image from pexels.com to make this post look nicer in social media shares.

Design is one of my favourite parts of programming, but I constantly run into the problem of how to tell whether my design is any good.

Before we go any further, I think we should define what makes a good design is. My definition is that if you can change it in the future without cursing your past self, it must have been good design. You may have noticed that using that definition makes it difficult to figure out whether a design is any good until potentially months after the fact when you need to change it. It would be nice to know ahead of time whether your design is going to lead to a lot of swearing in the future, and that’s where I have trouble.

To be fair, if I could definitively answer the question of whether a design was good without having to try to change it, I’d be a millionaire and I’d be writing this post from my own private island :) Whether a design that seems good now is going to continue to be helpful in the future is just a hard problem and there’s no getting around that.

That said, I think code smells can help a lot there. A code smell is, in the words of Martin Fowler, a surface indication that usually corresponds to a deeper problem in the system. The term was coined by Kent Beck while he helped Martin Fowler with his book Refactoring.

This whole concept would probably make more sense with an example. An especially designy code smell is a class that does too much. Ideally a class should have one responsibility – if it’s concerned with more than one thing that’s a strong sign it should be broken up into separate classes. The specific problem with a class that does too much is that it’s likely to lead to long, messy methods that do too many things and don’t make sense because of it, and it generally makes it hard to reason about your system. The more one class does, the more state it’s likely to need to keep track of, and the more state one class keeps track of, the more chances you have to completely mess it up. You may have gotten a hint here that software design is about accepting that humans are bad at it and trying to work around that basic fact :p

The thing with a code smell is that it’s not a hard and fast rule, it’s just a hint that something could be wrong. Sometimes it can be reasonable for a class to do “too much,” it depends on the exact thing you’re trying to accomplish and the context (i.e. the rest of your application) that your class is part of. Having a good design is more about the thing you’re trying to accomplish than it is about following all the rules whether or not they make sense in your particular situation.

The great thing about code smells and design patterns and all that is that they let you take advantage of other people’s experience. Can you imagine how long it would take to get good at software design if you had to make all the mistakes yourself? I love hearing what other people have messed up so I can maybe avoid that particular problem. And from the other side, I’d love it if anything I’ve told another dev helped them avoid a problem. It’s all well and good if I solve a problem for myself, but if I can help a couple of people avoid the problem in the first place and if those people help a couple other people avoid that problem, then I’ve done much more good than if I quietly fixed my own code and moved on.

Stay tuned for more posts about code smells, there are plenty of them to get through :)

Javascript tip of the day

in development, javascript, tip of the day

Javascript has a delete operator! Okay maybe that’s not news for people who do more frontend work than I do, but I was surprised to learn that. If you have a javascript object and want to remove one of its properties, it’s really easy. All you need to do is delete object.property. There’s more detail here if you’re interested. Now if only it wasn’t such a hassle to iterate over an object’s properties…

Ember tip of the day

in development, ember, javascript, tip of the day

Lately I’ve been working with Ember components, which are really pretty cool. For anyone who doesn’t know, in Ember components let you encapsulate layout and functionality neatly together so you can reuse things all over your app without making a huge mess.

Ember components have a lifecycle you should know about and a set of lifecycle hooks you can call. Those hooks are really handy, they let you do all kinds of things at different points in the component’s lifecycle. Be warned, though: you MUST call

this.super()

at the beginning of your lifecycle hook or your component will break in deeply weird ways. When you implement a lifecycle hook in your code, you’re actually overriding a method in the base Ember component. If you don’t call this.super(), the original function doesn’t get called and shockingly enough, it does a bunch of things that are necessary to make your component work right :)

Because Ember is open source, you can go have a look at what the base lifecycle functions do. Here’s the init function, which calls this.super() itself before it does the rest of its setup. Reading the code yourself totally isn’t necessary, but it’s interesting and might help you remember why it’s so important to call this.super().

Productivity tip of the day

in productivity, tip of the day, trick of the day

You might have noticed I like watching conference talks and recommending my favourites, and you might have gotten the wrong idea about my attention span from that :) I actually have a terrible time concentrating on watching a video if that’s all I’m doing, my mind wanders and when I come back to the video I have no idea what’s going on so I have to skip it back to catch what I missed. After that happens a few times in a row I give up and go do something else.

Fortunately, I have a trick to keep myself focused. It’s kind of a ridiculous trick but hey, maybe it’ll work for you. What I do is open up the talk I want to watch in one window, and in another window I open up a silly clicking game like Diggy’s Adventure or Clicker Heroes and play that while I listen to the talk. The reason having those open in separate windows is important is so you can alt-tab to the talk easily if you want to see the current slide.

For me games like those are the digital equivalent of doodling, they give me just enough to do to stay focused but not so much that I get distracted from the talk I’m trying to listen to. They’re also great for convincing myself that I’m really just playing games with a talk on in the background, which makes it not feel like work so I actually do it.

If you want to watch more recorded talks but never seem to get around to it or your mind wanders when you do get around to it, try a really low impact game. It might help and definitely can’t make it worse :)

What is technical debt anyway?

in development

A server room full of very messy wiring. There are so many cables connecting devices together that you can't see the devices themselves,
Actually relevant image by Happy Tinfoil Cat

Technical debt is one of those things that you completely understand when you run into it, but is really hard to explain to someone who has never worked on a large application. That picture on the left of the messy server room is probably the best illustration of technical debt I’ve ever seen, and you should definitely use it the next time you need to explain technical debt to someone.

You can guess exactly how it happened, can’t you? “I know this is the wrong way to do it but we’ve got to get this server back up NOW so just string a cable over to that other switch and we’ll tidy it up later.” FYI, that never happens just once. “Later” when it’s time to tidy it up never comes either. There’s always something more important than going back and fixing something that technically works.

Even when you have the time to make a change the right way, it’s a huge hassle because the server room is already such a mess. Eventually, it gets so bad it’s just impossible to change anything without first tidying the whole thing up. That’s what technical debt is like in code, it’s just harder to see.

Every time you cut corners to get something out the door quickly, you build up technical debt. You make a little bit more of a mess, and as the mess gets worse and worse, it gets harder and harder to make more changes, just like in the messy server room.

Just like financial debt, sometimes it’s worth taking on technical debt. And just like financial debt, you need to think carefully about it before you take on that debt and you need to have a plan to pay it off. Ignoring the fact that you have technical debt is like ignoring the fact that you’ve maxed out your credit card, it just gets worse if you don’t deal with it. Unlike financial debt you don’t directly get charged interest on technical debt, but every piece of new development you do has to work around your existing debt. If your project is dead and you don’t have to change anything then your technical debt doesn’t matter, but on a project that’s still being updated you’ll eventually have to work around the corners you cut. Every time you do that without tidying up the original mess, you make more and more of a mess until you end up with something like that server room above.

All of this is completely obvious if you’re a developer who has worked on a large project, but technical debt can be really hard to explain to non-technical people because they aren’t programmers. That photo is a fantastic visual metaphor for technical debt, which is why I think it’s so great. Once you have a metaphor like that, you can have a productive conversation about technical debt with a non-programmer because they now have the slightest idea what you’re talking about :)

It would be great if management would just trust the dev team when they say they need time to pay down technical debt instead of continuously pumping out new features, and it’s definitely an issue if different parts of the company don’t trust each other, but even when they do I think it’s reasonable for managers to want to understand what’s going on. As a programmer I certainly understand the urge to yell and stomp your feet about people who don’t understand technical debt (or why sometimes things take way longer than you expected or why adding people to a late project makes it later or why you need to make time for documentation, etc, etc), but you know, it’s a lot more productive to find a way to explain it.

What’s the big deal about years of experience in a language?

in career, development

A young cow in a sunny green field looks toward the camera
Unrelated image from pexels.com to make this post look nicer in social media shares.

A while ago I was wasting time on reddit, as you do, and came across an interesting question: “why do employers and just about everyone else make a big deal about language-specific positions and “what language should I learn”, etc.?” The greater context there was that the asker had a pretty easy time picking up new object oriented languages once they got a good handle on one of them, so they were confused about why people seem to think x years of experience in language y were so important.

I have mixed feelings about job postings that require a certain number of years of experience in any particular language. If you understand programming concepts (from low level stuff to how ifs and loops work to higher level stuff like how to keep your core business logic separate from presentation code) then yes, it’s pretty easy to apply those in whatever programming language you need to.

As a bit of an aside I think a lot of job postings are more of a wildest dreams wishlist than a useful description of what’s actually necessary to do the job from day to day. In the context of this particular question, I have a strong suspicion that when most job postings say the applicant needs “5 years of experience with Java” what they actually need is someone who knows Java and has 2-5 years of programming experience.

That said, while most programming concepts are transferable (especially if you’re using languages with broadly similar syntax), you really are more productive with a language you already know well, especially if you don’t have much programming experience. There are weird quirks of languages you may not run into at all until you’ve been working with them for a while, too.

For example, did you know in Java String.substring() used to return a “view” of the original string, not a completely separate string? And that since Java 1.7 update 6 it returns a completely separate string? Yes, that seems really minor but it can cause some weird weird bugs if you change the original string thinking it’s completely separate from the substring. And because stuff like that doesn’t look wrong, it can be absolutely miserable to track down.

Just because I technically can code in languages other than Java doesn’t mean I can do it quickly. When I need to do any front end work I spend a lot of time looking things up because I don’t remember the exact parameters basic string operations take in Javascript. If I had to write Javascript all the time I would start remembering those details, but that’s with a foundation of years of programming experience to start from. If you’re a new dev who just graduated from college/university/bootcamp, you’re going to have a harder time learning a new language because you’re also going to be learning professional programming at the same time.

Which language you learn first also makes a big difference in how hard of a time you have learning to code. In general I think you should start with whatever language lets you build stuff you’re excited about, but I don’t want to pretend all languages are equally beginner friendly either. C and C++ are good for many things but they are not your friends :) Python and Ruby are easier to pick up because they take care of fiddly details like memory management for you, and Javascript can be a good first language because you don’t need any special programs like IDEs or compilers at all, you can write it in notepad and run it in your browser.

So given all of that, why do (some) employers make such a big deal about language specific positions? Because if you don’t already understand programming really well, you need some way to find people who have a decent chance of succeeding in the position you want to fill. Sadly, not all job postings are written by people who understand the day to day work so it’s not unusual to end end up with some poor HR person’s best guess at what’s needed.

“5 years of Java experience” can also be a pretty decent proxy for “actually likes working with Java and won’t ditch us in a year to work in [cool new language of the week]”. Some languages are just not considered cool and plenty of people have a perfectly legitimate dislike of the amount of boilerplate you have to write to make Java do much of anything, so it makes sense to look for people who are willing to work with your tech stack for the long term (or at least the longer than one year term).

Readers, what do you think of stuff like “must have 5 years of Java experience” in job postings?

Dealing with imperfect requirements

in development, requirements

In a sunny green field, a wooden path curves into the distance. The sky is blue with fluffy white clouds.
Unrelated image from pexels.com to make this post look nicer in social media shares.

A very common question developers ask is what they can do about bad requirements. The internet definitely needs more opinions on it, so here’s mine!

The first thing you’ve got to do is accept you will never get perfect requirements. If anyone knew how to get perfect requirements every time no matter how large the feature was, you would know their name because they would be deservedly famous for finally fixing the requirements problem. Outside of school assignments, the requirements you get are practically always going to be incomplete in some way and probably wrong in at least one way too. It’s frustrating, I’m not going to lie, but that’s just how the job works.

I’m stressing that point so much because I want you to have realistic expectations about how much you can possibly improve your requirements gathering process. If you go in thinking you can ever get perfect requirements every time, you’re just going to be disappointed. On the other hand, if you have more realistic expectations about what kind of improvements you can make, you’ll end up a lot happier with your progress.

Now that I’ve gotten the disclaimer part of this post out of the way, there are some things you can do when you get incomplete requirements or when you work with people who often change their minds about what they want.

First of all ask questions! I touched on this briefly in my post about how communication can make you a better programmer, but it bears repeating. Communicating well is absolutely essential to being a professional programmer, and one of the many reasons it’s so important is that you need to make sure you completely understand the requirements before you build something. Don’t worry about looking stupid, ask questions about anything that you’re not sure you completely understand. Unless you work in a terrible toxic company, nobody is going to be mad that you cared enough about doing a good job to make sure you didn’t accidentally build the wrong thing.

Asking questions can get you quite a ways and is definitely worth doing, but it’s not always enough. Another really useful technique is mockups. When people can see an example and compare it to what they already have, they’ll understand it far better and will be able to give you much better direction about what they really need. It’s a lot of work for the human brain to have to imagine what the finished thing will look like, how it will work, and how you will use it all at the same time. Take a little cognitive load off of your requirements people by asking them to imagine fewer things and you’ll get better results.

There are tons of tools out there for mocking up UI, if nothing else you can throw together a quick slide deck or build a couple simple pages in HTML. Don’t forget to take a lot of notes when you walk your requirements people through your mockup, you’re working with a limited human brain too and you’re not going to remember every detail of the feedback they give you without notes.

After you’ve made some mockups and walked people through them, you may want to build a prototype before building the real feature. Once people can actually use something, it becomes real to people in a way written requirements just aren’t. It’s not because they’re dumb or bad at requirements, that’s just how humans work. Building a prototype will also bring up all the technicaly questions you didn’t realize weren’t answered in the requirements until you started building the feature. Don’t pretend you’re perfect at requirements either :)

There’s another really useful technique for gathering requirements, but unlike questions, mockups, and prototypes, it takes more buy-in from your requirements person or people. That technique is user stories (you may encounter some confusion about use cases and user stories, which seem to be similar but not quite the same thing. I just found out when I was looking for a good link to explain further that the things we call use cases at work, other people call user stories).

To very briefly define user stories, they’re a particular way of stating requirements. The general form is: as a_____ I want to _____  so I can_____. For example: as a blogger, I want to schedule posts for the future so my posts go up on a consistent schedule. It’s amazing what comes up when you think about what you users want to accomplish and why. That kind of context is really important to understand the intent of the feature, but it does take more work on the part of the person who comes up with your requirements and writes them down.

It’s pretty common for people to see all this question asking and mockup making and user story writing as a waste of time that just slows down development. If you’re willing to put in the effort, it can really help to record just how much development time gets wasted because the requirements are bad or get changed all the time. Developer time is really expensive, showing your manager exactly how much developer time gets wasted on building the wrong thing then throwing it out when you get better requirements will likely convince them that it’s worth putting a few more hours into getting better requirements.

Requirements are fundamentally a hard problem you can do everything right and still get a horrible surprise when you’re halfway through building a feature. Like everything else in development, there’s no silver bullet.

Linux tip of the day

in linux, tip of the day

Take out the trash! Unlike Windows, Linux (at least my distro, Mint) doesn’t have a recycling bin/trashcan icon on the desktop to remind you to empty your trash directory once in a while. That really adds up if you forgot to empty your trash for, uh, a while. Technically you can just hunt down your trash directory and delete everything inside it, but do you really want to have to remember the path? And remember how to find it if you delete a file on a USB drive?

trash-cli to the rescue! The terminal command to install it is sudo apt-get install trash-cli (at least on systems with apt-get), and to run it you just type trash-empty. Thanks as usual to stack overflow for that answer.

When I finally ran that on my laptop, I got 3.6gb back. Not bad for under a minute of work :) If you’re new to Linux like me, don’t forget to take out the trash.

 

Back to basics: advanced Java generics

in back to basics, development, generics

a white fox sits in the snow, looking toward the camera
Unrelated image from pexels.com to make this post look nicer in social media shares.

Last time I mentioned that there are bounded generic types and wildcards. I’ve never actually used one of those if I remember correctly, which I why I left them for a followup post.

Bounded generics are really cool – they let you narrow down which types you can use with a generic class or method while still having the flexibility to work with different types in the range you’ve defined. There are lower bounded and upper bounded generics. Upper bounded generics specify a superclass your generic type must extend and lower bounded generics specify a class your generic class must be a superclass of.

This means that you can do more interesting stuff with your generic param because you know something about what it is. Let’s use WordPress as an example. If you had a theme superclass (or probably an interface) that was extended or implemented by, say, oneColumnTheme, twoColumnTheme, gridLayout, etc you could have a theme preview page that accepts anything that extends the base theme class and calls getPreviewImage and getDescription on every item passed in, even if they’re different subclasses.

That method signature would look like:

public Result createPreviewPage(List<? extends Theme> themeList) {
    //code goes here
}

You can’t add anything except null to a collection that has an upper bounded generic type, though. Why? Java inheritance – if you have a class hierarchy of Vehicle -> Car -> Sedan -> Toyota Corolla then that Toyota is definitely a Sedan, a Car, and a Cehicle, but a Vehicle could very well be a Motorcycle or a Bus, not any variety of Car.

On the lower bounded end of bounded generics, you could have a method that takes anything that’s a superclass of integer (which could be a number or object) and adds all the numbers from 1 to 10 to it. Yes, I stole this example (and the following code) from the official docs. The code for that method looks like:

public static void addNumbers(List<? super Integer> list) {
    for (int i = 1; i &lt;= 10; i++) {
        list.add(i);
    }
}

With a collection with a lower bounded type you can add things. Taking my Vehicle -> Toyota Corolla class hierarchy above, if you have a List<? super ToyotaCorolla> then you know what the most specific thing it can be is so you can safely add one of those.

You have have a lower bound or an upper bound but not both. You can have neither, though! That’s called an unbounded wildcard and it looks like:

public boolean removeAll(Collection<?> c);

That’s from the List source code. Unbounded wildcards are for when you really just don’t care what the thing is and when you want to make sure you don’t make any major changes to your parameter. The only thing you can do with a Collection<?> is add null, you just don’t know enough about what’s in there to add an object or any sort.

In my admittedly limited experience with bounded generics, upper bounded generics are much more common so you shouldn’t be too worried if you can’t find a use for a lower bounded generic parameter. If you’re not sure when to use which kind of wildcard/bounded generic, there’s a handy guide in the official docs. There are also some really in-depth articles about generics here and here if you’d like much, much more detail :)

Lastpass tip of the day

in tip of the day, Uncategorized

LastPass tries to be helpful by filling in form fields for you, but sometimes it gets it wrong. If you see it fill in the wrong data or if you just mysteriously struggle to sign into services that use 2FA (for me LastPass was helpfully inserting an old 2FA code when I tried to sign into AWS, which meant AWS thought my authenticator app was wildly out of sync and would make me resync it every time I tried to log in), follow these steps and see if it helps.

In case that link ever stops working, you’ve got to find the problem site in your vault, click the little wrench icon to edit that site, then click the little wrench icon again in the edit popup to edit form fields, then delete all the fields with bad values. There may be quite a few of these.

Credit where it’s due, one of my coworkers told me about this. Thanks Logan, I don’t know if I ever would have found that on my own!