No, I didn’t die

Looking at this blog, it’s been over a year since I wrote anything. I’ll just list my excuses:

  • I was overworked on some agency projects and there simply wasn’t enough time to write posts
  • It’s generally a grey area to write about problems solved for clients who make me sign an NDA
  • I could have made the solution to the problem look generic, thereby obfuscating my client’s identity and thus my attachment to the project, but didn’t.
  • And now THE main reason….

I spent 8 months of 2018 taking a sabbatical. I like to call it a sabbatical because this is how you don’t lose respect from people when compared to saying “I’m unemployed and am enjoying watching my beard grow”. But really it was more like a “I’m fed up with insane projects that are under-staffed, with poor management and deadlines that don’t change, so ultimately the bottom-feeding developer who is doing the job of a small team on his own is starting to wonder if it’s time to pack it in and open a bakery, or do some other kind of artisanal work that involves repetitive, meditative movements and a certain degree of craftsmanship. <blows sawdust off his handmade hope chest>”

Sabbatical has a nicer ring to it and doesn’t require a backstory.  “Ah, he must be a well-to-do kind of man.”

This sabbatical was not about going to some coding retreat so to level up my skills as a developer. It was more like a sanity check. The reason I like coding and software engineering is that I find it to be a highly creative medium. For me, being creative is what gives life some meaning and makes it fun. The process of having an idea, developing it in your mind, putting it down on paper, refining and iterating on that, solving the unknowns, then finally doing the implementation / building. Then it’s done, you pat yourself on the back, revel in your accomplishments, then say “next!!” I love it. So the sanity check was a) to get a little distance from a profession that was starting to become not fun for me anymore, and b) do something completely different but also creative.

So I did that. In 2018, I decided I wanted to build a camper out of some kind of vehicle, then drive around North America until I experienced some sort of epiphany. I gave myself a year. I used 8 months. I built a camper. I had an adventure. I drove 24,000km in 4.5 months and saw so many beautiful places and met tons of very lovely people. I had some profound realizations about my life that were restorative and empowering for me going forward.

In short it was the most useful year I’ve had in over a decade. If you have the opportunity to take a long period of time off and leave your normal surroundings behind, I highly recommend it.  You’ll return knowing what changes you need to make in life.

True, I have fallen a bit behind with the latest and greatest in iOS / Swift dev, but since I’ve been back working (since November 2018), I’ve been fortunate to work with great developers and I’ve actually leveled up in this short time. I can say I’ve become way more of a test-driven developer, and I’ve also got a few new tricks up my sleeve that you generally get to learn when you work with other developers that work on your platform; not something I’m all that used to as I tend to be either the only iOS dev on a project, or they quickly say “oh but you know the most”.

At any rate, I’m back and I’m still happy to be a developer, and now that my approaches have changed somewhat, I have new areas to grow. So I’m not stagnating like I felt I was, and I’ve been fortunate to get a few freelance contracts that have not turned about to be a complete and total clusterf*ck, which has often been the case in Berlin, Germany. I oftentimes have the feeling that when it comes to Software Development practices, Berlin is the wild west; there are no rules, OR Berlin is teenage love; just fumble around in the dark for a while and hope something good happens.

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.

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.