First, Show Me The Code

Pssst... This post isn't about the code. It's about hiding preambles in posts about code. Use "Open The Story" below to see the actual narrative.

The Story

Open The Story

Now You See Me

I like getting straight to the code.

Having to parse a bunch of prose to find a code snippet burns tons of mental energy. It's friction that breaks my flow. Given I'm generally in the middle of figuring out how to solve a problem, it's a major frustration.

I don't mind the stories behind code. Learning the why behind a thing can be super interesting. I just don't want to have to plow through it to get to the how I'm after.

Previous Attempts

I've played around with putting code first. Usually in a TL;DR section. It always felt weird. Like there needs to be at least some padding before hitting the block.

Dropping the main body of text behind the code also felt off. There's a general order to posts. Flipping things around is off-putting.

I found myself cutting down on the story. Sometimes, deleting it all together.

The New Solution

So, I'm trying something new. The story is back up front, just closed by default. You see the code first. If you find it interesting, you can open the story after.

What's All This Then?

This post wouldn't have made much sense without a code sample. Figured the code that's switching the text from "Open The Story" to "Close The Story" is a good choice.

It makes for a bit of an odd transition to mention that at the end. That's just how examples go sometimes. Regardless, I hope you enjoy it,

-a

The Code

JavaScript

class DetailsOpenCloseWatcherTest {
  constructor () {
    this.addWatchers();
  }
  
  addWatchers() {
    const els = document.querySelectorAll("details");
    els.forEach((el) => {
      const summary = el.querySelector("summary");
      if (summary) {
        this.update(summary, el.open);
        el.addEventListener("toggle", (event) => {
          this.update.call(this, summary, event.target.open);
        });
      }
    });
  }

  update(el, state) {
    if (state === false) {
      el.innerHTML = el.innerHTML.replace(/^Close/, "Open");
    } else  {
      el.innerHTML = el.innerHTML.replace(/^Open/, "Close");
    }
  }
}


const watcher = new DetailsOpenCloseWatcherTest();

Quick Implementation

This post isn't really about the code. But, I'm not posting it elsewhere. So, here's the basics.

This came about to make the "Open The Story", "Close The Story" feature more clear. Without it, the text was always the same (e.g. I could only use "The Story". It appeared when the story was visible as well as when it was hidden).

I've played with it for like five minutes. I'm already a huge fan. Gonna throw it into production as soon as I'm finished this edit.

-a

-- end of line --

Endnotes

This reminds me a bunch of recipe sites. The standard joke about not needing a completely history of grandma's encounters with the neighbor's dog in order to see how to make scrambled eggs has the same vibe.

I strive to make my code examples both accurate and complete.

Seeing code snippets scattered throughout a post, then being told at the end you have to do assemble them yourself is maddening. I wonder if that's some of the appeal of AI generated code. You at least get a full block. Even if it doesn't actually work.

TBD on adding snippets of text before the actual code. My initial thought is that if the title is a clear enough description I might not add anything. We'll see how that evolves.

I expect there will be closing text after most code blocks posts. They'll act as wrap-ups. They can also give basic context at a glance.

The predecessor to this post covers how to keep details blocks open when pages reload. Something I built because I got tired of constantly having to reopen the sections of the bitty-js landing page every time I made a minor edit.

It's a better example of the idea here since it doesn't have to act as a meta-explanation as well.

bitty-js is a web component that adds reactivity to pages, btw.

You should totally check it out.