De_Magicking Words

December - 2020

The wonderful KatieKodes wrote a piece on making her minimum viable build tutorials. The process includes staying as far away as possible from the magic keywords inherent in site generators, CMSs, and systems of all types. Words like:

  • slug
  • permalink
  • url
  • post
  • etc...

Words which might be fine in one system, but cause your site to go up in a puff of smoke in another. This got me thinking of a Advent of code snippet of python I saw from Ali Spittel.

Most tutorials use the generic variable name file for reading/writing examples. Something like:

with open('input.txt', 'r') as file:
    # do something with `file`

That's always bugged me. First, I try to make meaningful names. Second, file feels like it should be a reserved word. It's not, but it feels like it should be. Anyways, what she did was preface it with an underscore.

with open('input.txt', 'r') as _file:
    # do something with `_file`

I love it.

In python, the leading underscore is used to let developers know the variable is meant for internal use. That's great and all, but I love the visual distinction it makes about not being a keyword.

Combining that and Katie's piece got me thinking about using underscores to de-magic keywords. Instead of using leading underscores (which have implicit meaning in Python), I was thinking of a trailing ones. Turns out, this is not an original thought. It's explicitly listed in Python's PEP 8 style guide.

But, after playing with them, I'm not sure I like the look:

  • slug_
  • permalink_
  • url_
  • post_

Feels like I didn't finish writing the variable name. It also feels like there's meaning associated with it. Like it's a type of keyword on it's own. Not unreasonable since double underscores in things like __init__ are meaningful.

So, what if we use the underscore, but in a different place? What if we put it after the first character? We get something like this:

  • s_lug
  • p_ermalink
  • u_rl
  • p_ost

Or, maybe before the last one:

  • slu_g
  • permalin_k
  • ur_l
  • pos_t

Of course, you could also do every letter:

  • s_l_u_g
  • p_e_r_m_a_l_i_n_k
  • u_r_l
  • p_o_s_t

That looks nicer, but it's super tedious to type.

So, what about prefacing with a letter:

  • a_slug
  • a_permalink
  • a_url
  • a_post

Using a even provides a little meaning. Or, at least, it's not inaccurate even if it's redundant from a naming perspective.

Or, maybe, use the:

  • the_slug
  • the_permalink
  • the_url
  • the_post

I really like that one.

Whatever the case, I hadn't thought about these options before.

Definitely something to play with.