An Open Letter to (mobile) Server Devs

On basically every project I’ve ever worked on that involves a server, I seem to notice the same things that happen over and over and could be preventable with proper planning.  When mobile devs discover server bugs, it often blocks our work and halts development (not to mention the costs associated with that, which are NOT trivial).

So I thought I’d just list the things that I wish server developers would think about when they start building a system, and rant a bit about the mentality we’d hope for in any server dev.

 

Design for the failure case, not the ideal case.

Servers fail all the time.  You should consider what will first go wrong before you focus on what will go right.  If you set up your architecture correctly at the beginning, this becomes easier.  Yes, your project has more boilerplate at the beginning, and you can’t just dive into the things that make programming fun, but remember you are a server; you serve others.  The quality of your work is measured by how close to perfect your work is.  Nobody knows when things are working correctly, but they DO know when they’re not.  It’s a tough life as a server dev because you get very little love.  But you chose that, so what should I say?

Consider at the very start how you’re going to deliver errors to the clients.

 

Think of responses like a textual representation of an object.

I come from Object-Oriented Programming.  Think of responses as objects, and you need an application-wide “baseclass”.

{
    "data" : {
        /* YOUR ACTUAL RESPONSE PAYLOAD HERE */
    },
    "errors" : [
        {
            "code" : 401,
            "domain" : "HTTP",
            "description" : "Unauthorized",
            "recovery_suggestion" : "Your access token may have expired.  Try logging in again."
        },
        {
            "code" : 1001,
            "domain" : "Our Server Form Validation",
            "description" : "Email address invalid",
            "recovery_suggestion" : "Make sure your email is formatted correctly."
        }
    ],
    "message" : "Any arbitary message that is relevant to the response itself.  This response isn't supposed to make sense for any specific context.  They're example fields.",
    "response_time_in_ms" : 1234,
    "status_code" : 200
}

 

It’s not 1982

Mobile Clients prefer textual representations in the response.  Your responses can be verbose and at times redundant.  If you have to echo the http response status code in the payload, why not?  All the pertinent information is in the same place.  To an extent, of course.  It just makes your API that much more easy to work with.

 

The Importance of a Documented API

Your server may be down.  When your server is down, your mobile developer is often stuck when he doesn’t need to be.  Most of the time, mobile devs need any data, so long as it can be used to populate the contents of the UI.  The Server API is a contract.  It specifies what the server team will deliver, and what the mobile developer can expect.  It ensures that two mostly separate teams can work happily in parallel.

If you provide a documented API before it’s even implemented, the mobile dev can get his job done.

It just needs to be simple.  Send these parameters with this method to this endpoint, and you can expect a response of:  (most verbose response here that shows all possible fields that might be defined.  Mark in comments beside that value if NULL can be expected.)

Then you highlight the error scenarios.  Possible error codes and why.

 

Interactive API via Postman

Postman is a very valuable tool.  It’s generally how you resolve disputes with the server devs to the effect of “Server’s broken!  No it’s not!”  You can make your requests outside of the app and inspect how the server is working.  It also makes your bug reports more believable to a server dev, where he can’t really say “stupid user error”.  It’s of course up to the server dev to keep environment variables up-to-date and provide some documentation on how to use Postman in the way the server dev expects you to.

 

This is sort of a working draft, but on almost every project, I wish there would be devs that understand how their work makes its way into the end product.  And if you ensure that your role is one of service, and your customers are mobile developers, keeping a service-oriented mentality, like the Maître d’Hotel, where you derive your happiness when your customers are happy, this surely is the way for you to become a rockstar.

Advertisements

Excellent Definition of a Senior Software Engineer

Found this on Quora and it certainly justified my job title! 🙂

What does this mean for a software engineer: “You are not at a senior level”?

QUOTE:

The Perils of Hackers in your Team

I’ve currently joined a project as the only iOS Developer.  I’ve inherited a codebase that’s passed through the hands of 4-5 guys over the course of 3 years.  3 years is already at least a yellow flag in terms of iOS Development.  In my view, the only reason the same project should be allowed to live for 3 years is if you have older devices to support, or a massive userbase and a fat client architecture (making loss of data an issue).  For startups, you should always consider re-writing your Minimum Viable Product, as so many lessons are learned, so many pivots are made, so many corners are cut, to get you to where your codebase is today.  Cruft (look it up) is your biggest problem.

