An increasing number of my work requests as iOS developer come from projects that are already in progress, but whose developer left for some reason, or projects that were left on a hiatus some time ago, and then started again with a fresh new team. In these situations, you are faced with a project built by one (or sometimes more) developer, in wildly different maintainability statuses.

Now, it’s obvious to me that it’s hard to be an “agnostic developer”, meaning, we all have our different ways of doing things, our favorite technologies and our special touches that make our style so unique, but we must be conscious as developers that our code will probably be maintained in the future by another developer, or someone else might join the team to help you with the iOS developement if the App becomes a hit. I am not talking just about the coding style here, but about everything in the project, from the structure to the Pods/libraries/frameworks included, to the technologies used. We should always assume that someone else is eventually going to maintain the code we wrote some time ago. Even for personal projects, you can find yourself looking at that project you did one year ago and wondering “What the heck does this framework do and why did I include it?”. We must consciously develop projects that are clutter-less and maintainable.

We should always assume that someone else is eventually going to maintain the code we wrote some time ago.

My last job offer was the perfect example of a project I wouldn’t like to be involved in. With just a glimpse, I could see that it was using 25-30, maybe more CocoaPods. It didn’t use storyboards, and was applying some custom technologies that would have made maintaining that code a nightmare.

Thus, these are some tips and suggestions that will help you keep a clutter-less, maintainable project, and will make the future developer or team managing that code happier:

Structure your project in a clear, intuitive hierarchy

mini1468154204Yes, when you are developing a project, you know where your files are, our brains get used to spatially locate our files and we intuitively find them. But when you revisit the project months later, or someone else navigates through it for the first time, it can be a nightmare to locate the view controllers, or find that class that is being referenced everywhere but you never seem to spot on first sight.

So please, use an ordered structure to keep the files inside your project tidy and easily accessible. It doesn’t need to be that complex. Here are some folder structure that I usually employ in a more or less strict way in my projects:

  • “App”: a folder to keep you AppDelegate and all global files, maybe definitions and constants, global methods or things such as the Info.plist. I use to store my localizable.strings and other internationalization files here too.
  • “Assets”: useful to have all your asset collections in a single place. I use to have different assets files for different things, like: backgrounds, icons, App icon and launcher screens, etc.
  • “Model”: This folder is a must for keeping all the files related to your model, database, concepts and objects, etcetera in an easily accessible place.
  • “View Controllers”: in this folder is where I usually put all my UIViewController classes, usually subdivided in different folders, depending on the application, like “Login-Registration”, “User profile”, etc…
  • “Storyboards” and “Views”: these folders are useful for keeping your different storyboards and your custom views (like UITableViewCells or UICollectionViewCells).
  • “Resources”: a folder I normally use to store all other resources that don’t fit in any other category, like css/html files, plist files, etc.

Of course this is just one of multiple possible structures, but it’s always nice to have all your files ordered and easy to find.

Don’t abuse frameworks

mini1468141333I’ve written about the abuse of frameworks before, specially when applied to frontend development, but also on iOS development. I think it’s kind of a trend lately: when faced with a problem, developers would not waste a minute of their times thinking about the problem and instead just drop a framework in the project. It always amazes me how many developers opt to include AlamoFire or AFNetworking (in Objective-C) just to make a network request that would easily be done by a simple NSURLSession call, and of course I love those two frameworks (they are just awesome projects and all my recognition goes to the developer for such a great work), but 90% of the time you don’t need them for just some simple network calls. Besides, not all frameworks and Pods out there are so well written, maintained and documented as AlamoFire, for instance.

In my last job offer, a glance at the code allowed me to see a list of easily more than 25-30 CocoaPods. This for me is always a warning sign, indicating that I would probably need to learn about 15-20 new frameworks, track where are they used in the code and why are they being used. This is time consuming, and sometimes you find yourself trying to clean the code of a framework that’s doing something that’s already being done by pure swift/Cocoa libraries/methods.

