Examples vs. Tutorials

I’ve been writing software since my first computer in the 1980’s (a commodore 64). Most of that time, I’ve written software for myself, but I did release my first app to the public in the 1990’s. Over all that time, I’ve learned and forgotten quite a bit about computers, computer languages, and how to write code. One thing I’ve never been able to adequately express is how I learn all this stuff. Knowing how you learn something is important because it should inform you how best to tackle something new.

In the realm of showing a learner how to code, there appears to be two major approaches: code examples and tutorials. Examples are short snippets of code that shows you how to do something specific. Tutorials, on the other hand, are similar but go through the process of writing the example within a broader context of a larger application. Typically, you’ll see code examples in places like stack overflow and tutorials in books, book-like websites, and videos. The reality, however, is that code examples work best for understanding languages, since you don’t need a full app to understand how pointers work, and tutorials work best for most complex systems such as frameworks use in applications.

My favorite programming book I’ve used is an old C book. I don’t use it much today, but it got me through writing my first C-based application for designing spherical geodesic grids. From the time picking up that book, a compiler, and getting a working piece of code was about a week or two. Why did that book work for me? It was an example-based book. It didn’t try to lead me through building an app, just explained the concepts and showed examples. For example, if I needed to figure out how to write output to disk, there was a chapter on file IO that would explain it. I stuck with C for a long time because of that book.

I never really “got” other versions of C (at least until Objective-C). There probably is a host of reasons for that, but I tend to blame how I learn. I learn by having a problem I need to solve. Up until 1999-2000, C, bash, and perl could solve all my problems. C plus plus should have been in there somewhere, but it wasn’t because I couldn’t wrap my head around it at the time. In addition to having languages that did the job, the resources I used at the time were more tutorial based.

I quickly discovered that I had a basic axiom:

I don’t want to spend time building someone else’s example apps. I want to write MY apps.

After all, that’s why I’m trying to learn this thing, right? I keep picking up learning resources that are tutorial-based and I fail to get through them and learn what I need because of a basic reality of tutorial apps:

Tutorials will never EVER show you how to write your app.

Tutorials show you how to write the tutorial app. It’s not fair to say that tutorials are not useful – they will help you figure things out, no question. It’s not a bad way to teach you things, particularly if they work for you. If something requires multiple steps are often easier to understand with series of tutorials. But for me, they typically fall down because the tutorials do not match my needs perfectly so they don’t show you critical pieces that fit my problem.

For example, I’m reading a book to help me though understanding a complex API right now (which is why I’m writing this now). It’s tutorial based, which is quite typical in this day and age. However, I could not find anywhere in the book a minimum starting point for using the API. The book started with a tutorial with the tutorial code going a bit too far into a specific problem. This mean that me trying to apply this tutorial caused me a great deal of confusion trying to figure out what I could dump from the tutorial to get to that minimum state. It took downloading tons of example code from Apple to find what I needed. Once I did that, I was ready to move to the next step. Guess what? There were no tutorials in the book that covered that at all…

The above doesn’t mean the book isn’t useful. It still is, but the tutorial code is almost useless to me.

Remember, when I try to learn something new, I have things I am trying to accomplish. I’m not doing it out of pure curiosity. I don’t want to spend a month going through a tutorial book realizing that I didn’t actually learn what I needed to do in the first place. That’s a large amount of time that the project grinds to a halt. Worse, it’s time away from my family that isn’t at least productive. I’m still not entirely sure what it is that I need, but tutorials are not it.

Hit with a code signing fail?

One of the frustrating things about developing for maOS and iOS is code signing. Code signing, to put extremely simply, is a way to make sure that the apps we submit to Apple and the apps you buy from the App Store are legitimate. But sometimes this process can go wrong, or at least seem to go wrong.

I’ve been working on a macOS app for years. Now, I’ve been wanting to get UI Testing to work via Xcode Server. But there was a problem. Code Signing. So, I created a Xcode Bot to build my app and run tests. However, it failed with errors like these:

Error: No profiles for ‘my app’ were found:  Xcode couldn't find any Mac App Development provisioning profiles matching ‘my app’.


Error: You are not allowed to perform this operation.  Please check with one of your Team Admins, or, if you need further assistance, please contact Apple Developer Program Support. 

There are not a lot of hits in good on these errors in google, so I dutifully tried and tried to resolve code signing: making sure everything was installed properly on the server and I had all the proper certs and profiles created at Apple. Nothing was working.

Much of the advice I did find on google wasn’t particularly helpful. Solutions, if there was one, ranged from recreating all certs and profiles to reinstalling the OS. None of those sounded like good solutions.