Poorly structured code will hurt your bottom line.  It becomes increasingly expensive to work with, and adding new features will not be easy, and the chances of introducing bugs will be high.  As much as one can talk about Test Driven Development (TDD), I’ve rarely heard of teams (in the startup world at least) that write tests, and if they do, they write them *after* the code has been written.  (This has proven to be the most expensive way to implement tests).  So, fine, the world is not perfect.  In these cases I would hope that if you are a developer reading this, you will at least put comments in your code and also NSAssert statements (the poor man’s sanity check / testing shortcut).

Let me now define what I mean by Hacker in the context of this post.  A Hacker is someone who may look good to any non-developer.  He gets the job done.  The code “works”.  He appears passionate as he types away in a frenzy, trying to make things ‘just right’.   The thing about a Hacker is that he may be self-taught and completely lack the principles of good software design.  He writes spaghetti code (that works).  He may say things like “I don’t need to put comments, the code should speak for itself.”  (If that’s true it is saying “Help me!” or “I’m taking hostages!” or “Your time now belongs to me!”).  But the worst thing about a Hacker on your team is that he will write code that is often a testament to every anti-pattern you have ever known, and to have to work with that person’s code is like being sabotaged before you can even begin.  Because to work with that code, you essentially have to rip out everything he’s done to make the codebase useable again.  So before you can begin to be awesome,  you have to weather the storm of management (who can’t possibly know your struggles) saying “I’m noticing progress is slow”, or “but it’s working now, what do you mean you need to rewrite it…?”

In short, a Hacker in charge of your codebase is basically signing a death warrant for your current codebase, or paying for a huge financial hangover after he’s gone.  A Hacker on your team can have some benefit (thinking outside the box, enthusiasm), but be wise and make sure he’s not in charge of architecture, and make sure you do code reviews.

Why I DO use Interface Builder – A rebuttal

If you are not familiar with this post on why an accomplished Developer does not use Interface Builder, I suggest you read it before reading this post.

I’d like to weigh in on the subject as some of the points shouldn’t – in my view – carry as much weight as maybe he would like them to in that post.  It’s not my intention to start a flame war, but I do have a vested interest in there being programmers who use Interface Builder, and ultimately I think that those who are against it just aren’t yet used to it or have understood what a powerful tool it can be.

Choosing Explicit over Implicit

Choosing to be explicit is my number one reason to do things in code instead … they can see right away where everything is and not have to wonder if this file has a NIB.

If you keep your project folders organized such that a folder has a .h/.m/.xib for your object then this is really a non-issue.

I have spent countless hours searching for the source of a bug only to discover it’s some checkbox in one of the half dozen inspectors in Interface Builder. If it was in code, it’s simple to glance at the view code and see the source of the problem much quicker.

If you like writing a lot of boring code to set properties that you can do in a second (and change later just as easily) then do it.  This is really a matter of style.  Interface Builder is just a part of a toolchain.  I also am a very visual person, so I have a better overview of what’s happening with a NIB.  Most of the time you are dealing with 2 inspectors.  The “I can see it all in code” argument only really applies if you already know what the default properties are supposed to be; so again, you had a learning curve with that.

Tight Coupling

It is much harder to use Interface Builder for reusable views….

I don’t really understand the meaning of this.  I’m starting to suspect that it’s just a matter of experience.  Perhaps part of you just doesn’t want to embrace it?  As an iOS coder, I ‘grew up’ with it, so can’t understand why people don’t want to use it.  (If you want to know how to easily create reusable instances of a UIView from a NIB)

Not to mention, if you use lots of custom views, your NIBs will just be a bunch of invisible boxes. So now you have this tight coupling that is even harder to work with if you were to just lay it out in code.

Did you know about this?  There are a lot of runtime attributes for your custom classes you can set up in IB.  Also, it’s a tool to build view hierarchies.  I don’t know what this argument really is.  I really don’t understand how using IB is any tighter coupling than in code, because it’s a code generation tool.  In fact, getting your programmers to use it could guarantee that they adhere to a Model-View-Controller pattern precisely because they are prevented from writing too much view code beyond keeping their views vapid and vain; IB helps ensure that.

