DEV Community: Gage

Stop Stressing Users OUT! 😳🙅🏽‍♀️

Gage — Fri, 07 May 2021 16:23:48 +0000

Lately I've been working on my project "Hyper Writer" which is supposed to help me to write more.

One of the ways it does this is by trying to convince you to write 750 words each day without editing.

This is great because it acts as a sort of "mind dump" that helps you get your thoughts out and find things that would be great to write about.

The problem is, I wasn't doing it.

At first I tried to introduce a sort of "streak calendar" which would color days you've written and leave the other ones a depressing gray color:

But lately when I pulled it up I just kind of felt this dread. I'm a busy parent of 3 small kids... I don't have a ton of time to write. Even 30 mins can be a big time commitment for me and often if life gets in the way I feel like a failure.

More positivity, less guilt

The answer of how to improve it came from an unexpected source. Trying to make the landing page.

The more I read and watched about marketing the more I realized an important principle:

Don't talk about the work they are going to have to do
talk about the benefits they are going to get

I know, sounds like "no duh!" but look at how much work my interface was implying that I do:

Now compare the new one:

Now I click it every day! Let's dive into this a bit more

Button Text

Before: 😰 Why would I want to WRITE TODAY'S BONE, that's just more work for me, it's daunting because I know I'm going to have to write 750 words

After: 🧘‍♀️"Unburden your mind" feels like such a relief! Of course I want to click that button!

Worry about Streaks after you succeed

Before: 😡 the streaks calendar creates an insta-guilt trip at the start of each day. You walk into the app and it says, "guess what! You're already behind again!"

After: 🤗 Hiding the chart till AFTER I succeed stops the instant guilt trip. Also, the message under the button tells you just 1 word is enough, but you know that when I start writing I'll write more than that.

Result

So maybe try making more changes towards calm and positivity and it see if it helps you too!

References

Don't come in "Guns-A-Blazing'"

Gage — Fri, 09 Apr 2021 02:11:06 +0000

Have you ever learned something that just blew your mind and goes against common knowledge or beliefs?

This recently happened to me when I realized, Single Page Apps (or SPAs for short) are actually way more expensive to build than traditional Server Rendered Multi-page apps (MPAs). When I realized this all I could think was, "I have to tell EVERYBODY! 😱" .

So what do I do? First step, make sure nobody's saying anything false on Twitter.

I quickly found a guy spreading the doctrine of, "Learn React + APIs" and sharing it with defenseless beginners. So I "set him straight" (typos and all 🙂🤦‍♂️)

I even tried to soften the blow with the 2nd comment, but it was still a blow after all.

His response was quite telling

I had basically just took a guy who was innocently trying to get followers and share some useful information with beginners and had attacked him. What the heck.

Made me realize my strategy wasn't effective, let alone nice.

Thing is when I walk into these types of conversations guns raised and ready to attack false ideals I usually just catch innocent bystanders in the crossfire (sorry Vlad).

Let's try listening

I recently posted a simple question on dev.to asking why people chose to make SPAs instead of traditional Server Rendered apps. You already know I'm super biased on the subject, but at least I was also more curious now.

I got a response from a nice person about how they built their app using AWS lambda functions, Next.js, Amazon SQS, and more. It sounded ridiculous on the surface, why would they subject themselves so much vendor lock in on top of the complexity of a normal SPA when normal Postgres, Redis, and some nice MVC framework would have got the job done?

Luckily instead I decided to just listen and ask questions to understand why they thought the way they did.

We had a long back and forth conversation and you know what happened? Their arguments made perfect sense!

They were able to not have to worry about any server upgrades and didn't have to shard their database anymore! Not only that they didn't have to worry about where their server was running, but it would also just run at the nearest data center. What about local development? Well, there's some local DB mocking for that. Sure there was some vendor lock-in but they traded off a lot of the effort normally being put into keeping a traditional app up and running. Huh 🤔.

After all this questioning I was tempted to open my mouth again, still sounded harder than how I would build it, but then realized... I had never made an app this way before! I had NO experience, zero, zilch, nada.