One suggestion that I did follow up on was to look at the more detailed logs for the bot’s attempts. I found some interesting things, such as…

DVTDeveloperAccountManager: Failed to load credentials for …


But I, being slow sometimes (only 46 build attempts via my bot), decided a different approach. How could I get a better handle of what’s wrong? Build the app! I’m sure you’re thinking that I hopefully built the app before I created the bot. Of course I did. But I didn’t build the app on the server itself!

So, I got on the server, checked out the project, built…. build error! I had a build phase that I thought I removed from the project, but it was still there. At this point, I’m not sure how this script wasn’t failing on my other machines, so figuring that out is not on my Kanban board.

The lesson? Code signing errors may be your fault and nothing to do with code signing at all.

Returning to An Old Project: Part 2

Returning to An Old Project: Part 2
The logical place to start reviewing and fixing up my Devonian app is in the area of managing the database.  I have one class that works on both iOS and MacOS that handles this job.   Reviewing the class… it’s quite a bit of code: well over 800 lines.  Individual classes with high line counts are not that unusual, especially for things like view controllers (if you stick to the classic Model-View-Controller, MVC, design pattern).  However, I’m not happy about that.  I want it to be smaller, leaner, easier to manage, and finally make it easier to transition to another file format or web service for the database.
There were a few tests.  Most failed.  After perusing the tests I discovered a major problem: I didn’t understand what the class actually did.  Tests serve as a way not only make sure your code works, but to do things like ensure contracts with the rest of your code are respected, and, quite importantly, they document the code.  The tests failed in this regard.
Part of the problem with the tests is that I didn’t understand how to write them effectively.  I probably still don’t always write them effectively, but I’m better 2 years on.  Furthermore, since I really didn’t understand how to mock code in Swift, the class was almost impossible to test anyway – mocks would be required to do unit tests.  So, what kind of tests did I have in the end?  Integration tests.  These tests had to use real data and real database in order to work and the database was likely to change over time.
So, chuck the tests and start over.
Now, what to test.  Generally, I want to exercise  all the code in my class.  But, since I wrote this for myself, I made no distinction between public and private methods and variables.  Anything that should be private should not be tested directly, since those things should impact other calls.  In addition, it was worth eliminating any dead code (if I really needed it back, I use version control like any sane developer).   I found a bit more of this stuff as testing went on, so it’s okay to eliminate stuff later.
Finally, it was time to slog through backfilling the tests.  Keep in mind, at this stage I’m only testing to suss out the contract this class is using to interface with the rest of the app, and not make meaningful rewrites or refactors.  So, the goal is to be minimally invasive.   The main exceptions (other than dead  code removal and public/private) include making the code easier to understand and easier to test.
As far as understanding, I had a number of values that were essentially magic numbers: i.e. numbers that seemingly come from nowhere.  Fortunately, I knew what the numbers meant, so I could assign them as variables or enums.  I would have trouble understanding what 832 might be, but if I passed the value around as “George”, it can make more sense.  If the code makes more sense, it will be easier to test.
Going through the testing process quickly brought up the need for mock classes.  In particular, mocks for FileManager and NotificationCenter.  Both of these standard Apple classes are commonly using on Apple platforms.  Most apps will use these somehow.  However, they are both essentially singletons: they both are single objects in your app that you can call from almost anywhere.  Very  convenient, but very hard to test when you do so.
First, the FileManager handles files: creates, deletes, verifies it’s there, etc.  Makes sense to use.   However, all sorts of things can happen while doing these operations.  For example, your code might do X if a file exists or do Y if it doesn’t.  Imagine for a moment your app will ..usually.. successfully create a file.  It almost never fails.  Maybe once in a blue moon something happens but it’s fairly consistent.  How do you test the failure state?  Your file is always created, right?  What if you could get the FileManager to say, “sorry, there’s no file there?”  You need a mock for that.
I’m going something bad and refer to anything that isn’t a real object as a mock: so I’m going to conflate mocks, fakes, and stubs.  Mock are objects that stand in for real objects and track what’s been called on them.  You can these assert that what you expect was called, was indeed called.  However, these objects are essentially non-functioning.   Fakes on the other hand are functioning objects that typically function similarly to the real object but how it works is simplified.  Stubs are similar to mocks but can respond with data.   So if you call a method on a real object that returns a value, a stub can do the same thing with canned responses.  Of the three, mocks and stubs are very similar and, in my usage, are best mixed.  You want to see what’s called, and if I response is required, then  do so.
So, we need a mock(with stubs) FileManager.  But how?  Swift makes it tricky given that it’s type safe.  Indeed, how to we deal  with those singleton calls?  How are those replaced with mocks?  It’s easier than it sounds.
Step 1.  Create a protocol in you app for the FileManager, say “MyFileManagerProtocol”.  In Swift, it will look a bit like this:
protocol MyFileManagerProtocol {
Then all you need is to make FileManager conform to that protocol with an extension:
@objc extension FileManager: PTFileManager {
Now, Apple’s FileManager conforms to MyFileManagerProtocol.  We’re not quite done yet.  Take a look at the FileManager calls you use.  Simply add those function signatures to your own protocol:
protocol MyFileManagerProtocol {
func urls(for directory: FileManager.SearchPathDirectory, in domainMask: FileManager.SearchPathDomainMask) -> [URL]
func fileExists(atPath path: String) -> Bool
func createDirectory(at url: URL, withIntermediateDirectories createIntermediates: Bool, attributes: [FileAttributeKey : Any]?) throws
func copyItem(at srcURL: URL, to dstURL: URL) throws
Since FIleManager already has these methods, it already conforms to your protocol.
Now, let’s change how we call the file manager.   Instead of calling the singleton version we want to inject our protocol version.  So, on init of the class, let’s inject it:
init(fileManager: MyFileManager = FileManager.default {
self.fileManager = fileManager
In the class, replace every occurrence of FileManager.default with fileManager (except for the init).  Notice in this using the standard FileManager by default.  This may not be desirable in some cases, but this should be fine.
Now, make a mock (and it will also be a stub).  Be sure to only include the mock in the unit test target, not the app.  Don’t forget to do a “@testable import” as well.
class MockFileManager: MyFileManager {
Of course, now you have to make it conform to the protocol.  In this case, we want to make some of these calls to be both mocks and stubs.  I’ll show one:
var fileExistsCalled = false
var returnFileExistsPath: Bool = false
var capturedPath: String = “”
func fileExists(atPath path: String) -> Bool {
fileExistsCalled = true
capturedPath = capturedPath
return returnFileExistsPath
What does the above do?  It allows us to verify that the method was called (if called, it sets fileExistsCalled to true).   It allows us to capture what path was used in the call (capturedPath).  Finally, it allows us to return whether or not the file exists.
So a test might look something like (pseudo code):
func test_doMyThing_givenFileDoesNotExist_ThenDoMyOtherThing() {_
// Given
let mockFileManager = MockFileManager() //create the mock manager
mockFileManager.returnFIleExistsPath = false //make sure we know it won’t find the file
let testObject = TestObject(fileManager: mockFileManager)
let expectedResultIfDoesntFileExist = failedResult
let expectedResultIfFileExists = successResult
let expectedFilePath = “/path/to/file”
// When
let result = testObject.doMyThing()
// Then
XCTAssertTrue(mockFileManager.fileExistsCalled) //make sure we called it
XCTAssertEqual(mockFileManager.capturedPath, expectedFile) //make sure we called the correct path
XCTAssertEqual(result, expectedResultIfDoesntFileExist)
The notification center is similar, except that you are capturing calls to the notification center.
More next time

Returning to An Old Project: Brining the Power of Unit Testing and Refactoring (and rewriting) To Resurrect the Dead

I have a project that stalled.

The project is an iOS app. A fairly simple, really. The app is, more or less, a graphical interface for database (I suppose most apps are some form of this). The app has been around in one form or another for many years, but doesn’t need to be update that often. The truth of the matter the database that i’m using hasn’t been updated in a while because I’ve never gotten around to write an editor. So, the last major release was around 2015.

In late 2015 or so, I had the brilliant idea of porting the app to MacOS. After all, I eventually need an editor. A twist in that idea was the app would be 100% written in Swift, if possible. The iOS version was written in Objective-C.

It turned out the transition went well. I released the MacOS version in 2016.

It went wrong when I decided it was time to unify the code base of the apps as much as possible. In other words, the iOS app had to move to Swift too. Why? Well, I got a job and this particular app was a relatively low priority.

Fast forward to 2018. I decided that it was time to expand the things I do at work. Thus, I decided to become a Test-Driven Development (TDD) instructor (in training at least). So naturally, I decided to find a relatively small project that I can apply my (limited) TDD chops.

It is time to revisit my Devonian Database iOS and MacOS apps. These apps are available for free on the different App Stores.

The iOS app been in the app store for many years, and I managed to get the last version out in 2015 or 2016. I fixed it up and released as part of a job hunt: have a good working app in the store to prove I can do the work. As part of that effort, though, I decided to release the Mac version of the same app. Cleaver me decided to make this new version entirely swift: no Objective-C code at all. That app was successfully released too.

What got me was the next decision: make my iOS app Swift only as well. The decision made sense, and still does. Minimize the code base and both apps are easier to maintain. While Objective-C is still a powerful language, Swift is an easier language to use (with the exceptions of occasional major changes to the languages and the difficulties in testing and Objective-C interoperability). But it takes time and energy. I got the job and the app fell by the wayside.

I started looking at the app again and it’s a mess. For most developers, looking at your old code is a cringe-worthy experience. Now that I work on a team, I find my old code has one fatal flaw: it was written for me… The problem with “written for me” that that the me of today has no idea what the me of 2015 was thinking. I wrote things quickly. I wrote things using simple and convenient design patterns instead of something that would be more appropriate. I did write a few unit tests (or in many cases integration tests pretending to be unit tests), but they were few and far between and written at a time where I really didn’t understand how to write good Swift tests. Not to mention many didn’t work at all.

So, my first few hours will be spent looking at the core of the app – the database management code. I’ll blog the results of this work.

iOS Size Classes, Navigation Bar Titles, UI Testing

I’m working on a particularly difficult part of my user interface and I ran into an interesting and confusing problem.  UI Testing is a new feature in Xcode.  Despite its newness, it has already helped save time in development.  However, I started using it with an app I’ve been trying to update for a while when I ran into this problem.

UI Testing depends on accessibility: a mode for those with disabilities.  As it turns out, it is highly dependent on titles or names you give different user interface items.  So, the names you give things are key to getting UI Testing in Xcode right.

In some cases, however, this can cause a problem.

I have a navigation bar that has enough elements that a title looks too stuffed into the bar when the device has a compact horizontal size class.  When regular, it looks fine.  So, I simply added a title when the display was regular, and did not add the title when compact.  This causes UI Testing problems.

The navigation item must always have the same name in the testing environment or you have to use a NSPredicate to search for the title or the class name (if you don’t set the title, then the UI Test record will record the class name).  This seems quite fragile and quite annoying since I don’t want duplicate tests for different devices unless there is a major difference in layout.

The apparent solution at this stage is to go ahead and name the navigation item to the title I want.  However, to prevent the title from appearing, I simply sent an empty UILabel to the “titleView” property of the navigation item.  This appears to work at this stage…



Why you need the hardware to develop for mobile…

Probably the second biggest roadblock for developing mobile apps is the cost of hardware (the first, of course, is the time).  Devices are expensive and it’s tough to keep up.  My current testing livery of devices is actually quite limited.  Indeed, some of my devices are not longer supported by their manufacturers or myself.

Despite the difficulty of maintaining an adequate device livery, you need the devices for testing. In a previous post, I mentioned that I’m migrating my app from OpenGL ES 1.1 to OpenGL ES 2.0.  All of my currently-supported devices support 2.0 (and in some cases 3.0).   That sounds like things should be just fine.   Well, they don’t have the exact same graphics card or OS – which will lead to horrible surprises.

I have one older iPod Touch which on iOS 6.  Having this particular device saved my bacon for the last release of one of my apps.  It turns out that the software ran just find on all of my devices except that iPod Touch.  Talk about panic!  It wasn’t an easy fix either; it required a rewrite of a major portion of my code to work correctly.

Well, in my testing for parts of my OpenGL ES transition code, I decided to try the old iPod again… and wouldn’t you know, code I thought was working fine rendered completely wrong!  It turns out there was a bug in the OpenGL code that apparently  didn’t manifest in the newer devices or on the simulator.

Realistically, you can get away with a smaller livery of devices under some conditions.  For example, if you don’t use any low-level code and stick with the high-level user interface APIs you’re more  likely to still have a stable app on many devices.  Getting into the lower-level stuff will likely cause more problems particularly in the short run as you develop, and in the long run when devices you didn’t test start reporting issues.

Just to add to the above, I don’t count the xCode simulator as a device.  I have code that works perfectly in the simulator and does not run correctly AT ALL on any device.  After all, the simulator is actually MacOS X OS and hardware, not mobile.  As a consequence, successful rendering in the simulator will not always translate to a device.  The first time you encounter this issue it is a rude awakening.  However, it shouldn’t be a surprise since all of Apple’s OpenGL  ES debugging tools only work on devices, not the simulator.

This gets back around to why my apps have yet to be ported to Android.  I only have a couple devices that use that platform for testing out of the many MANY devices out there… it’s a tad scary…



Working on migrating AE to OpenGL ES 2.0

Now that I have a break from other duties, I’ve been working on improving AE for iOS.  One of my early design decisions I made in AE is to go with OpenGL ES 1.1.  At the time, my only iOS device did not support OpenGL 2.0, so for practicality sake, 1.1 made sense.  Furthermore, I needed some basic functionality that was stripped from OpenGL ES 2.0.  ES 2.0 was clearly unattractive… at the time…

Today, the story is different.  All of my “supported” iOS devices support OpenGL ES 2.0 and in some cases 3.0.  Yes, they still support 1.1, and it’s arguable that the practical decision is to remain on 1.1.  However, it’s only practical if I don’t add new features that call on the graphics card.  I’m also considering the path to porting the application to other platforms, such as Android and Desktops.  From this perspective, ES 1.1 looks increasingly problematic.

The kicker that’s forcing the transition is the time scale control on the bottom of the screen.  It turns out that feature is quite a difficult to display.  The time scale tends to be a memory hog and requires a great deal of code to provide full functionality.  I’ve long known that the control should be moved to OpenGL rather than using higher-level functions.  Originally, the time scale was created using simple bezier-path draw calls. In the last version, I moved the system to Apple’s layers.  That transition was meant to make the code easier to maintain.  However, it turned out, on older devices in particular, the app became crash prone because the layers took up an unexpected amount of memory.  I managed to work through this problem for a stable release, but I wasn’t happy with the situation.

Enter OpenGL ES 2.0.  Now, the time scale is not done by any means, so these comments are initial impressions.  Now that I’ve worked with it, I do regret not going with ES 2.0 from the beginning (it still wouldn’t have been possible to release the original app with ES 2.0 support since I had no hardware at the time).  ES 2.0 is clearly superior to ES 1.1.  Surprisingly, I found that while in some areas ES 2.0 requires more code, the transition from layers to ES 2.0 appears, at least in some areas, is thinning out my code.  That’s exciting!  Since the code for the layers was extremely complex, it’s hard to improve or add features.  With the code simplifying, I feel I can consider, at least, adding functionality I wouldn’t have been too keen on adding before.

Now, back to work on the code.  We’ll see how this turns out…

Unexpected problem with the App Store – App icons

Migrating to XCode 5 has largely been very helpful.  I’ve used many of the new features and I’m quite happy how things are working out.

One thing caught me by surprise.

Submitting apps to the store is usually a painful experience.  One the goals of XCode 5 is to lessen the pain, at least a bit.  So, imaging my surprise when submitting my latests updates was painful!  Neither of my apps would pass the verification step in the approval process.  Basically, the problem was that the app icons couldn’t be found.


I’m using XCode’s latest feature called image assets.  They are great for managing all of the icon and launch images required for the app.  It was supposed to make all this painless.  For example, to manage your app icon, you made an app icon image set, load in all of the images, and the rest is magic.

But, it wasn’t quite magic.

It turns out, that when you build an app using image assets, XCode will modify the app’s info.plist file to list all of the app icons to be included in your app.  However, if you’re like me and your project is older, you might have references to icons already in your info.plist files.  I suspect in most cases, this wont be a problem.  In my case, however, when I looked at the info.plist file for a compiled version of the app, all of those old icon references were still there.  Thus, the verification process could not find those images and the app gets rejected.

Fortunately, it didn’t take TOO long to figure this out.  So, I deleted all existing app icon references out of my plist file and after that, things verified normally.

Now that I knew the problem, I fixed it in my other app and the process really because much less painful.

Redesigning my OpenGL engine for Ancient Earth

In case you were wondering about any updates to Ancient Earth, I’m working on them.  Right now, I’m spending a good deal of time trying to modernize my OpenGL engine to take advantage of Apple’s updates in iOS 5 (yes, that means, I’m dropping support for iOS4).  It turns out that Ancient Earth really pushes the limits for iOS, and for us to be able to add more data and map types, we need not only a more efficient rendering system, but a more flexible rendering system.

Ancient Earth Released for iOS!

Last month, I released by iOS app “Ancient Earth: Breakup of Pangea”. Working with C.R. Scotese, we've brought his maps to the iOS platform! In this app, you can explore his continental plate reconstructions for the last 200 million years of Earth history.

You can see our home page for Ancient Earth here: Ancient Earth. Alternatively, you can simply visit our page on iTunes:
Ancient Earth: Breakup of Pangea - Thomas L. Moore