Have you ever sat staring at some code wondering why it’s not working, only to realize you didn’t connect the outlet or action? I hate that.

I don’t know what to say here.  Programmer error?  Rookie mistake?  I’ve been there too at some point.  It’s just a learning curve.  Don’t you hate it when an app crashes and you don’t know how to debug it?  I hate that too.  😉  It should just work like I imagined it.  I will concede that there have been times where I have forgotten to set the delegate, but now I know that this is a source of error once I notice the methods not being called.  I guess one can chalk it up to experience.

Working With Others

Have you ever had a merge conflict in a NIB. It’s the worst…. if it gets automatically merged wrong, you might not notice until runtime. With code, you can read the diff and understand what’s happening.

This is where I definitely concede with you, but this is in my experience not a big deal.  How many developers does it really take to position objects on a screen?  I’ve never been on a project where a developer has said “hey dude, are you done with the NIB file yet?”  (Storyboards not included.)

It’s Part of Xcode

Xcode is not the most stable piece of software in the world. The text editing part works pretty well. Every time I get a crash while editing a NIB, I grumble to myself and wish it was code even more.  The less I have to use Xcode for more than anything except a text editor with completion and a compiler, the happier I am.

Two things; it sounds like you just don’t WANT to like Interface Builder, and two, you’re not one of those VIM guys, are you? 🙂  Anyway, if you don’t like Xcode, you might try AppCode if you’re not using it already.

Location, Location, Location

Layout code is not hard. Trying to work with auto-layout in Interface Builder is maddening … it’s so simple to just override layoutSubviews and do your thing.

True, and true.  Let’s not forget that time is of the essence, so spending time writing lines of code that can otherwise be set with a mouse-click is a task for people working jobs with big budgets.  For the rest of us, anything that will speed up the amount we can get done (well!) is appreciated.

You can simply reuse your code instead of create this tight coupling.

I still don’t understand how you think there’s tight coupling going on.  But anyway, with IB I set the rough position and the auto-resize properties, then do the rest in layoutSubviews as well.  Screw Autolayout.  I don’t know anyone using it, or who has a real use-case for it.

Bottom Line

Interface Builder itself is not bad.

Agreed.

It does encourage bad practices…

I completely disagree, and still haven’t found where you’ve made your argument for this, sorry!

…prevents reusability (making working with others more difficult)…

How?  I just don’t see your argument here.  It gets compiled into code.  A chunk of code with an interface (outlets and actions).

…and slows your workflow.

If this were true, why would it exist?

Personally, I avoid using Interface Builder (including storyboards) as much as possible. All of the projects I’ve worked on since 2009 haven’t had NIBs unless it was out of my control.

Storyboards are a slightly different topic that I’ll just leave alone.  I don’t use them either because I actually want to write controller code, and I think Storyboards take too much of that away, but feel free someone on the interwebs to dispute that.

I think you should save yourself some time, learn a few things, and start moving to code. We are programmers after all.

We are creative people who solve problems, we programmers.  If you were a carpenter, you could saw everything by hand and talk about the purity of your craft, or you could get yourself a fancy woodshop and produce products at a faster speed.  So, your job as a programmer is to build something, and build it well in the quickest amount of time possible.  If you think this is best accomplished without Interface Builder, then that’s your right.  But ultimately all I can say about the “I can’t see what’s happening” and “it slows my workflow” arguments is that you just need to gain some experience with it.  I think it’s a fantastic tool that helps one get an overview of what it’s going to look like at runtime, and saves one having to write a lot of boring code.  You can even drag elements onto your .h/.m files and it will automatically create the outlets for you.  So much LESS typing, allowing you to focus on interesting parts of your application.

If you really are against Interface Builder, then I suggest having a look at DCIntrospect, a very very handy tool that allows you to tweak your view hierarchy (especially frame positioning so you can nudge a view to the left, right, etc until it’s *just right*) at runtime, so at least you don’t have to nudge a frame’s value, compile, run, check, repeat until correct.

Writing Structured Code

As you have perhaps read in my last blog post, I once worked on a project where when I started its very old codebase was more or less one giant mess.  It got me thinking heavily about structured code and how I’d love to just refactor all of that but sadly can’t.  What I can do however is offer up some advice based on my own experiences as to how one might go about doing their job in an organized manner, so that the things you deliver will also be.