I felt like before I had so much experience, having seen both sides (SPA and MPA), well it turns out there was another side 🤯, even a whole spectrum of choices that I've never even tried.

Maybe I'm right, maybe he is, doesn't really matter. I learned a lot from putting down my "guns of justice" down and talking around a campfire, and I think you could too.

(Photo by Andreas Wagner on Unsplash)

DON'T FORGET TO LIKE COMMENT AND SUBSCRIBE, RING THAT BELL ICON SO YOU CAN KNOW WHEN ALL MY NEW BLOG POSTS COME OUT.

J/K, but you can leave a comment if you want.

Peace ✌️.

Gage

P.S: My coworker shared this with me and I think it relates

Why did you choose the SPA architecure?

Gage — Tue, 06 Apr 2021 23:12:23 +0000

Single Page Apps (SPA) + APIs seem to be the default nowadays over more traditional Multi-page apps Ruby on Rails / PHP type server-rendered HTML.

I want to write an article about why I think MPAs are still a valid a nice way to make applications but I'm not sure where people are at right now besides they seem to be picking SPAs almost exclusively.

Was React + APIs the only thing you learned?
Why did you pick SPAs personally?
Why did your company pick a SPA if they did?
Why do you think SPAs became the default for most orgs? Or do you think they aren't?

If you have no idea what the difference between a SPA or MPA is then I am curious about that as well (I just want to hear from you guys I guess 🤗).

Cheers!

Photo by Javier Allegue Barros on Unsplash

Published is better than perfect

Gage — Tue, 06 Apr 2021 15:58:54 +0000

I'm kind of a perfectionist. I love to read a blog post that's been crafted and polished over weeks and weeks of work like Paul Graham's essays.

But I also have a super bad habit of not actually publishing anything. I have tons of drafts, thousands of notes, all of them are just not good enough. I'm afraid that people will make fun of my ideas or poke holes in them that if only I poured in a few more hours into them I could have made it all airtight.

However, when I was watching a video about how a man learned Italian way faster than most people can. Most people get hung up in following ridged grammar rules but often end up years in not really being fluent.

What he decided to do instead was just learn the most common words of the language (the most useful ones) and just start stringing them together in the ways that most make sense to him. Sure he looks like a total "noob" to any native speaker but that's not the point. He didn't get hung up on hiding his talking till he was, "ready".

He made a good argument for this:

language is not like math. Math has right and wrong answers.

If my son says, "I ated a Apple" I'm not going to correct him. He said words and I understood them. That's all part of the expressive human experience.

Basically, so long as you can relay your message clear enough you're communicating!

