Thank you, perl* for that most useful phrase, There’s Always Another Way. It was another rough week. The solution I had intended was just not working. We did some tweaks and it was still crashing. Still more tweaks still more crashes. Late last night, before it got too early in the morning, I gave up and went to sleep. Sure enough, I woke up early with an idea.

Just because you have picked out a solution doesn’t mean you have to stick with it. Yes, your great ego=-inflated developer brain doesn’t want to give up, but when you’re facing a real deadline, something has to give. You can either pitch out the original idea and try something different, or you run away screaming. Happily I chose door one.

Yes. sometimes that means scrapping a bunch of code and rewriting vast swathes of architecture. Honestly, by the time you get to that point, chances are good that a rewrite is going to be immensely faster than trying to force the original direction. When you’re stressed out and so neck deep in the problem that you start dreaming about it, you can consider letting your back brain chew on the idea for a little bit to see what wild ideas it comes up with.

No, you should change course every time you hit something that’s a little harder than you expect. If you’re afraid to learn a few things on the fly, and admit that you need to learn them, them you should probably consider a different career. In this case, I found a much simpler solution that will meet our needs in the scope of this project. But I also have another topic (complexities around Grand Dispatch) to dig into later.

*Perl, the language. It’s a clever and fiendish little language best used for projects that can be thrown away rather than maintained. Have you heard Scalzi’s bit about the failure mode of clever is asshole? Yeah, it applies in coding too. But it’s a fun little language and worth at least taking a look at if you’ve never played with it.

Here’s one that sounds like it ought to be simple, but when it isn’t it can bite you: Plan for how you’re going to test your app.

Does your app depend on sending data to or receiving data from other systems? Does your app validate the data it receives and handle failures gracefully? User entered data should always but always be treated with the utmost suspicion. But even generated data can bite you if the other end makes an apparently minor change to a database schema.

Or what if your app is displaying (for example) catalog data provided by a third party that has to be filtered based on user roles. And, for example, let’s say that this data is being updated on a very regular basis. How do you very that users are seeing all of the items they are supposed to see but none of the items that they aren’t supposed to see?

The standard method is to set up a set environment and populate it with real data so that you can test there. Which works until you have enough moving pieces and enough players and third parties who don’t want to play. You have to get creative and you have to code with more even paranoia than usual. The trick is to not leave it to the end. Prioritize it, think about it, document it, and get everyone involved to sign off on it. And have a fall back plan, because no matter how much testing you do, you can still get surprised.

More lessons from the trenches, and of the worst sort. There are some mistakes that seem to get made over and over again. You stub your metaphorical toe, recognize the rock, swear you’ll take care of it, and then wham! There’s that stupid rock again.

Define your terms. Explicitly. In writing.

In this case we had data being passed through three layers of services with three different companies after importing data from yet another service at yet another company. Everyone involved uses a different subset of the data and has their own data models. And their own field names. What we failed to do was document a data dictionary showing how those fields mapped between models. Normally this sort of problem would have surfaced early in testing, but there was other factors that hid the damnable rock and we’re lucky we didn’t break a toe this time.

Document your terms. Document your assumptions. Find a way to get everyone to actually read the documentation and update it when things change. And make sure you are testing those definitions and assumptions, somehow. And the more parties you have involved in a project, the more critical this becomes.

Now, how the heck do I avoid being involved in this sort of toe-stubbing exercise again? I don’t have the answer to that one.

Things you don’t want to have happen the week you intend to deploy:

1. You finally get access to the production data. Extra points for this being on the production system itself because, for some reason, the production data couldn’t be copied onto the development system.
2. Double extra points for not getting connected to the production system until the day before scheduled deployment.
3. You finally get more than one test user.
4. You’re asked to make a major change to the way you sync the primary data set. After an extensive effort to make this happen quickly, you are asked to discard that work and try a different approach.
5. While discussing the details of a final round of acceptance testing following all the above, you’re informed of yet another change, this time to the primary transaction data.

Supposedly all these details had been settled on months ago and fully documented. But when you are dealing with a third party vendor who is also dealing with another third party vendor, things can go cock-eyed pretty quickly. When you sense this sort of situation developing (or step into one up to your elbows), stay calm and document everything. It’s especially important after phone conferences to write up and distribute a recap of the discussion. And then be very careful not to get sucked into a blame game. For now, fix the problem. Once the problem is fixed, review all the documentation to see if there’s a way to avoid having to deal with the same problem in the future.

No, I don’t mean whether you spend too much time on social media during times you’re supposedly coding. What I want to talk about is how we code when we’re working on a solo project and/or not within a formal project context. When you’re working on a small toy project or just working solo, it’s easy to skip over all the folderol of a formal project. In fact, that can be one of the advantages of those types of projects, right? Less overhead and bureaucracy! More nimble! I think that it’s in just this situation that you should be most focussed on using – and evaluating – your workflow.

If all you’re doing is messing about with code for the sake of trying stuff out, you’re probably fine. (But if messing about with code is how you do your design, maybe give some thought to that process as well!) Disposable code is fine, so long as you are truly committed to throwing it away. As soon as you have code you want to save, it’s time to think about process and workflow.