First, every project needs an Architect.  Imagine what would happen if your immigrant paid-under-the-table construction workers were tasked with the job of designing the house as they build it.  Not the best plan.  Everything you want to do, software design-wise, deserves a discussion with the project’s architect, as this person is most likely the most experienced person with conceptual design, and through discussing it you can show him how you think and approach problems (good for future work, as he will remember this bright young mind!), and most importantly, you will be keeping him in the loop.

That said, YOU might be the architect, and forget experience, you’ve got a job to get done.  Let’s go then.

I am assuming it’s an iOS project, which is very much going to be for the mostpart a Model-View-Controller paradigm. Here’s generally how to ensure you can adhere to this pattern:

Make a Click-Dummy

You should be able to navigate the interface without requiring any data initially (or at least you can use mock data), so that you are properly ensuring that View objects remain dumb (that is, the Controller tells them how they should appear, and the View tells the controller what has just happened to it, say when the user interacts with it.)  A view should rarely, if ever, retain a pointer to a data model.  If so, this ‘smells bad’ and you should probably be doing something differently.

Ensure View-to-Model Separation

If you couple a view to a model, this view can never be reused in any other project, ever again.  This is why you should keep your views as dumb as possible.  They should inform someone (a controller) about anything that happens to it, if they need to populate themselves with content (like a table view, for example), it should be delegating this job away to someone else (like a controller!  who asks the model!)  A view is vapid and vain; it only cares about itself and how it looks, and if anything happens to it that might disrupt his appearance, he goes and cries to someone else about it and gets them to figure out what to do.

Encapsulation, Encapsulation, Encapsulation!

It can’t be stressed enough how important it is to encapsulate the functionality of your objects as much as possible.  Always write code considering that someone else may use your code later.  The public header is your way of saying “these are all the things you should need to know about, the rest is not required knowledge for you to make this thing do it’s job”  Matt Gemmell put it best in his famous article (which you should read as well!):

APIs are UX for developers… your API is part of the first impression that a developer will have with your code, and will have a huge impact on whether they use it or throw it away.

Of course, with any craft, practice makes perfect, and one doesn’t simply learn this stuff overnight.  The important thing is that you strive for excellence, don’t just be happy with “It works! On to the next feature…”

// Comment.Your.Code.

Time after time I’ve heard the lazy excuse of “well, I shouldn’t need comments because the code speaks for itself”.  Well then, young padawan, your code is saying “help me, I’m retarded”  or at a very minimum “I’m culturally very different than you.”  Which in any case leads to misunderstanding and confusion.  Especially when you haven’t adhered to design patterns, comments are most essential for another programmer to make sense of the mess that’s been made.  It never hurts to give a person some indication of what was going through your head at the time.  That person could also be you, reading your own code months later once your skills have progressed and you find yourself wondering “What idiot would write such a thing…. written by… oh.  Erm, carry on, nothing to see here…”

I hope this might be of some help to you, which of course will then be of some help to whatever person you end up working with in the future.  I had another article I like to call “Stephen’s Manifesto” on writing clean code, but it’s a bit long, lots of images, and a bit outdated.  It’s meant for relative rookies.  I’ll summarize as follows:

  • Avoid “Cowboy Programming”: Don’t “code first, ask questions later”.
  • Write headers first.  It gives you an overview of what you want to accomplish
  • Write method stubs, filled in with comments that explain in plain english what your algorithm is.
  • Organize your implementation files with pragma marks

Happy Coding!

To Nib Or Not To Nib

(UPDATE) There are some good arguments on the Internet about this, whether using NIB files is good, or whether you should just skip it and do it all in code.  Ultimately there are times where either would be appropriate, but personally I am a fan of Interface Builder.  If it were really a cumbrance, why would it exist?  Why would they have taken it further to create Storyboards?  That said, there are times where maybe it’s not the tool for the job.  (I will add my rebuttal to one of these posts in a future post).

The key reason I would say in an article called “Writing Structured Code’ is that Interface Builder (IB) is actually an excellent way of ensuring a coder works to the Model-View-Controller paradigm.  Because when you are coding up your view controller’s view in IB, the NIB file has an owner; in most cases the View Controller.  So, right there you are forcing your views to inform the controller of anything happening to them, and the controller (via IBOutlets) is able to set properties on the views.  Without that, you see coders writing controller code in their views, views are referring to objects, and all sorts of other wacky behaviour that just wouldn’t be easily possible if the person had to set up a view in IB and then set all sorts of other pointers in viewDidLoad.