I think the same applies to writing. You may not be good at it (I know I'm not) but if you're not sharing you're not learning.

Some people even use publishing as a perfecting process:

...with an annealing policy will usually improve in quality after publication. More exposure = More "heat" = More quality.

I really like this idea. Nothing is going to ever be perfect unless you put it into the real world. There's no shame in modifying your post after you post it! Once it's out there you'll be so much more motivated to fix the problems with it 🙃. This post had 10 grammar errors that I fixed a day after writing it.

So just freakin' write it and push publish.

Published is better than perfect.

Gage

PS*: If it makes you feel any better just take any popular blogger and stick it into Grammarly, you'll see their post isn't perfect either* 😅.

Photo by Bank Phrom on Unsplash

Saner apps with the Facade Pattern

Gage — Mon, 11 Nov 2019 17:00:00 +0000

One day the trunk of my 2005 Toyota Camry got stuck. It was an old car, but had been reliable in the past, so it was surprising. My wife showed me how the trunk made a grinding sound when it opened and closed. I discovered the trunk had become detached from this long metal bar that acted as the spring. This metal bar made the trunk float up when you opened it and held it open when you were getting things out. Now it was broken. I attempted, but was unable to fix it. Now it had become a guillotine for hands. Not only that, but it was also super heavy to lift—far more than I would have assumed.

Cars are a great example of good abstraction. Their interface is simple, yet they are complex on the inside. The trunk appeared to be the simplest part of the car, yet it was complex when I looked at how it worked. It hid the weight of the trunk from me for years. The trunk would float up, and that's all I knew.

The power of an Interface

The idea of an "interface" (also called an "API") exists in software as well. This is because, like cars, software tends to be complex on the inside, but should provide a simple interface on the outside.

Interfaces hide complexity

The best interfaces hide complexity so the user should never need to "look under the hood" to know how to drive. Otherwise, the abstraction would be unhelpful, and you would have to be an expert mechanic to even use the thing. This is not what you want.

A car's steering wheel is this way. You could say: "please rotate the tire-rod mover counter-clockwise 20 degrees," but you don't have to. You can just say: "turn left here!"

Interfaces Unify

The other cool part of an interface is it's "combining power" - meaning it can help bring many different parts of a machine together into one. For instance, both the steering wheel and the brakes are completely different parts of the car. Even the stereo and the heat are right next to each other in the interface, yet are completely separate subsystems. The interface of the car combines them into a seamless interface.

In a software context, imagine you're making a new API endpoint for your microservice. You might get your data from joining 4 different tables, then doing some in-memory calculation. Not only that, but you mix that with some data from an external API. That would be very complex if another person had to understand all that and do it themselves. But with a nice interface, the user will never be the wiser. You could even refactor it in the future to make it simpler, and nobody's code would be broken (I can dream can't I?).

The Facade Pattern

There are many ways to create interfaces in different programming languages. One way is to make some of the functions private, so that other ones operate as the public API. In Elixir, you can change a function to be private (unable to be accessed by other files) by just a bit of syntax—defp <function name>, instead of def <function name> (note the p). For example:

defmodule MyApp.Example do

 # I'm public
 def public_add(a, b) do
 private_add(a,b)
 end

 # I'm a private, helper function
 defp private_add(a, b) do
 a + b
 end
end

*(NOTE: I'm going to use Elixir for all my examples in this article, because that's the primary backend language we use at Podium, but, this could be used in any language. So long as you understand the example above, you should be able to follow the rest of the article)*

These constructs only work on a file level. But what happens if you want to "hide" a lot of files under one interface? This is where the Facade pattern comes into play.

The Facade Pattern is a design pattern¹ where a module/class provides a simplified interface to a larger body of code.

That's cool, but how do we implement that in Elixir?

File structure

To start, we organize things the way Phoenix (the web framework for Elixir) recommends — using the "context" pattern. If you're unfamiliar, never fear, it's the pattern I'm going to describe in this article with small additions, primarily the presence of the Facade file. If you're curious you can read about it in the Phoenix docs.

All contexts have a name; which, in our example below, there is a widgets and an orgs context.

These both have a file outside their folder with the same name (widgets.ex and orgs.ex). These two files are the facades. They act as the Public API to their sub-modules in the widgets/ and orgs/ folders, respectively.

lib
├── your_app_web/
└── your_app/
 ├── widgets.ex (<-- facade)
 ├── widgets/ (<-- context folder)
 │ └── private/ (<-- Widgets' private modules)
 │ ├── create.ex (<-- private function file)
 │ └── update.ex (<-- private function file)
 │
 ├── orgs.ex (<-- facade)
 └── orgs/ (<-- context folder)
 └── private/ (<-- Orgs' private modules)
 └── whitelist.ex (<-- private function file)

Now let's talk about each of these files, in turn, to understand their purpose more and the rules that govern them.

The Facade File (Public API)

Facade files adhere to the following rules:

They Don't contain any defs, only defdelegates. (See the defdelegate docs, also explained below)
They are the main place of documentation for the context's API.
Named plurally (Orgs not Org). This allows the name Org to be used for a database struct. It's also the convention that Phoenix uses.
Each defdelegate should have docs of why it exists, what it does, and a working example. (Doctests helps with the working part)

Example of a context's facade file:

defmodule YourApp.Widgets do
 @moduledoc """
 A widget is a unit of sale...
 """
 alias YourApp.Widgets.Private.{
 Create,
 Update,
 }

 @doc """
 Create a widget in the database. Any configuration options not specified will
 be provided with defaults.

 # Example

 iex> {:ok, id} = Widgets.create()
 """
 defdelegate create(config \\ %{}), to: Create, as: :call

 @doc """
 Update a widget's configuration options. If the update is a no-op it will return an error.

 # Example

 iex> {:ok, id} = Widgets.create()
 iex> Widgets.update(id, color: "red")
 """
 defdelegate update(id, config), to: Update, as: :call
end

The defdelegate might be unfamiliar to you, so let me explain it. It's a part of the Elixir programming language, although not well known. I think it's best explained with an example.

This:

defdelegate update(id, config),
 to: Update,
 as: :call

is the same as this:

# 🚫 Don't do this, just an example
def update(id, config) do
 Update.call(id, config)
end

Private Function Files

Private function files adhere to the following rules:

Their filename matches the name of the function they represent.
They have a single exposed function named call at the top of the module.
They must never be accessed directly, but rather through the facade.
Should have @moduledoc false at the top so they are hidden from the generated documentation.

Example of a private function file:

defmodule YourApp.Widgets.Private.Create do
 @moduledoc false

 # this is the only public function
 def call(config \\ %{}) do
 # do stuff
 end

 defp helper_function() do
 # ...
 end
end

What does Private mean?

Public vs Private here means that different contexts (Widgets and Orgs) should never reference the other's private modules directly. For example, if widgets/private/create.ex, needs access the functionality in orgs/private/whitelist.ex it should go through the facade Orgs.whitelist() rather than going directly to Orgs.Private.Whitelist.call().

If it looks like this, you're doing it wrong:

defmodule YourApp.Widgets.Private.Create do
 # ❌ BAD, this has a `Private` in the alias, and it's not in the same context.
 alias YourApp.Orgs.Private.Whitelist

 def call() do
 # 🚩 Red flag, shouldn't see `.call` in your code
 Whitelist.call()
 end
end

Example of doing it right:

defmodule YourApp.Widgets.Private.Create do
 # ✅ Good, you only alias the facade
 alias YourApp.Orgs

 def call() do
 # ✅ Good no `.call` in the your code
 Orgs.whitelist()
 end
end

If you're wondering about why I have an extra level of nesting using the private/ folder and the .Private. in the module name, the reason is, it will make it more obvious that you're doing things wrong because you'll see Private in your alias ... line and, hopefully, rethink your decisions. I even dream that someday I'll write my own linting rule to look for people aliasing private modules, but haven't done it yet.

Another benefit to nesting under the Private is that auto-complete will work better in iex and VSCode, because you'll see the right functions first, rather than the modules (modules are usually listed first for some reason).

Also note that it's fine to have files that aren't listed in the context, but are in the Private folder. I often have a private/util.ex file to share functionality between
the different private modules that are all in the same folder.

10% pattern 90% design

Although this pattern has helped me a lot in my projects, I will say that the main thing it did for me is force me to think about my API's.
Because when you have one file dedicated to the interface of your sub-modules, it's a lot easier to spot functions that do the same thing,
to spot naming inconsistencies, and it becomes a lot more obvious when something doesn't have a @doc at the top of the function.

Despite this, if you don't care about your API's, it's not going to make any difference.

"If your application is difficult to use from iex* your APIs are probably wrong"

~ Aaron Renner

Some recommendations would be:

The first argument is the id of the context (where it makes sense). For instance, do Widget.update(id, settings) not Widget.update(settings, id)
Don't stutter in your APIs, meaning, do Widget.create() not Widget.create_widget().
Make the names work well together and are guessable. For instance all functions that get something start with get_. I find it useful to group functions this way due to autocomplete. I can always start typing Widget.get_... and then it will tell me the different ways I can do it. Some style guides hate this, but I personally find it useful.
Don't pass in arguments that you could get from the database. For instance, don't pass in Org.get_widgets(id, widget_ids) just because the front-end happens to have those ids. It's better to do Org.get_widgets(id) even if it's a little slower. This is especially important because of security (it's easy to forget to filter out ones that aren't owned by the user).

FAQs

1. Isn't it a bit crazy to have NO `def`s in the Facade? Why can't we move them out into a new file when they get too big?

The main reason I made a rule about only using defdelegate as opposed to normal defs is the Facade is public. When I say public, think "town square" or "neighborhood park". Everybody owns it and everyone needs to take care of it. Its main purpose is to be a sort of crossroads into other modules.

While this may seem harmless, over time, it's very likely people will put all their code into this file until it becomes thousands of lines long. A "Tragedy of the Commons" occurs:

The tragedy of the commons is a situation in a shared-resource system where individual users, acting independently according to their self-interest, behave contrary to the common good of all users by depleting or spoiling the shared resource through their collective action.
~ Wikipedia

When everybody is trying to get their ticket done, they are aren't too concerned with making sure the facade file stays clean, especially if nobody else is. This leads to everyone adding their 1 line. Nobody is incentivized to pull out the function into a new file, and so nobody does.

This gets even worse the more helper functions (namely defps) you get in this file, because it's unclear which ones are reused and which ones are there to make some other function shorter.

Pulling the implementation into a new function file doesn't quite solve the tragedy of the commons problem, but it limits its effect.

So keep facade files to @docss, @specs and defdelegates. You'll be happier if you do. While you're at it, make sure there's a good @moduledoc.

Also, it's important to always remember to design for a nice experience using your app via the REPL (iex). Why? Because REPLs It allows you to see things really work without the mocking that you would have to do in tests. I also find when you are forced to type everything into a REPL the really long function names, and complex argument lists start to become a lot more apparent.

2. Doesn't this mean it takes more jumps to get to the right file?

Yeah, it does if you're following the references directly. However, I can take advantage of the fact that function files are named the same as the function they represent and just use a file finder as I have in VSCode with ⌘-P (on a Mac, probably CTRL-P on Windows?). So if I see Org.whitelist(), I know if I do ⌘-P and start typing whitelist..., this will be quite a bit faster than digging through a huge file with all the functions in it, don't you think?

3. This seems like too much work. How can we make it easier?

I'm glad you asked (you didn't 😂, but just go with it). Code Generators!

Code Generators

One barrier to implementing this pattern is the fact that it's more work. Namely in modifying the facade file and creating a new file every time you want to put a function on the context, rather than doing def in an existing file.

To fix this problem, I made a mix command (mix gen.fn) to generate new function files and update existing facade and function files. This command even generates a failing test to hint you towards doing TDD. Not to mention a few # TODO:... comments to make credo force you to write some documentation.

It works like this:

λ ~/lib/your_app/ mix gen.fn "Email.feedback_email_contents(user_metadata, orgs, feedback)"

./lib/your_app/email.ex doesn't exist, creating...
File wrote to: ./lib/your_app/email.ex
File wrote to: ./lib/your_app/email/feedback_email_contents.ex
File wrote to: ./test/your_app/email/feedback_email_contents_test.exs
File modified: ./lib/your_app/email.ex

Here's the mix task. It's not a super clean implementation, but might serve you as a thing that you could change to suit your needs.

Concrete benefits

Some of the most concrete benefits my team and I have experienced are:

Functions make more sense in context. It's easier to know that I'm creating a widget when I do Widgets.create() rather than Create.call.
Easier to remember what to alias. I can alias Widget instead of the three or four functions I need from it.
Because of the previous point, it is super easy to use this API in IEx.
Nothing is tied to the API endpoints, so it's easy to write a mix task that does the same thing.
People write documentation! Crazy!
Because the public functions are reusable, they get reused! I've even implemented new functions out existing ones, which feels good.
The facade file looks very clean, which helps people feel like our app is something we take care of. No broken windows.

Conclusion

I hope you'll try this pattern out, it has helped me find and reuse code. I no longer feel like I'm digging through the guts of my car to just understand how to drive it.

Footnotes

Software design pattern, if you're unfamiliar, are essentially templates of how to layout your code. They usually aren't embodied in a library although maybe in some cases they could be. For my purposes I'm not going to use any libraries, only using a bit of code that generates the file structure that I'm looking for that I'll include at the end.

Hi, I'm Gage

Gage — Thu, 23 Mar 2017 14:17:16 +0000

I have been coding since high school.

You can find me on GitHub as justgage

I work for Podium

I mostly program in these languages: Elixir, Ruby, JavaScript, and Elm.

I am currently learning more about Elm.

Nice to meet you!