Mike Zornek

A Few Good Memes

mike@mikezornek.com (Mike Zornek) — Wed, 29 Jan 2025 08:46:05 -0500

Yesterday I took to r/ProgrammerHumor to reply to this post about code review. I used a meme I crafted back in September and posted this meme as I was preparing for quarterly performance review season. It since has gotten some replies that have me laughing out loud. Recording for prosperity.

Intelligent-Touch936 writes:

We live in a world that has code, and that code has to be perfect. Who’s going to ensure that? You? You, with your lenient comments? I have a greater responsibility than you can possibly fathom. You weep for your feelings and you curse the review process; you have that luxury. You have the luxury of not knowing what I know: that my critique, while harsh, probably saved the project. And my existence, while meticulous and unkind, brings us closer to a flawless system. You want me to be nicer? You can’t handle the nicest! Because deep down in places you don’t talk about at stand-ups, you want me on that review. You need me on that review.

We use words like “optimize,” “refactor,” “debug.” These words are the backbone of our development process. I have neither the time nor the inclination to explain myself to someone who rises and sleeps under the very quality code that I provide and then questions the manner in which I provide it. I’d rather you just said “thank you” and went on your way. Otherwise, I suggest you grab an IDE and get to work. Either way, I don’t give a damn about what you think you’re entitled to!

Prosecutor: Did you force push main?

Defendant: I did what I needed to do.

Prosecutor: DID YOU FORCE PUSH MAIN?

Defendant: YOU’RE GODDAMNED RIGHT I DID!

Personal Elixir Code Aesthetics

mike@mikezornek.com (Mike Zornek) — Sun, 29 Sep 2024 20:25:46 -0400

With my side project Flick hitting an MVP milestone and inspired by some conversations during Elixir Book Club, I thought I’d take a moment to document some code aesthetic choices I made in this project.

The order below is not ranked in importance. In fact most of this is nitpicky, but still my preference.

Whitespace between import and alias.

Alphabetically ordered alias declarations.

Avoiding multi-alias declarations.

  # lib/flick/ranked_voting.ex
  import Ecto.Query

  alias Flick.RankedVoting.Ballot
  alias Flick.RankedVoting.Vote
  alias Flick.Repo

Whitespace should be done with intention to separate distinct concepts; and for me, import and alias are distinct concepts.

I also list my alias declarations in alphabetical order, enforced via AliasOrder and use a preferred order across use, import, alias, and require via StrictModuleLayout.

I prefer to avoid multi-alias declarations like alias Flick.RankedVoting.{Ballot, Vote} since it makes searching the code base for module names harder to do. This is enforced with MultiAlias.

(Generally) prefer multiline do/end functions.

defp page_title(:edit), do: "Edit Ballot"
defp page_title(_), do: "Create a Ballot"

Unless I can express a group of functions in a simple stack (like the above code) I generally prefer multiline do/end function declarations. One reason for this preference is that my code editor can collapse the whole module in a nice way, making during exploration easier.

# This could be one line, but I prefer multiline do/end.
def get_ballot!(ballot_id) do
  Repo.get!(Ballot, ballot_id)
end

Use consistent DSL layout in test modules.

# test/flick/ranked_voting_test.exs
describe "update_ballot/1" do
  test "success: updates a ballot title and questions" do
    # ...
  end

  test "failure: `question_title` is required" do
    # ...
  end

  test "failure: can not update a published ballot" do
    # ...
  end
end

Test files can generally end up 2 or 3 times the line count of the module under test. To help keep this code organized and easy to navigate I use a style where I will list the function under test using describe and then various success and failure expectations in each test. For functions like list_ballots/1 that can’t fail, one might drop the success label, but looking at my code as it stands today, it looks like I kept it. 🤷‍♂️

I have far less consistency with my LiveView tests. Sometimes the describe breaks out new vs edit logic, other times it breaks out with or without authentication paths. I’m still evolving this and welcome ideas and good examples.

Invest in test fixtures

Arrange, Act, Assert. To help keep your arrange logic neat and tidy, invest in good test fixture tooling. These test fixtures should provide functions for entity creation in your test files as well as the known list of argument defaults (for tests that need to do something more custom but do not want to be burdened with a complete understanding of every argument).

These fixtures should use the actual domain context paths for creation and not raw SQL injection unless absolutely needed for performance or edge cases.

# test/support/fixtures/ballot_fixture.ex
defmodule Support.Fixtures.BallotFixture do
  @moduledoc """
  Provides functions to allows tests to easily create and stage
  `Flick.RankedVoting.Ballot` entities for testing.
  """

  alias Flick.RankedVoting.Ballot

  @doc """
  Returns a map of valid attributes for a `Flick.RankedVoting.Ballot` entity,
  allowing for the passed in attributes to override defaults.
  """
  @spec valid_ballot_attributes(map()) :: map()
  def valid_ballot_attributes(attrs \\ %{}) do
    Enum.into(attrs, %{
      question_title: "What day should have dinner?",
      possible_answers: "Monday, Tuesday, Wednesday, Thursday, Friday",
      url_slug: "dinner-day-#{System.unique_integer()}",
      published_at: nil
    })
  end

  @doc """
  Creates a `Flick.RankedVoting.Ballot` entity in the `Flick.Repo` for the passed in
  optional attributes.

  When not provided, all required attributes will be generated.
  """
  @spec ballot_fixture(map()) :: Ballot.t()
  def ballot_fixture(attrs \\ %{}) do
    attrs = valid_ballot_attributes(attrs)
    {:ok, ballot} = Flick.RankedVoting.create_ballot(attrs)
    ballot
  end

  @doc """
  Creates a `Flick.RankedVoting.Ballot` entity in the `Flick.Repo` for the passed in
  optional attributes and then publishes the ballot.

  When not provided, all required attributes will be generated.
  """
  @spec published_ballot_fixture(map()) :: Ballot.t()
  def published_ballot_fixture(attrs \\ %{}) do
    attrs = valid_ballot_attributes(attrs)
    {:ok, ballot} = Flick.RankedVoting.create_ballot(attrs)
    {:ok, published_ballot} = Flick.RankedVoting.publish_ballot(ballot)
    published_ballot
  end
end

Aside: I hate how the typespecs here use map() for the attribute map. I want to make that more detailed in the future, see issue #4.

Use tiny_maps to save horizontal line space in tests.

test "success: submitting valid form creates ballot and redirects", ~M{view, ballot} do
  # ...
end

When composing my test descriptions, I like to get the test "..." do on a single line. To help achieve that, I use the tiny_maps library to help me express repetitive argument maps with a more concise syntax: ~M{view, ballot} expands to %{view: view, ballot: ballot}. I generally limit this syntax sugar to test files but would not be against using it in the main source in the future.

Compose code to prefer clean line breaks

I love that Elixir ships with an opinionated formatter. However, even with the formatter, you still have a lot of influence on how your code is composed. I prefer it greatly when expressions are clean one-liners or otherwise avoid excessive indentation when breaking up complex terms.

To help explain, let me walk you through a test from Flick.

test "success: submitting valid form creates ballot and redirects", ~M{view} do
  payload = %{
    question_title: "What's your favorite color?",
    possible_answers: "Red, Green, Blue",
    url_slug: "favorite-color"
  }

  response =
    view
    |> form("form", ballot: payload)
    |> render_submit()

  # Assert upon submit the page redirects, and the ballot was created.
  assert {:error, {:redirect, %{to: redirect_target}}} = response
  assert "/ballot/favorite-color/" <> secret = redirect_target
  assert %Ballot{} = RankedVoting.get_ballot_by_url_slug_and_secret!("favorite-color", secret)