Having ‘grown up’ with Interface Builder, I think it inherently trained me to adhere to a MVC pattern and I feel I’m better off having done so.  Whether I need IB now, no, not really, but as it’s been mentioned in one of the above 2 posts, one writes less (boring) code.

The Importance of Design Patterns

I suppose this post is aimed at the recent graduate of computer science, or to the programmer who is at a stage of his career where “Look!  It works!” is a validator for whether they know how to program or not.  (And further down in the article towards a CTO who has to give business arguments for why certain things need to be done)

I’m a freelancer and have been for almost 2 years.  What this means is that, for a fee, I am parachuted into unknown territory and am asked to complete task X in amount of time Y.   This is straightforward and enjoyable for prototypes or new tasks, but now that I have some time to reflect on the past, like pulling teeth when you are dropped into a project with a pretty old codebase written by mostly recent graduates and students.

Basically what happens when programmers do not adhere to the paradigms of design patterns (I’m an iOS developer, so I am mostly in this case employing the Model-View-Controller pattern), basically any object ends up with a pointer to any other object, and when you hope to implement a feature by extending the functionality of one specific component, it slowly dawns on you as you are stepping through code to try to understand how it works that basically the app is one big component called AppDelegate and everything else is a member variable.   In programmer parlance, it’s Spaghetti code.  And not just the ‘i just pulled this out of the strainer’ spaghetti, no, this is the ‘i just went back into the kitchen 3 hours later to see if there’s any spaghetti left’ spaghetti, and when you pull on one noodle, the entire blob which has now taken on the form of the pot it was in, is lifted out with it.

This post is about the importance of design patterns.  Yes, we all hear of these things.  But then we are implementing, and don’t know how to get this object talking to that object whilst following the pattern, so we hot-wire a solution where objects A and B, who should otherwise not have any knowledge of each other to do their job, now contain pointers to one another.  This is called coupling.  Now repeat this idea for almost every object in your code, and you not only have the most tightly coupled mess, you now have code that:

* has a very very steep learning curve for new programmers on the project

* is very difficult to extend and add new features because it’s impossible to work on one component in isolation

* is NO fun to work on (affecting quality of life and thus how much they will charge in the future)

* next to impossible to test / debug in any timely manner

What does this all mean?  Cost.  At the end of the day, we are all being paid to produce something, and all of these things result in longer amount of times required to get anything done.  So, you hire a freelancer to implement a simple feature?  First you have to pay him handsomely to learn and understand a codebase that doesn’t follow any pattern, so on his side, no assumptions can be made about how it works.  He has to discover everything new.  You’ve just spent 2-3 weeks on one person who still hasn’t accomplished much.  Now that freelancer understands how it works, but wants to extend a component.  Now the implementation could also end up being messy because it’s trying to consider all of the existing mess and tries to prevent that from getting worse, if possible.  This also takes longer.  The entire time it actually kind of sucks for such a programmer because it’s just painful at every turn.  This programmer will no doubt demand more money next time because the job was not fun.  You just want to implement something simple, but it’s a constant 2 steps forward, one step back, maybe even two steps back.  Actually it’s more like “maybe I can take a step here?  No.  Try somewhere else”  And testing…. ?  Well, that’s just something we won’t get into here.  We just assume that if the code is as it has been, unit tests were never in place to begin with.

Good, structured code, that adheres to principles of software design is ESSENTIAL to any project that is more than a prototype.  What business leaders need to understand is that development takes TIME.  “Yes, it takes one week for that little spinny wheel to do its thing so that later an image is displayed.  But NEXT time we need to do that, our costs are like 1/5 of what they would be because we built something GOOD.”  You get the drift.

Stay tuned for a post about how to approach writing structured code that’s easy to work with.

Practical Considerations for the Technical Interviewer

Was out the other night for a beer with a friend and former colleague and he was telling me of the interview process where he works and it got me thinking about the technical interview stage when trying to hire someone. Having interviewed for positions myself, I sometimes was left questioning the effectiveness of the process itself. I know I haven’t been coding forever, but I’ve been through interviews that left me thinking “they haven’t even begin to assess what I’m capable of”, and like that it was over.