Source code control is the easy part. You are using source code control of some sort, yes? But even here, it’s good to practice using the tool as if you were in a larger team, even if it’s just you. Don’t commit everything to the master branch. Do include meaningful commit messages. Use pull requests. And don’t forget to add project level documentation to the repository, at the very least a basic readme.

Set up testing code and strongly consider setting up a continuous integration process. This is the step I most often fail at. In fact, my unpaid side gig this week is to figure out how to use travis-ci to see if I like or not. I’ll also be adding test code to my current toy project. If you play with new tools on a smaller scale project and when you’re not under an external deadline, you have the luxury of poking around in the corners of your tools and trying different options. That means I have time to try more than one CI tool on the same project to see if I have a strong preference in any direction.

Even if you never intend to let anyone else run the code, it’s still a good idea to think about issue/enhancement tracking. Here I’m talking about internal, developer facing tracking, not the public facing type. (Although it’s possible to solve both at once depending on the project.) Think about your issue tracking interfaces with your source code control. Think about how change control interfaces with documentation. (You do have at least basic documentation, right?)

Another piece you might overlook is distribution and archive. If an executable (or source code) is sent to someone else, you really should be keeping track of who it was sent to. Does this need to integrate with your CRM solution or your billing/invoice solution? Maybe yes and maybe no, but it should be a conscious decision. When things get hairy, traceability can be a hugely effective tool, but only if it’s in place before you need it. And even if you’re not delivering projects to someone else, it can be useful to have an archive of finished projects.

What are the benefits of doing this work, even if no one else ever sees it? First, it gets you in the habit of defining and following a work flow. Developing good habits now will make it automatic to apply them to larger more complex projects. It also gives you a chance to learn and evaluate the tools in your workflow in a more contained situation. Second, if you ever do need to bring in additional developers, the project will be in a good state to hand off with a minimum off fuss and flailing. Third, maintenance will be much easier and less stressful. And because of the second point, you might even be able to farm out the maintenance tasks, freeing your time to do other more interesting projects. Third, a clean project with good workflow makes it possible to re-use code, either in another project, or in another context entirely.

Ah, the joys of being a developer. You get to keep your development tools up to date. You get to make sure your IDE and source code version control, and testing environments all talk to one another and play nicely. You need to keep all your tools up to date with whatever level of support you need to provide. And you need to keep up to date with the evolving language specs while learning the interesting little bits that can make  difference when you’re trying to write clean, readable, maintainable code.

Today I got bored waiting for some other things, so I read up a continuous integration tool. Tried to set it up. Failed. Failed miserably and in such a way as to feel as though I had made negative progress. So set that distraction aside and read up on some nuances of how Swift import statements work. Dang, I learned something useful; you can import just parts of a module if that’s all you need. If you’re curious, you can read up on it yourself: https://nshipster.com/import/.

NSHipster.com and UseYourLoaf.com are two of my current favorite sources for writing about (mostly) Swift development. If you know of any others, or if you know of an equally good source focussing on Xamarin development, drop me a line.

Well, I finally missed a morning deadline here. The good news is that it was because I was dang busy this week. By three o’clock things had started to settle down a bit and I started trying to remember everything I had done today. I knew it had been quite a bit, but when I started writing it all down, I was surprised at just how much there was and how easy it would have been to lose track of it all to the general sense of busyness.

Keeping a work journal can help. Sometimes I manage to keep a more formal work journal, separating out each project with milestones and issues. But even if you just keep a running log of things accomplished, issues raised, open questions, and future plans, it can be useful. It doesn’t have to be fancy, although I vastly prefer to have a permanently bound notebook so that you aren’t going to rearrange or lose pages. Just a cheap composition book will do the trick. I also use my work journal to jot down test data or to work through possible ideas. Many is the item I’ve been able to answer a questions just by flipping back through the pages of the past week or two. This is also a place where bullet journalling could be very helpful.

And if you want more ideas for how to stay organized and you like podcasts, Kevin Sonney’s Productivity Alchemy podcast can be quite good.

When you’re in a small team and things are moving fast, documentation is important. Yes, documenting your code is important and the issues around it are well known. You do document your code, right? Documenting assumptions and decisions is more important.

There’s always pressure to be “agile” (don’t get me started), and even in a waterfall development model, you will need to make changes during development. Document the issues that led to the changes and why you decided to make that particular change. Eventually you will find yourself asking, why did we do that? If you have even basic documentation around midstream changes, it makes life so much easier. (And don’t forget to include the date when you made the decision. Sometimes knowing the sequence in which changes happened can make all the difference, although you can usually reconstruct sequence using source code versioning. Don’t count on it.)

But the hardest kind of documentation to do, and the one most often missed, is to document assumptions, as many as you can. They can be critical when it comes time to do testing or to evaluate future changes, or even when handling support calls.

Yes, I do mean that you should take the time to put together this type of documentation even if you’re a one-person development team. Six or twelve months down the road, you may not remember all the details of what you decided when. If you’re business expands and you need to bring on additional help, or if you’re in a larger team and you have turnover, this kind of documentation can make maintenance and enhancement go much more smoothly.

I may have been dealing recently with a project that has suffered greatly because the previous development team assumed that they would be doing the work so they didn’t document everything. Then the project was dumped on an entirely new team with little to no experience with the project. We should be out of the weeds in another week, but it’s not been a fun process. Now, every time I’m tempted to cut corners, I’m going to remember this project.