end

First, let’s take note that response is captured in its own line group. Technically, you could compose render_submit() to happen on the same line as assert, but by capturing response using its own line group, it helps separate the act vs. assert test concepts and avoids a very complex indentation variant.

# A complex multiline expression with lots of indentation, I am trying to avoid.
assert {:error, {:redirect, %{to: redirect_target}}} =
         view
         |> form("form", ballot: payload)
         |> render_submit()

Next, let’s look at the pipe feeding response. You could compose the code like this:

response =
  view
  |> form("form", ballot: %{
      question_title: "What's your favorite color?",
      possible_answers: "Red, Green, Blue",
      url_slug: "favorite-color"
  })
  |> render_submit()

I dislike this composition since it breaks the pipe. By moving the payload value assignment to its own line group, we end up with a cleaner pipe that, in my opinion, reads better.

payload = %{
  question_title: "What's your favorite color?",
  possible_answers: "Red, Green, Blue",
  url_slug: "favorite-color"
}

response =
  view
  |> form("form", ballot: payload)
  |> render_submit()

Embrace pipelines with custom utility functions.

# lib/flick_web/live/ballots/index_live.ex
def mount(_params, _session, socket) do
  socket
  |> assign(:page_title, "Admin: Ballots")
  |> assign(:ballots, Flick.RankedVoting.list_ballots())
  |> ok()
end

defmodule FlickWeb.LiveViewPipes do
  @moduledoc """
  A collection of functions to help express pipes when processing live view responses.
  """

  alias Phoenix.LiveView.Socket

  @spec ok(Socket.t()) :: {:ok, Socket.t()}
  def ok(%Socket{} = socket), do: {:ok, socket}

  @spec noreply(Socket.t()) :: {:noreply, Socket.t()}
  def noreply(%Socket{} = socket), do: {:noreply, socket}
end

Many LiveView functions require tuple return values like {:ok, socket} or {:noreply, socket}. To help allow call sites to be composed as a single pipeline, I use some utility functions like ok() and noreply().

Be consistent between module names and filenames.

If I have a module called Flick.RankedVoting.RankedAnswer it lives at the filepath lib/flick/ranked_voting/ranked_answer.ex

While I have good consistency inside my core domain contexts, this consistency fails with various Phoenix things. For example, FlickWeb.Ballots.EditorLive lives at lib/flick_web/live/ballots/editor_live.ex. I dislike that Phoenix generators put these modules in a folder called live that the module path does not express. I may fix that in the future.

Related blog post: LiveView Modules Must End in Live

Write professional documentation.

  @doc """
  Publishes the given `Flick.RankedVoting.Ballot` entity.

  Once a `Flick.RankedVoting.Ballot` entity is published, it can no longer be updated.
  Only a published ballot can be voted on.
  """

All public functions, especially those that represent the formalized domain API for your system, should get documentation.

Each documentation block should start with a single-line, terse summary, as those are used by ex_doc and other developer tooling to summarize function indexes. Every so often, look at the collection of function summaries of a module and try to make them all use consistent phrasing like “Returns noun given thing…” or “Raises Blah when stuff…”.

If referencing another module, function, or callback, use backticks to help the documentation system generate hyperlinks.

Use rewrap tools to hardwrap characters to 80 columns to help with GitHub diffing and more presentable Markdown.

Document your decisions.

Programming is all about tradeoffs. When making an intentional design or process decision with other valid approaches available, consider documenting what was considered and why you went with your approach. Your future self and peers will thank you.

I’ve documented some things related to timestamps, schema shape, and fixme/todo so far in Flick.

Make sure each FIXME has an issue URL.

Related to the above decisions, Flick allows FIXME comments but requests all FIXMEs include a link to a GitHub issue documenting the concern.

Avoid abbreviations and prefer expressiveness.

Prefer expressive variable names like _ballot over _.

Prefer expressive variable names like ballot_params over params when you think it helps improve clarity.

Words matter.

Invest time in an expressive and consistent ubiquitous language for your project. Continue to edit it over time as the terms evolve.

Find consistency in your project code regarding terms like create vs. new, update vs. edit, submit vs. save, params vs. attributes.

Do your best to align with existing Elixir community norms.

Craft typespecs to express your domain.

All public functions should have a typespec. Private functions can also have typespecs, depending on whether they will help with code clarity or change confidence.

Spend time and make those typespecs match the domain. For example, when accepting the identity of a Ballot use the Ballot.id() not a Ecto.UUID.t().

  # lib/flick/ranked_voting/ballot.ex
  @type id :: Ecto.UUID.t()

When building types for my main domain entities, I tend to build the main t() around a persisted entity value that is brought into memory from a Repo, and thus all post-creation values like id or updated_at are typed to their expected value, without the need for an | nil addendum.

To help write typespecs for non-persisted structs of this schema type, I make a schema_t() variant.

  @typedoc """
  A type for a persisted `Flick.RankedVoting.Ballot` entity.
  """
  @type t :: %__MODULE__{
          id: Ecto.UUID.t(),
          question_title: String.t(),
          description: String.t() | nil,
          url_slug: String.t(),
          secret: Ecto.UUID.t(),
          possible_answers: String.t(),
          published_at: DateTime.t() | nil
        }

  @typedoc """
  A type for the empty `Flick.RankedVoting.Ballot` struct.

  This type is helpful when you want to typespec a function that needs to accept
  a non-persisted `Flick.RankedVoting.Ballot` struct value.
  """
  @type struct_t :: %__MODULE__{}

Spend time writing typedoc documentation, it can be a helpful space to talk out the reasoning behind some of the types.

In addition to writing typespecs, when composing functions I also prefer pattern matching the struct and using guards to be explicit about incoming argument expectations.

  def change_ballot(%Ballot{} = ballot, attrs) when is_map(attrs) do
    # ...
  end

Dialyzer is not a runtime enforcement tool, but these are. They help enforce expectations earlier in the call stack and thus help you become aware of when things are not as they seem sooner.

Document your dependencies.

To help future you know why various dependencies were added to the project, add a minimal description before listing it.

  defp deps do
    # ...

    # For Observability.
    {:appsignal_phoenix, "~> 2.5"},

    # To Render Markdown.
    {:earmark, "~> 1.4"},

    # For security scans.
    {:sobelow, "~> 0.13", only: [:dev, :test], runtime: false},
  end

Document and validate function options.

  # lib/flick/ranked_voting.ex

  @doc """
  ...

  ## Options

  * `:action` - An optional atom applied to the changeset, useful for forms that
    look to a changeset's action to influence form behavior.
  """
  def change_vote(%Vote{} = vote, attrs, opts \\ []) do
    opts = Keyword.validate!(opts, action: nil)

    # ...
  end

If you offer a function that accepts options as the final argument, document them and validate them.

Validation helps ensure call sites do not include unexpected or typoed option keys and offers a clean space to provide a default value for the said option.

Aside: Not currently demonstrable in Flick, but is in some of my work project, I usually write rich typespecs for my options as well.

Compose PR titles for clarity and consistency.

With Flick, I work in focused PRs and have those PRs titled for clarity regarding what is changing. I like using prefixes like fix chore feat. These PR titles are enforced with a specific GitHub Action workflow. These PRs are squash merged and make for a (hopefully) readable main branch.

In the future, I might even be able to automate this to help with release notes.

Strive for database precision.

Be detail-oriented when building out your database tables.

If something can not be null, be explicit NOT NULL.