I think a lot of potential candidates may get unfairly filtered out of the hiring process. Let’s look at it; a hiring manager may ask one of their more senior developers to ‘do a technical interview’ of a potential candidate, that developer (who probably prefers to write code) ‘interviews’ them, then reports his/her findings and the search goes on or an offer is made. If you are in charge of hiring someone, does the following sound familiar?

“Here is your task sheet. Your job is to program an App that does the following three things. (e.g. make a request to a webservice, parse the result, then display those results in a table view). You have 3 hours. Here are the constraints (e.g. which frameworks you can or can’t use, which format the webservice is in, etc.)

I already see a few problems with this approach, though not a bad one, but it leaves me thinking and my questions to the interviewer are these: How often do you actually need a programmer to get a task like that done in under 3 hours on a regular basis? In my experience, not often. Do you want fast solutions from a potential hire, or good solutions? If a programmer is not familiar with your approach to solving tasks (i.e. because he’s not familiar with the same frameworks you are when you designed the task), does that make him a bad programmer? When you assign the tasks, are you making it clear to the programmer WHAT it is you are actually testing him/her on before they begin?

As it often occurs in software development, many problems arise simply because people don’t communicate with each other. They dive into coding and report when they’re done. If it works, everyone goes “Hooray!” Would you ever have to take that code 4 months later and extend it? Or better, have another programmer extend it? How long would it take for that person to get up to speed? (because perhaps the first person wasn’t following standard practices / design patterns)

During this conversation over a beer, I challenged this friend of mine to re-evaluate their techniques. Ultimately in a tech interview I want to know a few things from a potential hire that are slightly more abstract but ultimately more telling if that person is someone that would be nice to work with:

  • Before they start coding, ask them HOW would they approach the problem? i.e. in plain English (or whatever language you speak at the office). This tells me more about how the programmer thinks. How they might structure their work. Ultimately when working in a team environment, the way a person structures their code is going to have a big influence over how others will change it later, and speaks for its future maintainability. Getting something to just work is the beginning of being good at what you do. This would tell me they’re not just a stackoverflow.com abuser who just looks for someone else’s posted recipe. If you can understand HOW a problem is approached, it’s easier to forgive them for not knowing the framework, or the approach you perhaps already thought they should take (let’s face it, if you designed the test, chances are you have tunnel vision when it comes to how to solve the problem.)
  • When providing a task, have you condensed the task into clear subtasks that are independent of one another? For example, what if they don’t have experience with Asynchronous data communications, but DO have experience with table views, can they at least create a table view that displays dummy data? This way they can create the table view at the beginning of the test, then teach themself what they don’t know so well with their remaining time. Or put another way, if tasks B, C, D, and E are dependent on the success of task A (which the candidate for whatever reason can’t do), you’ve torpedoed a potential good hire because of a poorly designed test.
  • Have you made it clear which areas of knowledge you are testing? “We just want to be able to see that you know a bit about x-y”, so that even if the candidate doesn’t solve the task in its entirety, he/she can show you at least how fit they are in that area of knowledge.
  • Further, after having discussed their approach, so that you get some confidence that they do know conceptually what to do, why give them a hurried 3 hours? Why don’t you tell them to return the task to you tomorrow (committing their results to a repo along the way)? If they already know conceptually what to do, (they can’t really cheat that), you can then give them some time to solve the problem in a way that suits them best. The chances of them cheating are going to be low, especially when they’ve already told you what they’ll do. In the end, what they return to you should indicate whether they did do that, or if their solution was totally different than their conceptual approach, you can give them a chance to explain themselves afterwards.

Even if they somehow did make it past all the guards, and cheated somehow, this is why every job has an initial probation period. It will come out in the wash that this person can’t do what they said, so I really wouldn’t worry about them solving the task off-site.

Anyway, it’s worth thinking about. I’m sure that many good candidates are passed up for positions just because the format of the evaluation process is flawed. So my hope is that if you consider these above, you, and they, will find the right fit.

(PS: Self-promotion: Also wrote an article, now for me a bit outdated but still useful, on what to ask developers at the interview… before it gets to this stage.)

(UPDATE:  This article is also a very excellent read!)