So please, before adding yet another framework to your project, think if it’s really necessary, or you can solve that functionality with just some lines of code or a class of your own. Sometimes the answer will be: “Yeah, I don’t really need a whole framework for just that”, and you will learn a lot, and have a limited, documented and more easily maintainable piece of code in your project.

As an additional benefit, you will be reducing the technical debt of the whole project, and being less dependent of third parties for updating and adapting future versions of your project.

Stick to common technologies unless you have a good reason not to

In my last job offer, one of the main things that put me off the project was realizing that, instead of using storyboards or XIB/NIB files, they were using AsyncDisplayKit to define the user interfaces and all the elements of views and controllers. AsyncDisplayKit is a technology originally developed by Facebook for its Paper app, and even though it may be cool, nerdy, and mega-hipster to use, I can tell you it’s not something easy to use (specially if you have never used it before). It requires you to define all interfaces, layout rules and stuff by a set of custom classes, without the help of IB. I’m sure a hardcore AsyncDisplayKit user/supporter will tell you that it makes the code development process faster, less error-prone, blablabla, but the truth is: it makes your project harder to understand and maintain.

The lesson here is simple: unless you have a really good reason (and no, personal preferences or a 1% increase in performance is not a really good reason), please stick to common technologies. Use storyboards for building interfaces (now that you can have storyboards split in multiple files, I think we can get over the old, boring storyboards vs. nib/xib argument, right?), SQLite or CoreData (if that’s your thing) for internal storage of data, Assets for keeping graphical resources in your project, localizable files for internationalization, etc… If you are using a completely different technology, specially if it not well known, make sure to document why this new technology is used, where exactly is used, and a basic starting guide for a future developer joining the team.

Don’t abuse swift

Swift is one of the most versatile and flexible languages that I’ve ever used, and gives you a lot of freedom for defining custom functions and operators to use in your code. Whenever possible, avoid defining custom operators or functions with unclear meaning.

As an example, in 2014, while let concatenation and guard let clauses had yet to arrive to swift, it was really ugly to parse JSON in swift. You would end up building nested structures of “if let” to handle all possible cases in your JSON structures. During that time, many articles out there ([1][2]) suggested using custom operators to help avoiding this nested structures. While they made use of clever techniques to avoid this code mess, they ended up generating code like this:

static func decode(json: JSON) -> User? {
   return JSONObject(json) >>> { d in
      User.create <^>
      d["id"] >>> JSONInt <*>
      d["name"] >>> JSONString <*>
      d["email"] >>> JSONString
   }
}

Even though I appreciated the genius behind these constructions, I immediately disliked the idea of joining this trend, because it would make my code unreadable and hard to understand by someone who’s not used to my custom operators and definitions. This is just an example of how swift lends itself to these kind of manipulations, so please, resist the urge of adopting a custom syntax in your code. Stick to the basics.

Use a standard coding style and comment whenever possible

These are the usual common recommendations for everybody writing code in any platform, language and operating system. Try to stick to a standardized coding style, and comment your code often, with useful comments, avoiding obvious comments like:

// this function does something.
func doSomething() {
   // i starts at 0
   var i = 0
   // increment i by 1
   i = i + 1 
}

There are many resources ([1][2][3] just to name a few) out there for best practices when coding, so I’m not going to add anything else about that matter. Even if you have your own style, and you add some custom bits here and there (we all do), make sure to use a generally standardized, clear style that’s easy to read.

Conclusion

Writing a clutter-less, maintainable project is not that hard, but requires some conscious effort by the developer. We sometimes tend to ignore the fact that this same code will eventually be maintained and modified by someone completely different (or by ourselves months or years later), and also that we will eventually end up maintaining and modifying code written originally by another developer, so it’s essential to write code that’s clean, clutter-less and maintainable from the very beginning of the project.

These are just some tips for keeping your projects under control, but of course there are a lot of other techniques that can also be helpful. Do you have a suggestion? let us know in the comments below!