If a string can be really long, use :text. If you do use :string (which has length limits), then enforce those length limitations in Ecto.Changeset so the value is not trimmed quietly.

Virtual fields on Ecto schemas are almost never the right answer.

That was quite the hodgepodge of suggestions and tips. I had others, but they did not fit, or I don’t have good open source references yet.

If you liked these or disagree, let me know.

Notes about Technical Debt

mike@mikezornek.com (Mike Zornek) — Mon, 17 Apr 2023 10:42:07 -0400

The Elixir Book Club is reading Software Design X-Rays: Fix Technical Debt with Behavioral Code Analysis.

This past Sunday, we had our first meeting, reviewing chapter one and sharing some interesting discussions on technical debt. I wanted to capture some thoughts while they were fresh in my head.

What is technical debt?

So the book starts by defining technical debt as:

a metaphor that lets developers explain the need for refactorings and communicate technical trade-offs to business people. When we take on technical debt we choose to release our software faster but at the expense of future costs, as technical debt affects our ability to evolve a software system. Just like its financial counterpart, technical debt incurs interest payments.

Personally, I would add the concept of decay and entropy in addition to mindful choice. Often, code that is eventually identified as technical debt was added to the system with a less perfect understanding of the requirements, or the requirements changed after the fact. Perhaps the developer leveled up their skills and has new ideas about approaching the problem and avoiding previously accepted trade-offs.

Software libraries are also deprecated over time and need to be updated/replaced. Otherwise, you must deal with open security issues or the troublesome constraint of integrating old libraries with newer industry expectations.

Working towards a tech debt framework

The eventual goal of the book is to give you a framework to look at large codebases and understand what areas of the codebase would benefit from addressing technical debt the most. It uses git’s version history as a source and wants to provide statistical signals you can use in addition to (and in favor of) exclusive emotional reactions.

Sounds like a reasonable start. It tracks the same way I want production observability signals to help me understand the system.

What the book does not get into is the discussions around getting time allocations in sprints to address technical debt. Depending on your circumstances, that is a more meaningful blocker than figuring out how to spend that technical debt time. The book club discussions ran on this for a while.

Selling

Technical Debt Meme

Saw this meme over the weekend, and it’s a good discussion starting point for the common perspective challenges of technical debt.

You may see the house in that broken state, but the owner might see a working house and need help understanding what all the fuss is about. We don’t share the same vision of the system. We each have our own perspectives and biases.

To continue the construction metaphor, yes, the inner wiring of the house might be decrepit and a fire hazard, but the owners are not electricians. They see and use abstractions like light switches and heat regularly without issue. They don’t see nor understand the system’s inner workings, and it’s your job to express your perspective: to help them understand how things work, why it might be a good idea to replace the wiring, and what failing to replace it looks like regarding managed risk.

I suspect many programmers don’t like being a salesperson, but you need to do it to be a successful voice on behalf of the system.

Last week, while attending Philly ETE, I saw a great talk on this topic titled Leading with the Platform: A Platform Engineering Approach to Tech Debt by Jess Mink.

Platform teams, SREs, tool teams, DevOps…we are the stage crew of a software company: we’re only noticed when we mess up.

This talk is about how platform teams have the potential to be proactive and lead projects across engineering so that things can be addressed they break, thereby reducing tech debt before it’s accrued, and they can be noticed for something positive for a change.

We’ll be talking about company objectives, data, thinking like a product manager, and how it benefits the company as a whole if other teams can get into the act and to pick up some of the platform team’s work.

You can also check out this article on how to sell technical debt and why positioning the business value of technical debt is crucial to getting buy-in and approvals.

Sprint planning and broken glass

While a product manager has the ultimate say and owns the sprint plan, various stakeholders still influence it. To simplify, let’s say we have one group representing the customers and the other representing the developers. Each group has their own short-term and long-term interests. A good sprint and roadmap will have a healthy mix of all four areas. If the weights of any of these four areas get too out of proportion for too long, things will get into a bad state.

Specifically to the short-term interest of developers, I’m a big proponent of giving individuals timeboxed ‘broken glass’ autonomy. This is a metaphor that comes from theme parks. If you are an employee, and your job has you walking the park day in and day out, when you see broken glass on the floor, you should stop and clean it up for the serenity and safety of everyone else.

A more strict and formal management style would have the employee report the observation, have it queued for review, and then (maybe) executed days or weeks later—a lot of overhead for a 20-minute clean-up job.

Giving programmers autonomy to identify, timebox, and execute pain points they experience in the codebase is both efficient and satisfying for the programmer.

Trust

“All this sounds nice, but my product manager does not trust the development team. They never approve technical debt work.”

Earning and having trust with coworkers is a foundational and challenging need. If the product manager does not have trust in the development team, ask those hard why questions.

For the developers:

Work hard to empathize with the product manager and the million spinning plates they are trying to keep up.
A common cause of friction is missed deadlines, so work with the product team to descope work and create small iterative loops with extreme priority. Always keep the system in a shippable state.
Be expressive about progress, letting the product manager dig deep when needed, but have a high-level understanding at all times.
Give them the information and choices, and when a choice is made, work to execute it professionally.

For the product managers and owners:

Be transparent with your whole team about the company’s status and goals. Don’t consider these ’non-programming status communications’ as wasteful. Developers make hundreds of decisions on the company’s behalf, with or without this context. The more informed they are, the better decisions they can make.
Create space for trust to be earned. Instead of assigning a sprint’s worth of tickets to a team, let the team choose the capacity.
Create space for empathy to grow. Encourage pairing across multiple job titles so people better know what all corners of the company feel like.

For more on trust, I recommend The Five Dysfunctions of a Team: A Leadership Fable by Patrick M. Lencioni.

Join us

If you’d enjoy discussing technical debt, join us for future book club discussions. We meet on Sundays every two weeks via our Discord. More info at: https://elixirbookclub.github.io/website/.

Elixir Context Accessor Function: Which Return Type Do You Prefer?

mike@mikezornek.com (Mike Zornek) — Sun, 12 Feb 2023 13:55:42 -0500

During a recent Elixir Book Club meeting we had a back and forth discussion on a simple code style question:

When providing an accessor function inside your domain context, do you prefer a return type of {:ok, noun} || {:error, :not_found} or noun || nil ?

In my own historical work I’ve generally followed along with common Phoenix generator style of building out functions like get_noun/1 that return the noun or nil but moving forward I think I’ll be preferring fetch_noun/1 functions that use an :ok / :error tuple style return type.

The primary reason is expressiveness in the crash logs. Eventually there will be some crash and the stacktrace is going to show nil being passed into some function, and the function having an expectation of a real value type. In those moments it can take some time to understand where the hell nil is coming from. I think an error like noun_not_found will be more helpful.

I want to start keeping track of these personal preferences and so today I’ve also made a new guide for the Franklin project documenting Code Style: Context Accessors. There is some more background and reasoning about my preferences inside should you be interested.

While that guide expresses a preference towards fetch_noun/1 and the :ok / :error tuple return type, it also acknowledges that it might be helpful and supportive for the context to offer multiple accessor functions allowing the call sites to use whichever one is more appropriate. ` How about yourself? What return type do you prefer and why? Let me know.

The Curse of Test Fixtures

mike@mikezornek.com (Mike Zornek) — Thu, 27 Oct 2022 20:10:37 -0400

Please heed my warning or be cursed with coupled test code!

The general use case for test fixtures usually involves impure functions. These functions rely on an external collaborator and not just the incoming arguments of the function. Before the test runs, you want to put the world in a particular state. A common case is a database, your app’s repository of entities.

You have choices for how to make this happen.

One choice/tool I observe many Elixir developers reaching for is ex_machina, a fixture/factory tool. I’ve used it myself on many projects. It can be a productive addition.

In short, ex_machina lets you build a factory of fixtures, even fixtures with relationships to other fixtures. When the time comes, you invoke insert(:user) in your test, and your database is populated with the generated data. The world is now set for you to test your list_users/0 function.

This is (usually) a poor choice.

The problem is coupling. When you call insert(:user), you are hard injecting the database with an assumption of what it means in the domain to “create a user”. You probably have a real domain context that provides a create_user/1 function. Instead of using it, you couple this test, which needs a user already in the system, with assumed implementation details.

In the early days of a project, this raw database injection will likely be pretty close to what you have going on in create_user/1, but as the project evolves, these two paths can quickly diverge. The challenges and risks of maintaining parity between what it means to “create a user” through the domain context OR the factory’s raw database injection will become an expensive burden. Still worse, when you want to refactor create_user/1, you can’t – at least not without touching every part of the test suite that used fixtures and made assumptions about the database layout.

The much better choice is to, when needed for impure tests, use your domain contexts to influence the world.

Be extremely mindful of the API boundaries of your code. Test the boundaries and NOT the implementation.

Using real domain contexts to populate the world state can sometimes be slower. My suggestion is to swallow this slowness up front and only fallback to direct fixture injection when the testing performance needs are a good tradeoff for the cost of coupling. Since coupling will hamper refactoring, I consider that and HUGE tradeoff, and so it would take a significant speed difference to make me reconsider.

For more on this concern, check out Saša Jurić’s Clarity talk. He talks of helper methods he usually makes, like register!/1 at minute 38.

Elixir Style: Prefer Unnested Aliases

mike@mikezornek.com (Mike Zornek) — Fri, 01 Apr 2022 12:31:06 -0400

This post was originally written for my old ElixirFocus blog, and transfer here after its closure.

In Elixir, alias is a keyword we often use to create shorthand references to long-form module names allowing us to refer to RetroTaxi.Boards.Board simply as Board.

You’ll often end up with a collection of alias declarations at the top of a module, and Elixir offers two ways to format these.

One way is simple list such as:

alias RetroTaxi.Boards.Board
alias RetroTaxi.Boards.Column
alias RetroTaxi.Boards.TopicCard

The other way is an optional nested list like:

alias RetroTaxi.Boards.{Board, Column, TopicCard}

Sometimes this nested list is broken across separate lines and presented like:

alias RetroTaxi.Boards.{
    Board,
    Column,
    TopicCard
}

Style Recommendation

I highly recommend avoiding this nested presentation. The primary reason is to help keep the codebase plain-text searchable. By avoiding the nesting, you can quickly find which modules are referencing any module simply by searching for its name string like RetroTaxi.Boards.Column. Finding nested aliases would require a more complex regular expression or language server tooling.

If you want to enforce this style with a credo, check out Credo.Check.Readability.MultiAlias which is usually disabled on a default credo install.

Improve the Clarity of Your Elixir Code Through Expressive and Consistent Language

mike@mikezornek.com (Mike Zornek) — Sun, 06 Jun 2021 12:00:00 -0400

This post was originally written for my old ElixirFocus blog, and transfer here after its closure.

One of our primary day-to-day responsibilities as programmers is to communicate. We need to express our ideas, explain our work and document our code. Having a strong vocabulary and explicit intentions behind the words you (and your team) choose can greatly help avoid confusion.

Take some time as a team to talk about how you name and describe things. Embrace productive confrontation when you identify inconsistencies and work towards creating (and documenting!) as much as a ubiquitous language as you can.

The following is a collection of terms I try to be mindful of in my own work. Hopefully this list helps inspire some of your own terminology choices.

Programming Terminology

Entity vs Value

An entity is a structure that has identity. An Account in my application has a unique identifier and is thus is considered an entity.

A value is a structure without identity. A Color in my application might be made up of three scalars like red, green and blue. Collectively they make up the Color value but there is no identity.

Some people might prefer the term record instead of entity in this context. I consider the terms fairly similar so would honor my team’s chosen preference.

Entity vs Row

Sometimes when we talk about entities we’ll get into the deeper discussions of how the entities are persisted, usually inside a database At that point I make a special case to change how I talk, being more explicit about the database row. Entity is how I refer to the in-memory representation of the structure, but if we are talking about database storage or SQL-specific things I want to use the term row to be more explicit.

Maps vs Structs vs (Ecto) Schemas

Maps, Structs and (Ecto) Schemas are all Elixir structure tools that we use to create entities and values. Each of these tools has their own purpose and constrains so I try to be explicit when talking about which tool we are using.

Create vs New vs Insert and Remove vs Delete

As you define the core domain nouns of your app you’ll inevitably start to build out a series of modules that help you manage these nouns. When designing the interfaces of these modules have an explicit pattern for how to name behaviors and try when possible to lean on community patterns. Ask yourself, “how does the Elixir language or popular frameworks use these terms?”

Delete and New as used inside of Elixir.

You can also take advantage of the various Phoenix/Ecto generates for a peek at some pattern recommendations from the framework authors. These are usually a great place to start, although I don’t consider the patterns to be gospel.

In addition to the working on the names of the modules functions themselves, you may also be involved in the user experience of an app and its own terminology. Ideally the nouns and terms from the interface down through the code will align but this is not always possible. Sometimes the needs of the user experience design require the terminologies to deviate. While not ideal, I’m fine with this – it just has to be done with intent and consistency. Write down the terms you have chosen and why.

Get vs Fetch

There are a few notable Elixir patterns to be mindful of with the terms get vs fetch.

First let’s check out Map.get/3 which will return a value for the given key or a default value if the key is not found.

iex> Map.get(%{}, :a)
nil
iex> Map.get(%{a: 1}, :a)
1
iex> Map.get(%{a: 1}, :b)
nil
iex> Map.get(%{a: 1}, :b, 3)
3

Next we have Map.fetch/2 which will return an :ok tuple or :error if the key is not found.

iex> Map.fetch(%{a: 1}, :a)
{:ok, 1}
iex> Map.fetch(%{a: 1}, :b)
:error

There is also a bang version of fetch, Map.fetch!/2 which will return the value or raise an exception if the key is not found.

iex> Map.fetch!(%{a: 1}, :a)
1

The takeaways from these language patterns I take note of are the following:

get_noun should return the value or a default if not found.
fetch_noun should return a :ok tuple or an :error tuple.
Any function with a bang (exclamation point) will throw an exception, and that exception should be documented inside the inline documentation.
In general I try to avoid creating bang style functions as I feel like Elixir exceptions should be exceptional. You may notice that the there are Phoenix code generators out there that will create a get! style functions in generated contexts. That is pattern I am aware of but question in newer code.

List vs Array

I do my best to be mindful of and embrace the terminology of the language I am working in, moment to moment. This means if we are dealing with a collection in Elixir I’ll say list and when we are dealing with a collection is JavaScript I’ll say array. In an Elixir context I’ll say map and in a JavaScript context I’ll say dictionary.

For a junior programmer this might seem like symantec nonsense but I think its an important distinction. Related, I honor the styles of the host language, for example using camel case for variables in JavaScript and underscores in Elixir. With luck a linter of some kind can help remind me if I loose my place.

Behavior vs Feature

When talking about what my code does I use the term behavior. I describe the behaviors I want to build and I document the behaviors I observe.

The term feature is more a product or marketing term, usually describing a collection of end user observable behaviors.

App and Business Domain Consistency

Document Your App’s Custom Terminology

While I have some personal preferences to share below, ultimately every app will have a custom vernacular for how they label things in the system. Spend some time getting team agreement on the meaning and intent behind these terms. Write them down. Review and evolve the glossary when needed. Having alignment on this language will be extremely helpful over time as you discuss what to code needs to do.

Authentication vs Authorization

Many people simply talk about “auth” systems without being explicit but it’s important to distinguish between authentication, figuring out who you are talking to, and authorization, figuring out if someone should be allowed to do something.

My own preference here is to use Sign in, Sign out and Sign up. I’m also ok with other variants like “Create Account” in the user experience as long as we are consistent.

I dislike log in since it is too easy to mix up the term “login” vs “log in”.

Account vs User and Settings vs Preferences

No strong personal preferences here, would have to consider the application context – but once again I am looking for consistency. If I were debating choices for a new app with my team I’d look at some industry competition to see what they do.

Language I Try to Avoid

Bad Code and Code Smell

I do my best to follow the retrospective prime directive which states:

Regardless of what we discover, we understand and truly believe that everyone did the best job they could, given what they knew at the time, their skills and abilities, the resources available, and the situation at hand.

Believing this, I try to avoid saying something is “bad code” or has a “code smell”. Those phrases package a lot of negative judgement which is not very constructive. Instead let’s look for opportunities to improve testability, or documentation or abstractions. No one wrote this “bad code” intentionally to sabotage the system. We are all members of an extremely immature and fast moving industry with diverse backgrounds and levels of experience. It is messy out there and everyone is learning as we go.

If you are doing a code review, instead of saying something has a “code smell”, kickstart a discussion around getting more context around the decisions and constrains that led to this code’s design. Ask if they considered an alternative or are aware of your concerns. These pull requests are opportunities for education and starting the process with judgement language is not going to result in many positive outcomes.

Video: Using Fixtures and Test Assets in Swift Unit Tests (9m)

mike@mikezornek.com (Mike Zornek) — Wed, 02 Sep 2020 10:42:44 -0400

In today’s video I’ll demonstrate how you can use the concept of fixtures in your Swift unit tests to quickly build business objects and validate scenarios.

I’ll also show how you can add assets to a test target and then access them in code using Bundle(for: SomeTypeInTheTestBundle.self).

The code you see in the video is part of a demo project on GitHub:

https://github.com/zorn/VersionedFilesDemo

Your browser does not seem to support the video format. You can download the MP4 file directly.

Download MP4 Watch on YouTube

Thanks for watching!

Renaissance Man

mike@mikezornek.com (Mike Zornek) — Mon, 16 Mar 2020 15:39:04 -0400

👨‍💻 Right now I’m on a client project that has me working on an iOS SDK codebase but still touching GoLang, C and Kotlin/Android as well. I’m doing the best I can but it is challenging jumping around, particularly into languages I don’t have a rich history with.

This experience does however back up my opinion that good programers are better off being proficient in many languages.

If you do find yourself with some extra time indoors over the next few weeks, consider giving yourself a distraction and try to learn something new. I recommend Exercism as a great starting point for many different languages. They even have mentors to help. I also like PragProg’s “Seven (Things) in Seven Weeks” series.

Good luck out there. Stay safe, stay sane. Make today count!

Code Documentation

mike@mikezornek.com (Mike Zornek) — Tue, 19 Feb 2019 10:00:00 -0500

This article is part of a series, Professional iOS Projects.

Professional iOS projects have good code documentation.

What is code documentation?

When I talk of code documentation I generally mean two things. First is inline code documentation, those triple slashed comments in a Swift file you use to describe types, properties and methods. Second, I mean guides, which are articles that describe aspects of the code from a higher perspective, usually explaining expected interactions as well as the thinking behind the design.

Documentation is great. It helps people who are new or returning to a code base learn how things work and like unit tests can help lead to better designs as documenting a poor design usually will help expose potential issues and misunderstandings.

Why should I write documentation?

All that sounds great but how come no one writes any code documentation?

Sadly it’s a victim of our current industry norms.

You won’t find many “how to write great code documentation” classes in a computer science curriculum. Most “learning to program” books will overlook the topic entirely or limit coverage to a passing mention of the document syntax format for the given language.

Even at work, when was the last time a pull request of yours was rejected for missing documentation? When was the last time your manager brought up code documentation during a sprint plan? Maybe you are getting pushed around for a quick delivery. Was documentation a requirement in the client contract? Has anyone suggested that if it’s not in the contract it’s not part of the deliverable?

This is where we separate the coders from the professional programmers.

Some, many in fact, work in this industry just to make a buck. Others like to consider themselves craftsman or professionals. These people constantly look for ways to improve themselves and the community around them. It is in these people I put my faith that over time, code documentation norms will get better, like other behaviors before it.

When I first started programming very few people used version control day to day, leaving it for only the most complex of projects. A daily ZIP file of the source and passing around .patch files worked just fine for many.

Testing has also followed a similar path where back in the day only a few would consider testing helpful and tools were hard to find and integrate, but now test targets are part of the built-in project templates.

Progress is being made.

Aside: While I general feel the community norms around code documentation need to improve I did want to point out that open source is one ecosystem which is shown to highly value code documentation the tooling around it.

If you are looking for good code documentation examples, try to find an active open source project to reference. You’ll usually find some helpful patterns to follow.

How do I write documentation?

Swift inline documentation is easy enough to get started with.

Example 1:

/// Describes a person whom we have met in real life.
class Contact {

    /// The name of the person.
    let name: String

    /// Initialize new `Contact` instance.
    ///
    /// - Parameter name: The name of the contact we met.
    init(name: String) {
        self.name = name
    }
}

To add documentation use three slashes /// to start a line of documentation. You’ll want to document the type, the properties and then methods. Also, notice for methods that take parameters there is a format to document them as well.

In Xcode you can also use Option+Command+/ to bulk paste a documentation line template. This template is particularly useful when documenting a method with lots of parameters and other parts.

Swift documentation supports Markdown and if you backtick mentions of a type it often will generate a link to that type when the documentation is rendered in Xcode.

Example 2:

/// A data store to hold `Contact`s of the user.
class ContactStore {

    //MARK: - Properties

    /// The currently managed `Contact`s of the store.
    private (set) var contacts: [Contact] = []

    //MARK: - Methods

    /// Accepts a contact and adds it to the store.
    /// If the given contact was already a member of the
    /// store, the `contacts` collection is not changed.
    ///
    /// - Parameter contact: a contact to be added to the store
    func addContact(_ contact: Contact) {
        guard contains(contact) == false else {
            return
        }
        contacts.append(contact)
    }

    //MARK: - Private

    /// Will search the store for the given contact.
    ///
    /// - Parameter contact: the contact to look for
    /// - Returns: a bool value indicating if the contact
    ///   was found in the store
    private func contains(_ contact: Contact) -> Bool {
        // FIXME: To be implemented
        return false
    }
}

In this second example we use MARK: - SectionName. This helps split up our source file. In particular since we don’t have headers anymore I like how I can segregate private methods to the bottom.

Another example here includes the use of //FIXME. FIXME is not triple slashed so it’s not technically documentation but it will be showcased inside of Xcode’s editor.

The main way you’ll encounter this documentation is through Xcode’s Quick Help. Option click a method and you’ll see:

Sadly there is no official support for HTML generation but there are third party tools like Jazzy that can help.

Writing Guides

In addition to inline documentation you’ll want to write up some more high level guides. These can cover many things from code tutorials to design retrospectives to agreed upon code patterns and terminology.

A great example of this can be found in the open source code base for NetNewsWire. Brent has written lots of helpful documents including Coding Guidelines and a Roadmap.

Resources

Counterarguments

Documentation is one of those things some developers get extremist about. One popular quote:

Good code is its own best documentation. As you’re about to add a comment, ask yourself, “How can I improve the code so that this comment isn’t needed?” Improve the code and then document it to make it even clearer.

Steve McConnell

There is nothing inherently wrong with this statement. I too avoid documenting very simple statements. The bigger problem is that the code we are writing today isn’t very good. It’s usually pretty lousy. It’s a version one for some half written client specification.

If you aren’t finding possible improvements in the code you wrote last year you have a problem. The phase “good code” is very suspect.

There are extremes with anything. Use your judgement. Most people don’t get yelled at for writing too much documentation though.

How to Get Started?

Document something, document anything.

You need not take two weeks off to go back and document everything. Stick to documenting new types or types that are being refactored or take a shot at listing the most complex aspects of your current system and then work down the list.

Give code documentation some time to become a habit. Documentation’s value usually doesn’t popup until a few months after writing it.

Code Consistency with SwiftLint

mike@mikezornek.com (Mike Zornek) — Thu, 24 Jan 2019 12:00:00 -0500

This article is part of a series, Professional iOS Projects.

Have you ever opened a source file and knew instantly it was written by a specific member of the team because of all the curious syntax choices they made? Perhaps they are green and don’t know the community standards or perhaps they spend most of their days in another language which has its own preferred style. What do you do?

Many programmers would agree at a certain level of maturity we look for code consistency in our own work and in our group projects. However manually enforcing a style guide is extremely tedious, error prone and can get personal real quick. The solution is to find tools that automate a community standard and let them enforce if not generate the code patterns for us.

In this post we’ll introduce and demonstrate one such tool for Swift iOS developers called SwiftLint. Its a great first step into a world of consistent code and easy to get integrated into your Xcode project.

What is SwiftLint?

Wikipedia describes a linter as:

Lint, or a linter, is a tool that analyze source code to flag programming errors, bugs, stylistic errors, and suspicious constructs. The term originates from a Unix utility that examined C language source code.

SwiftLint is a tool that can scan your Swift code files and generate a list of warnings and errors based on a community provided collection of rules. It has great Xcode integration and online documentation.

Installation

There are a few different ways to install SwiftLint. I’ll review the Homebrew method as it is the one I prefer. Assuming you have Homebrew already installed, run:

brew install swiftlint

This will install a command line tool called swiftlint and while you can use it from the command line most will want to integrate it with their Xcode project. To do so, you’ll want to add a new Build Phase for your main app target, specifically a Run Script Phase at the end, and insert the following code:

if which swiftlint >/dev/null; then
  swiftlint
else
  echo "warning: SwiftLint not installed, download from https://github.com/realm/SwiftLint"
fi

Xcode Build Phase Editor

This script will look for the swiftlint command line tool. If found, it will run it on your project’s source files. If not found, it will still allow the build to finish but will post a short message to the console.

SwiftLint In Action

With swiftlint installed and your Xcode project setup, you now will experience new inline warnings and errors, helping to identify code that might lean away from community standards. Sometimes the warnings or errors will even offer automated fix options too.

Warnings and Errors in Xcode Editor

Customizing the Rules

Out of the box swiftlint will enforce a small subset of the 166 (and growing) rule collection. You can however customize the rules you want to enforce on your project by adding a .swiftlint.yml configuration file to the root of your project. Here you can explicitly opt in or disable rules. You can also configure file paths to exclude from rule matching (like Pods or Carthage). You can even configure some rules, defining the thresholds you want to be held accountable to (think file line size or method line size). More details on this configuration is in the SwiftLint README. A full list of Rules is also well documented.

If you want to turn a rule off for individual occurrences, check out the inline disable and enable options:

// swiftlint:disable colon
let noWarning :String = "" // No warning about colons immediately after variable names!
// swiftlint:enable colon
let hasWarning :String = "" // Warning generated about colons immediately after variable names

Personally I recommend turning on all the rules to get started. If you have a previous code base this will probably result in hundreds of warnings and errors but you can easily filter these errors in Xcode to see them, one by one.

When I first started using SwiftLint in a larger project, I did this rule by rule, either fixing the code issues and committing the changes or adding the rule to the disabled list. It took a few hours but was a great way to learn what people considered good standards.

SwiftLint has been my personal go-to tool of choice but if you want to compare some related projects checkout:

Conclusion

SwiftLint is a easy to install and configure tool that helps you add some code consistency to your Swift Xcode projects. It helps you avoid manual style checks during code reviews leaving more time to focus on actual code quality.

The README File

mike@mikezornek.com (Mike Zornek) — Tue, 08 Jan 2019 12:51:32 -0500

This article is part of a series, Professional iOS Projects.

One of the most crucial documents in any project is its README file, a plain text file (sometimes formatted in Markdown) located in the root of the project directory, clearly named, usually in all caps, README.

README is the initial point of contact for product owners, current and future developers and sometimes end users. Even if your project is a solo private endeavor taking the time to produce a good REAME file will answer many questions your future self will have.

Core Components

Project Name and Branding

Name, tagline, logo, and a short description help market and explain what this project is all about. If available, links to more detailed marketing sites is also helpful.

Project Status

Many project, particularly open source ones, like to promote their own status regarding test coverage, current versions, continuous integration, and more. Sometimes this comes in the form of small clickable badge images.

Other helpful links for this section would be to a modern CHANGELOG file and Release Note document.

Feature List

Included towards the top, the goal of this feature list section is to help people understand a project’s core competencies and if it is a good match for their needs. Don’t be afraid to embed high level architectural graphs, screenshots thumbnails or links to screencast demos. There is no reason a README should be text only.

Installation and Getting Started

Dedicated to the users, this section should help people understand what it takes to get to a working version of this software stood up. If prebuilt binaries are available, those should be the linked and recommended.

If there are other setup needs those should be documented here as well. The basic goal is to help the user get to a Hello World demo of the core competency of the project. When it comes to more complex configuration settings, those should probably live in the main documentation, help system.

Development and Contribution

Dedicated to the current and future developers of the project, this section should help someone who wants to contribute or test a development version of the project how to get their environment prepped and how to build the code base.

If there are processes for contributing bug reports, pull requests or documentation updates those should be documented here as well.

If you have specific code style guidelines, those should also be linked to.

Try not to make too many assumptions (we were all green devs at some point) and be as detailed as possible.

Deployment

Deployment can mean a lot of different things to different projects but it doesn’t hurt to have a short summary in the README with more details in a separate guide.

If you have an active TestFlight beta page, link to it here.

Links

While many will encounter your README on places like GitHub, project repos can be moved around, archived, and so on. For that and general convenience, it’s a great idea to have a raw list of project links. From a project’s home page to it’s repository URL to other things like issue trackers, support forums and related blog posts.

If you want to be really helpful link to your competition and other related projects too.

Licensing

To help make it clear what others can do with this project it’s important to pick and document your license. A LICENSE file is a great place for the full legal speak, but a one liner and link on the README can answer most people’s questions in a single glance.

If you need help picking a license help is available. Also keep in mind the license of any third-party code libraries you are using, be sure to reference those as well.

Examples

awesome-labs/iOS-readme-template

README.md template for your iOS open-source projects.

Apple Radar Bug Report

#47121832 - Xcode Project Templates should come with a opinionated README template.

If you have a suggested edit or addition, let me know. See you next time for Anatomy of a Modern iOS App.

New Series: Professional iOS Projects

mike@mikezornek.com (Mike Zornek) — Tue, 08 Jan 2019 12:40:03 -0500

One of the lessons learned from The Pragmatic Programmer by Andrew Hunt and David Thomas is to learn a new language every year.

Different languages solve the same problems in different ways. By learning several different approaches, you can help broaden your thinking and avoid getting stuck in a rut. Additionally, learning many languages is far easier now, thanks to the wealth of freely available software on the Internet.

Over the last few years I’ve really tried to take this to heart and have worked with and dabbled in lots of languages, including:

Objective-C
Go
JavaScript
Elm
Ruby
Elixir
Swift

…and related frameworks/tools:

Ember
ReactJS
Rails
Phoenix
GraphQL

With that context, one of the biggest issues I have with iOS development is that our projects, as a community, lack professional consistency.

If you open a project in any of the frameworks I mentioned above you’ll find very specific places for each piece of the codebase; you’ll find code generators that follow these patterns for new files and tests; you’ll find community accepting tooling standards for bringing it all together. This consistency takes a whole world of questions and decisions off the table making your development life so much easier.

On iOS, every Xcode project is its own unique beast. There are some patterns we get from UIKit but it only gets us so far.

I feel like Apple has dropped the ball. In my opinion, Xcode should have more opinionated and structured project templates to offer. It should have open integration to third-party project templates to easily allow the community to drive us forward. Following “good practices” like migrating code to frameworks, should be easier. Testing should be more streamlined. Failure to add inline documentation should cause warnings. I can go on and on, and I will.

“Professional iOS Projects” is a new blog series where I want to explore what we can do to improve our iOS projects. Apple of course drives us with its closed-sourced, time limited Xcode release schedule, but there is plenty we can work on ourselves, from lint tools to documentation, testing, folder structure, system design and more. It’s a series that could go on forever. 😱

The first post is ready. It’s all about the README file. Please check it out and let me know what you think. I also welcome topic ideas for future articles.

Going to shoot for a weekly release schedule so grab that RSS feed and join me.

I'm Teaching a Half Day iOS Refactoring Workshop in July

mike@mikezornek.com (Mike Zornek) — Mon, 12 Jun 2017 15:38:30 +0000

When I re-entered the self-employed world last March and launched Zorn Labs LLC one of my main goals was to find a way to continue my education work. The first output of this effort has been workshops, specifically one on Refactoring iOS.

I’ve developed and taught the workshop for a local development studio Tonic Design and am now going to run it publicly.

iOS Refactoring Workshop

Throwing away bad code and writing something new from scratch is both risky and expensive. You need to avoid this temptation and instead learn to master small improvements over time.

Refactoring is the art of improving code without changing user behavior. Adding dedicated refactoring time to your workflow and sprints can pay for itself many times over in both added source code flexibility and application stability.

In this workshop we will review refactoring concepts from a high level and then explore example cases found in many iOS projects. As a group we’ll refactor and discuss the benefits of our changes. We’ll then work on our own (or in pairs) to execute what we’ve learned and then demonstrate the results for the class.

This workshop is targeted at those iOS developers who are getting over the hump of learning iOS and now want to know how to write higher quality iOS code. This workshop is capped at 12 people to make sure there is plenty of time for questions and individual attention.

Tickets for the half day workshop cost $189.00 even (we take care of all the ticketing fees). For more information on the agenda, see the event page.

TICKETS NO LONGER FOR SALE

Local performances of this workshop (and others in development) are available for corporate purchase. Contact us for more information.

Regarding Knight Rider and Delegation

mike@mikezornek.com (Mike Zornek) — Tue, 02 Aug 2016 22:14:36 +0000

One of the saddest aspects of being a Big Nerd Ranch instructor in 2016 is that students these days do not appreciate the Michael Knight is to Delegation, as RoboCop is to Subclassing discussion of yesteryear.

From Cocoa Programming for OS X: The Big Nerd Ranch Guide:

Delegation

Let’s start with a story: Once upon a time, there was a man with no name. Knight Industries decided that if this man were given guns and wheels and booster rockets, he would be the perfect crime-fighting tool. First they thought, “Let’s subclass him and override everything we need to add the guns and wheels and booster rockets.” The problem was that to subclass Michael Knight, they needed to wire his insides to the guns, wheels, and booster rockets – a time-consuming task requiring lots of specialized knowledge. So instead, Knight Industries created a helper object, the Knight Industries 2000, or “KITT,” a well-equipped car designed to assist Michael Knight in a variety of crime- fighting situations.

While approaching the perimeter of an arms dealer’s compound, Michael Knight would say, “KITT, I need to get to the other side of that wall.” KITT would then blast a big hole in the wall with a small rocket. After destroying the wall, KITT would return control to Michael, who would charge through the rubble and capture the arms dealer.

Note how creating a helper object is different from the RoboCop approach. RoboCop was a man subclassed and extended. The RoboCop project involved dozens of surgeons who extended the man into a fighting machine. This is the approach taken by many object-oriented frameworks.

In the Cocoa framework, many objects are extended in the Knight Industries way – by supplying them with helper objects. In this section, you are going to provide the speech synthesizer with a type of helper object called a delegate.

What do you think the new metaphor should be?

Quick Launching for Cocoa Unit Tests

mike@mikezornek.com (Mike Zornek) — Wed, 14 Oct 2015 01:22:26 +0000

I was doing some proofreading and research today regarding the latest testing features in Xcode 7. In the process I ended up rereading this article from Mark Dalrymple on code coverage. It’s a great article but it also reminded me of a little tip I wanted to share on the blog.

- (BOOL)application:(UIApplication *)application
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    ...
    // bail out early if we're running as a test harness.
    if (NSClassFromString(@"XCTestCase")) return YES;

    // otherwise load the main storyboard.
    UIStoryboard *storyboard = [UIStoryboard storyboardWithName:@"MainStoryboard" bundle:nil];
    UIViewController *vc = [storyboard instantiateInitialViewController];
    ...
}

Not only can this type of check help speed up your unit test times by a little bit, but, it also makes sure you aren’t loading things like crash log capture tools, performance monitoring injections, or other things that might otherwise interfere with your unit test logic or code coverage numbers. Now if you are doing the new UI testing you’ll probably have to use some other kind of flag to define this path, but regardless the core idea is the same.

Code Patterns Talk, Video Now Available

mike@mikezornek.com (Mike Zornek) — Thu, 23 Apr 2015 17:09:17 +0000

We’ve been trying to a better job of capturing our main talks at Philly CocoaHeads. You can find and subscribe to our small but growing collection of videos on Vimeo: https://vimeo.com/phillycocoa.

I did a talk last month reviewing a some iOS code patterns. The runtime is about 27 minutes. Feedback very welcome.

Update April 27, 2025: Video not available.

Some Code Patterns, Mike Zornek from Philly CocoaHeads on Vimeo.

This talk covers a handful of code patterns that were successful on my recent projects. Some of these patterns include Block Safety, “Tell, Don’t Ask”, Using DataSources for your network-based *Service objects.

Apologies the audience participation isn’t well captured.

Think of the Smallest Possible Code Change, and Then Make It Smaller

mike@mikezornek.com (Mike Zornek) — Thu, 16 Apr 2015 03:23:25 +0000

I’m working on a client project right now. We do peer review of the code via pull requests. It works great, but the quality of the reviews you get are very dependent on the size of the pull request you make.

Take for example, one of my recent pull requests, which had the following git characteristics:

1,780 additions
1,618 subtractions
24 files changed

Not my largest pull request ever but still way larger than what I’d prefer. I got zero feedback. It was merged on first pass. Now take one I did the next day:

80 additions
1 subtraction
7 files changed

We had 10 conversation posts on this pull request, discussing three distinct recommendations and/or questions. Questions on things I was already doing for a few pull requests already but I guess slipped by.

I don’t blame the reviewer, I blame myself. It’s really hard to be detail focused when there is so much to review.

So keep those pull requests small and focused. You’ll get better feedback and you’ll probably get integrated faster too!

An “App Architecture” Kata

mike@mikezornek.com (Mike Zornek) — Mon, 24 Nov 2014 02:00:29 +0000

At the last Side Project Saturday CocoaHeads event I ran a special little exercise. Here was how I described it.

I’d like to run a little event, (maybe after lunch?) for anyone who wants to participate. Should take like 45-60m.

You will be presented with a mobile app idea. It’ll be fairly basic and we’ll list all of the behaviors we need and some we’d like in the future. You will then pair up with someone and pencil out how this could be architected. Each group will then present their app architecture and answer questions, accept feedback from the rest of the group.

From Wikipedia: A code kata is an exercise in programming which helps a programmer hone their skills through practice and repetition. The term was probably first coined by Dave Thomas, co-author of the book The Pragmatic Programmer, in a bow to the Japanese concept of kata in the martial arts.

App architecture is one of those things I’m always trying to improve so I thought it would be cool to see how other people would solve similar problems.

We had six people participate. We started with a brief explanation of the app we were going to sketch out an architecture for. Then, we broke up into pairs of two. After about 40 minutes we came back and showed the group what we came up with.

The one group ended up documenting behaviors per screen. They did a great job of documenting the little things that developers might look over as assumed behavior (which add up fast). It was pointed out that it’s also a great idea to document the things you will not be doing since there tends to be lots of great ideas during brainstorms but when you are planning a sprint of a version target you need to be clear about what’s in and what’s out.

The other two groups (including my own) were more visual, using tools like OmniGraffle to draw representation of models, controllers and services. There was some common separation of responsibilities with slight differences: the one group making an “APIStore” that combined the state and networking and another (mine) that favored separate “Network” and “Session” managers.

Some of the more high-end abstractions I introduced included a FormController that could take a Form model (that had say a collection of FormFields) which described the form at a model level and then through a FormController might be able to render the form on screen through a TableView for a generic representation or maybe through specific outlets to a custom layout. It could also handle things like input validation. True, this is overkill for our one simple login form but assuming this app might grow to contain edit person forms at some point it might not be too bad of an idea (and plus the whole purpose of this event is to discuss interesting ideas).

I also took the time to introduce a pattern thats been out for a while but is a recent addition to my personal toolkit, that being ViewModel. You can read more about MVVM on objc.io. In short it’s a great way to centralize the code you use to transform model objects for user interface purposes and keep that logic out of the model.

In conclusion, everyone who participated seemed to enjoy the exercise and I would encourage you to replicate it amongst your own peers. It’s still up for debate if “Side Project Saturday” is the best venue for such things as many who come have their own stuff to work.

Philly Craftsmanship

mike@mikezornek.com (Mike Zornek) — Sun, 03 Aug 2014 00:52:02 +0000

Software as Craft Philadelphia

A community of professionals dedicated to well-crafted software

Was very happy to attend the inaugural meeting of this group last week. Was a great mix of discussion and hands-on coding/pairing. Thanks to Promptworks for hosting.

During the discussions, the Software Craftsmanship North America conference (as well as its manifesto) were mentioned. You can find a bunch of the conference videos on the eighthlight vimeo channel. Seems like pretty interesting stuff.

In related news (since I think all hosts were in attendance at said meeting), I want to give a plug to the podcast Turing-Incomplete podcast. Finally starting to catch up on this Philly showcase of talent and really enjoying the discussions. Keep up the good work!

Focused Testing in Xcode

mike@mikezornek.com (Mike Zornek) — Mon, 27 Aug 2012 03:10:55 +0000

I’ve set a very informal goal to produce content for this blog on a daily basis. We’re not there yet, but before the night is lost, here is a quick Xcode tip I fell into today.

So I’m using RestKit in a client project. In this project we POST and PUT lots of records. RestKit does not currently have an option to, when serializing a record, include those record attributes which are nil as nulls in the resulting JSON. While there has been an ongoing ticket for this feature, my own release date is approaching and so I dug in this weekend to see what I could do.

As part of adding this code, I wanted to run and make additions to the RestKit test suite, but running the whole suite over and over as you are making very specific changes is a bit of a time waste. Here is my Xcode tip.

When working in an Xcode project that has lots of tests, you can temporarily setup Xcode to only run the tests you are working on by editing the schema. In the schema editor, look for the test action and from there you can expand the test target.

You’ll see checkboxes for each test file and they expand further for each test case. Check and uncheck to focus in on the tests you are working around. Hold down the Option key as you click on the checkboxes to turn them all on/off with a single click.

This can seriously speed up your editing cycle. Just make sure to switch them all back on (or do this change on a schema that isn’t shared in the repo) and verify that the full test suite passes before you commit your changes.

As for my feature, I think I have it working, but will let things settle down before I generate a nice pull request for the RestKit development branch.

Mike Zornek

A Few Good Memes

Personal Elixir Code Aesthetics

Whitespace between import and alias.

Alphabetically ordered alias declarations.

Avoiding multi-alias declarations.

(Generally) prefer multiline do/end functions.

Use consistent DSL layout in test modules.

Invest in test fixtures

Use tiny_maps to save horizontal line space in tests.

Compose code to prefer clean line breaks

Embrace pipelines with custom utility functions.

Be consistent between module names and filenames.

Write professional documentation.

Document your decisions.

Make sure each FIXME has an issue URL.

Avoid abbreviations and prefer expressiveness.

Words matter.

Craft typespecs to express your domain.

Document your dependencies.

Document and validate function options.

Compose PR titles for clarity and consistency.

Strive for database precision.

Notes about Technical Debt

What is technical debt?

Working towards a tech debt framework

Selling

Sprint planning and broken glass

Trust

Join us

Elixir Context Accessor Function: Which Return Type Do You Prefer?

The Curse of Test Fixtures

Elixir Style: Prefer Unnested Aliases

Style Recommendation

Improve the Clarity of Your Elixir Code Through Expressive and Consistent Language

Programming Terminology

Entity vs Value

Entity vs Row

Maps vs Structs vs (Ecto) Schemas

Create vs New vs Insert and Remove vs Delete

Get vs Fetch

List vs Array

Behavior vs Feature

App and Business Domain Consistency

Document Your App’s Custom Terminology

Authentication vs Authorization

Sign in vs Log in

Account vs User and Settings vs Preferences

Language I Try to Avoid

Bad Code and Code Smell

Video: Using Fixtures and Test Assets in Swift Unit Tests (9m)

Renaissance Man

Code Documentation

What is code documentation?

Why should I write documentation?

How do I write documentation?

Writing Guides

Resources

Counterarguments

How to Get Started?

Code Consistency with SwiftLint

What is SwiftLint?

Installation

SwiftLint In Action

Customizing the Rules

Related Projects

Conclusion

The README File

Core Components

Project Name and Branding

Project Status

Feature List

Installation and Getting Started

Development and Contribution

Deployment

Links

Licensing

Examples

Apple Radar Bug Report

New Series: Professional iOS Projects