DEV Community: Shimin Zhang

My Favorite Books of 2022

Shimin Zhang — Mon, 06 Feb 2023 06:02:35 +0000

One of my 2022 goals was sticking to a consistent nonfiction reading habit of 1 hour a day, 7 days a week. While I only mostly succeeded, I ended the year with a 33-book-long book list. Here are my favorites books of last year, along with a short review and a key insight.

Every Layout by Heydon Pickering and Andy Bell

Big Idea : Layout should be about the relationship between elements and how they change, not the elements themselves.

A great little book that changed the way I think about web layout and layout separation of concerns when it comes. It also contains some great information about the inner workings of the CSS layout spec that are often missed by developers who find CSS mystifying. The bulk of the book contains a series of fundamental layout relationships along with how to implement them in multiple web technologies. Learning these fundamental layouts is a great way to break down complex designs into modular layout components.

Fun fact, I used the layout patterns in the book in my day job in the form of CSS layout utilities.

The Mom Test by Rob Fitzpatrick

Big Idea: Don't ask users about future potential solutions. Ask about their past experiences and specific pains.

How often have you gotten enthusiastic responses about the latest feature you are in love with, only to release it and find it hardly gets used? The Mom Test help you conduct better customer interviews and separate the problems users don't care enough to fix from the features that solve real pain points they are willing to commit to today.

Philosophy of Software Design by John Ousterhout

Big Idea : Good software design is about dealing with the fundamental nature of complexity and our need for information hiding.

This is one of my favorite books on software development – it attempts to build a philosophical framework for what it means to write good software. From the definition of complexity to tactical red flags like 'when the same knowledge is used in multiple places'. While I don't agree with all of the book's recommendations, I wish I had this book earlier in my career to provide a framework for evaluating software design principles.

Designing Data-Intensive Applications by Martin Klepperman

Big Idea : Build fault-tolerant systems by finding general-purpose abstractions with good guarantees then build everything on those guarantees.

It's hard to pin down a single big idea for this book since it is chock full of them. While I mostly work on the front end, this book is a must-read for anyone interested in building and understanding scalable applications. This is one of those books that can never be replaced by blog posts or StackOverflow answers, it builds a strong mental shelf of database topics and how they relate to each other, something that you can refer back to for years to come.

Badass: Making Users Awesome by Kathy Sierra

Big Idea : Users don't evangelize to their friends because they like the product but because they like their friends.

This book is packed full of insights on what it means to build a product so good that your users will market it for you. I wish more software are built with these principles in mind – instead of the addiction-based model that is so common these days. This book made me much more mindful of the increase in cognitive resources any new features would cause.

Reactive Design Pattern by Roland Kuhn with Brian Hanafee and Jamie Allen

Big Idea : Nondeterminism is a necessary evil due to hardware limitations.

Another really good book on creating scalable and fault-tolerant applications, this time through the use of functional reactive programming. While a lot of the message-passing / functional programming paradigms are familiar to AngularJS developers, I found the fault tolerance and recovery patterns very insightful – reminds me of Release It! by Michael T. Nygard.

The Timeless Way of Building by Christopher Alexander

Big Idea: The central task of 'architecture' is the creation of a single, shared, evolving, pattern language that everyone contributes to, and everyone can use.

As someone with 'architect' in my job title, I occasionally find myself reading about architecture to try and live up to my role. Christopher Alexander coined the term design patterns in the Timeless Way of Building, and I found the rest of the book equally applicable to the art of software. A long-lasting piece of software -- like a medieval village – is a living thing, and its never-ending stream of maintenance and repairs is what gives it its final shape.

A particular story from the book has not left my mind since the initial reading :

Suppose that I am trying to make a table for the blackbirds in my garden. In winter, when the snow is on the ground, and the blackbirds are short of food, I will put food out for them on the table. So I build the table; and dream about the clusters of blackbirds which will come flocking to the table in the snow. But it is not so easy to build a table that will really work. The birds follow their own laws; and if I don’t understand them, they just won’t come. If I put the table too low, the birds won’t fly down to it. If it is too high in the air, or too exposed, the wind won’t let them settle on it. If it is near a laundry line, blowing in the wind, they will be frightened by the moving line. Most of the places where I put the table actually don’t work. I slowly learn that blackbirds have a million subtle forces guiding the in their behavior. If I don’t understand these forces, there is simply nothing I can do to make the table come to life. So long as the placing of the table is inexact, my image of the blackbirds flocked around the table eating is just wishful thinking.

I hope we can all chase fewer software fads and learn more about blackbirds in 2023.

Javascript readability vs performance: a false tradeoff

Shimin Zhang — Fri, 15 Jul 2022 15:08:23 +0000

Have you ever come across a piece of "clever" Javascript code that causes you to slow down and concentrate a little harder in order to digest it?

"Prefer readability over premature optimization" is a popular developer mantra, but the mantra also implies that the two are mutually exclusive. Does this assumption actually hold true when we are dealing with hard-to-parse one-liners?

Here's an example of a "clever" piece of code, a one-line solution to the FizzBuzz problem (taken from this medium post):

 function oneLineFizBuzz (n) {
    return ((n % 3 ? '' : 'fizz') + (n % 5 ? '' : 'buzz') || n);
}

Sure, you have to squint a little and think through the use case where n is divisible by both 3 and 5, and you also have to remember that an empty string evaluates to a falsy value in Javascript, but at least it's fast right?

For comparison's sake, let's also create a much more straightforward version of the FizzBuzz solution:

function clearFizzBuzz (n) {
    let result;
    const div3 = n % 3 === 0;
    const div5 = n % 5 === 0;
    if (div3 && div5) {
        result = 'fizzbuzz';
    } else if (div3) {
        result = 'fizz';
    } else if (div5) {
        result = 'buzz';
    } else {
        result = n;
    }
    return result;
}

The second solution is clearly easier to read and reason about, but is it slower than the one-line version? And if so, by how much?

By the end of the post, you'll see that because most of our JS code runs on highly optimized engines, performance and readability are not mortal enemies. In fact, readable Javascript is frequently the same as performant Javascript.

Benchmarking Our Functions

Looking at our two functions, the clear version contains two more constant assignments (div3, div5) and one more branching operation (div3&&div5). It should in theory be slower.

To make sure, let's run some experiments using the benchmark file from Surma's Is WebAssembly magic performance pixie dust? post (gist). We'll run each function for integers from 1 to 10e5 for 10 iterations and average the results. We'll also run 10 iterations before recording results, allowing the V8 engine to warm up and optimize the two functions:

const ITERATIONS = 10;
const oneLineResults = benchmark({
  run() {
    for (let i = 1; i < 10e5; i++) {
      oneLineFizBuzz(i);
    }
  },
  numWarmup: 10,
  numIterations: ITERATIONS
});
print('one line version result:', oneLineResults.average);

Here's our result running the testing code with NodeJS:

one line version result: 4.6
clear version result: 2.7

The more verbose version is significantly faster. Huh, what gives?

V8 Bytecode

To get a better understanding of why our clever one-liner FizzBuzz solution is slower, we need to take a look at how V8 works. V8 is the Javascript engine that powers NodeJS, you can directly download a binary version of the engine either via JSVU instead of compiling locally.

The results below are from v8-debug-10.4.132 on my local Linux 64-bit system.

Here's a diagram of how V8 processes our Javascript source code:

_Note: this diagram is out of date, the V8 engine v10.4 no longer uses Crankshaft and instead has two additional optimizers before TurboFan – Sparkplug and Maglev. _

On engine start, V8 first parses the JS code into its AST, then the Ignition interpreter translates the AST into platform-independent V8 Bytecode before passing it on to additional optimizing compilers. Its the optimizers' job to turn the platform-independent bytecode into platform-specific machine optimized code.

Here's what the Bytecode of our one-liner FizzBuzz function looks like:

[generated bytecode for function: oneLineFizBuzz (0x12ea00253ad9 <SharedFunctionInfo oneLineFizBuzz>)]
Bytecode length: 35
Parameter count 2
Register count 1
Frame size 8
Bytecode age: 0
         0x12ea00253d76 @ 0 : 0b 03 Ldar a0
         0x12ea00253d78 @ 2 : 49 03 01 ModSmi [3], [1]
         0x12ea00253d7b @ 5 : 97 06 JumpIfToBooleanFalse [6] (0x12ea00253d81 @ 11)
         0x12ea00253d7d @ 7 : 13 00 LdaConstant [0]
...
         0x12ea00253d94 @ 30 : 96 04 JumpIfToBooleanTrue [4] (0x12ea00253d98 @ 34)
         0x12ea00253d96 @ 32 : 0b 03 Ldar a0
         0x12ea00253d98 @ 34 : a9 Return

You can generate function bytecode by running the debug-v8 engine with the flag --print-bytecode.

And as suspected, the Bytecode of our clearFizzBuzz the function is longer than its one-liner counterpart (note the length of 63 vs 35 for oneLineFizzBuzz).

[generated bytecode for function: clearFizzBuzz (0x12ea00253b11 <SharedFunctionInfo clearFizzBuzz>)]
Bytecode length: 63
Parameter count 2
Register count 4
Frame size 32
Bytecode age: 0
         0x12ea00253e1e @ 0 : 0e LdaUndefined 
         0x12ea00253e1f @ 1 : c4 Star0 
...

In fact, if we run our benchmark test without using any of V8's optimizers, the one-liner version is indeed faster – though not by much.

one line version result: 3948.4
clear version result: 4085.8

V8 Optimized Javascript

The most surprising thing about our previous result is not how similar the function performances are. It's the fact that TurboFan optimization gave us a 1000-fold increase in execution speed.

As mentioned earlier, once a piece of JS code is invoked multiple times, V8's TurboFan optimizer kicks in and produces an optimized version of our functions. You can view the optimized code via V8's --print-opt-code flag.

Here are the first few lines of our optimized clear function:

optimization_id = 0
source_position = 135
kind = TURBOFAN
name = clearFizzBuzz
stack_slots = 6
compiler = turbofan
address = 0x7f88c0084001

Instructions (size = 480)
0x7f88c0084040 0 488d1df9ffffff REX.W leaq rbx,[rip+0xfffffff9]
...

versus our one-line function:

optimization_id = 1
source_position = 31
kind = TURBOFAN
name = oneLineFizBuzz
stack_slots = 6
compiler = turbofan
address = 0x7f88c0084241

Instructions (size = 592)
0x7f88c0084280 0 488d1df9ffffff REX.W leaq rbx,[rip+0xfffffff9]
...

The important bit here is the instruction size. Our one-liner FizzBuzz solution has an instruction size of 592 while the readable variation is only 480 instructions long.

While both our intuition and the V8 bytecode informed us the one-liner function should be faster, the optimized TurboFan result is the reverse.

While I did not perform additional testing to confirm exactly why our 'clever' FizzBuzz solution is slower in practice. Though I suspect the culprit is the string concatenation that must be done on every iteration that slows it down.

Takeaways

I hope this post has convinced you that code readability and performance are not mutually exclusive — at least not in the case of Javascript running on a highly optimized compiler.

So next time you see a piece of clever code in an MR that makes you pause and squint, point out that it can be written more clearly – and potentially without any performance penalties.

And next time you are tempted to write something clever and super concise, consider rewriting it for readability and for performance.

Thanks for reading this far. As always, if you found this post helpful, please share it with others. You may also be interested in learning about Troubleshooting Javascript memory leaks or How to measure web performance with the Navigation TIming API.

Additional Readings

Franziska Hinkelmann's excellent Understanding V8's Bytecode
Matt Zeunert's Compiling V8 and Viewing the assembly code it generates
V8 Blog's Sparkplug — a non-optimizing JavaScript compiler, Firing up the Ignition interpreter
An Overview of the TurboFan Compiler

Troubleshooting a JavaScript memory leak

Shimin Zhang — Fri, 17 Jun 2022 18:15:15 +0000

I got a chance to debug an app memory leak issue this week, when I took a heap snapshot in Chrome it dawned on me:

What the heck am I looking for?

Should I be sorting heap objects by distance, shallow size, or retained size?

JS Garbage Collection

JavsScript memory is managed automatically, meaning the JS engine's garbage collector releases heap memory automatically when they are no longer in use.

All modern web browsers (i.e. not IE) use some variation of the mark-and-sweep algorithm to determine which heap objects are safe for garbage collection (GC). The algorithm has two phases:

Marking phase : Starting from a root object, recursively traverse all heap objects referenced by the root GC node and mark them as in-use.
Sweeping phase : Iteratively visit all objects in the heap and release any that are not marked as in-use.

This is a simplified description of the V8 GC process. In actuality, the Chrome GC keeps heap objects in multiple categories bucked by their generation and incrementally garbage collects them.

The distance column in the heap snapshot screenshot above indicates the reference distance between an object and the GC root. A memory leak occurs when an object that otherwise should be garbage collected is marked as in-use by the marking phase of the algorithm – meaning some other object is unintentionally holding its reference.

Setting up

The heap snapshot of a completely empty webpage still contains a significant amount of objects in its heap. So let's set up a test example to better monitor our heap usage using Chrome's built-in snapshot comparison function:

<html>
<head>
  <script>
    var memBuffer;
    function start() {
      memBuffer = { 
          value: new ArrayBuffer(1000)
      };
    }
  </script>
</head>
<body>
  <button onclick="start()">start</button>
</body>
</html>

Note that we had to declare the memBuffer variable at the global scope to prevent the object from being garbage collected once the start function finishes execution. This is our memory leak into the global scope.

To use the snapshot comparison feature, we first take a snapshot of the page on page load, then click on the start button to allocate additional memory to our memBuffer object. We can then view new objects allocated between Snapshot 1 and 2 and filter for our new ArrayBuffer.

Shallow vs Retained Size

Once we've filtered for new JSArrayBufferData type heap objects, we see it has been added to the heap at 1kb for both shallow and retained sizes.

The retainer path provides us with details on the path that connects our buffer to the garbage collector root. GR root -> Window Object -> memBuffer object -> value key -> memory buffer for a total distance of 4. In Firefox, we can pull up the same information under the dominators view, although the exact object size and graph shape differ slightly due to implementation differences. FF also gives us a nice retaining path chart.

Going back to the value key in Chrome's retained size column, we see that 16b is the size of pointers used to keep track of key-value reference while the 1188b retained size includes the buffer object memory that will be freed when the value key is deleted.

In other words, we should look at the retained size column when looking at heap snapshots, it determines the amount of memory that will be released when an object is garbage collected.

To show the retained / shallow size difference, let's move our ArrayBuffer outside of the object instantiation and establish a global reference to it.

    var memBuffer;
    var ab = new ArrayBuffer(1000);
    function start() {
      memBuffer = { 
          value: ab
      };
    }

Running the test again, we see the value key's retained size has reduced from 1188b to only 124b. By adding another reference path to our ArrayByffer from GC root, the GC can no longer release the entire 1kb if our value key is deleted.

Going back to Firefox, we see an updated retaining path graph with the alternate path to our ArrayBuffer through the ab variable. Now there are two paths from the GC root to our ArrayBuffer.

In graph theory terms, a node x is said to dominate another node y if every path from the root node to y must pass through x. The retainer size of a heap object is the size of all objects that it dominates. In the first example, the memBuffer object is a dominator for the ArrayBuffer while in the second example it is the Window object.

In summary, when troubleshooting memory issues:

Use the snapshot comparison functionality to narrow your search down to newly created heap objects.
Look for heap objects with a large retained size that should be garbage collected.
To determine whether an object should be garbage collected, check its retainer path and examine reference validity.
Some common memory leak issues are easy to resolve, if you see signs for detached elements, detached element event listeners, and large global cache objects, consider removing their dominator references.

I hope that was helpful! If you like the post, please share it with others. You may also be interested in learning about how to measure web performance with Navigation Timing API or how to use CSS custom properties to create style API.

3 useful CSS properties to customize your web interactions

Shimin Zhang — Fri, 10 Jun 2022 21:03:19 +0000

A CSS complaint I often see online — one that I largely agree with — is there are too many properties to learn. After learning the basics, it feels like you are then asked to 'memorize the rest of the dictionary'.

Like building a vocabulary, it's easier to add to your CSS knowledge slowly over time than reading the entire spec over a weekend. Today, I want to share 3 of my favorite "new to me" CSS properties from the last year.

user-select

There are few things more frustrating than site owners disabled text selection with user-select: none;. This is usually done with the intent of copy-prevention. Doing so not only violates web conventions but it doesn't even work since one can always access the HTML directly.

user-select: none is not what I want to focus on. I want to mention the lesser-known value: user-select: all;. The all value causes any selection inside the element to select all element text, even with a single click.

This means you can use HTML elements as semantic 'highlight sections' to group related content together. Some interesting use-cases:

<address> it makes sense to wrap an entire name/address /telephone in a single copy section. So the user can copy an entire address in a rental listing into Google Maps to lookup commute distance.
<code> you can wrap sections of code in its own <div> to make copy/pasting easier.

Like all techniques, user-select: all involves some tradeoff, it can make common copy/highlights tasks easier but comes at a cost of breaking existing user expectations.

pointer-events

Pointer event is yet another CSS property that affects interactions, you can use it to change how an element interacts with mouse events.

The most common use case for pointer events is adding pointer-events:none to an element so that it can no longer be clicked on — see this example from David Walsh. This way, you can use CSS selectors to determine whether some elements should be transparent to the hit-testing algorithm, a better alternative to adding checks inside the click event handler for its current target and manually calling preventDefault().

Aside from using it to disable buttons and links, pointer-events:none is helpful when you have some overlapping components and want to pass the click event through one layer to another one underneath. See this example where inline SVG icons overlap with a <select> element, yet clicking on the icons will pass the event through to the select.

Resize

The last CSS property I want to point out is resize, the resize prop allows users to modify an HTML element's size — hence the name.

You are probably already familiar with the resizing behavior in the context of the <textarea> element. Resize behavior works well with textarea because we do not know in advance how much content a user will supply. You can disable this default behavior via resize: none.

But resize is not limited to just <textarea> elements. You can make all content without overflow: visible resizable. Either in the horizontal, vertical or both directions.

Here's a demo of a resizable reading window with a resizable range input that allows you to change the reading font size.

Depending on the input range, a resizable range input could be a more intuitive approach than using the keyboard or clicking with the mouse for a pixel-perfect value.

Conclusion

While we generally consider HTML to be about a document's semantics, CSS for its look and feel, and JS for user interaction, this categorization is not absolute.

Just as the disabled HTML attributes can affect an element's interactivity, there are a number of CSS properties that handle more than styling. Following the Rule of Least Power, we should look for HTML and CSS solutions before reaching for a pure JS one.

If you are not familiar with the resize, user-select, and pointer-events properties — or it's been a while since you last looked them up — I encourage you to take a look at the examples and maybe look up the docs to refresh your memory.

Are negative CSS margins bad practice?

Shimin Zhang — Fri, 03 Jun 2022 19:40:26 +0000

The negative CSS margin is a bit of a black sheep of the box model family. Unlike its siblings the negative padding and border – which are simply invalid – the negative margin is useful yet often misused.

So is using negative margins 'back practice'?

The short answer is no, as long as you are only using negative CSS margins to bring elements closer together than their box model properties would allow.

Since positive margins are used to bring box model objects away from each other, the canonical use case for negative margins is to remove the positional constraints applied by another element's content, padding, or border.

The downside of negative margins is they are difficult to debug and will make your CSS harder to read. The most often misuses of negative margins that I encounter is when it is used to make up for incorrect layouts elsewhere on the site. This is indeed bad practice.

So when should you use negative margins? Let's take a look at some examples.

Offset Padding

One common use case for negative margins is to remove the padding and border constraints applied by a parent element. Let's start with a card containing Keat's poem To Autumn:

We want to enlarge the title of the poem so it takes up the entire upper section of the card, but the size of the <h1> is constrained by the card's outer padding. Negative margins allow us to override the constraints:

You can achieve the same effect using absolute positioning – see below.

The Absolute positioning approach is significantly more brittle since it takes the element out of the document flow. Now we need to add more padding elsewhere on the page to compensate for the size of the title. Changing the size or content of the title now requires changing multiple lines of CSS to update card layout – the dreaded "multiple CSS tweaks for a small change".

Overlapping Boxes

Because negative margins bring elements closer together, it is perfect for creating overlapping elements.

Let's add a little emphasis to the Keat's name in our card and overlap it with card header to add emphasis:

This is a valid use case for negative margins since we are intentionally breaking out of the box model. We can similarly do this with absolute positioning:

Like the padding example, the absolute positioning method requires 2 changes when we make future changes: one to update the copy and another to update the offset to compensate for the copy. This makes our CSS more complex.

Break Out of Parent Container

The last example I want to look at is how negative margins can be used to change a parent component's content width constraint. Let's say we want to add a popover on hover with the author's bio, using absolute position so it doesn't take up document flow:

We see that popover content width is limited by its parent. This is an ugly look. We can set a fixed width for our popover, but the width is now static. With a short copy, this means lots of white space.

Instead of having a fixed width, we can use a negative margin on the child element to allow ample space for growth as the copy needs:

However, this is no longer the preferred way to achieve this effect with the introduction of CSS sizing 3 values min-content, max-content, and fit-content. To achieve this effect with modern browsers we can simply use width: max-content instead:

This is a cleaner, more readable approach that unfortunately does not work in Internet Explorer. Consider adding the negative margin trick as a fallback for IE.

Take-Aways

What should we take away from this exercise in negative CSS margins? A few things to note:

Use negative CSS margins to overcome box model constraints inaccessible to layout algorithm changes.
Negative margins can be easier to work with than their absolute positioned counterparts. By preserving the document flow, fewer layout tweaks are required on content and style changes.
Negative margins can be hard to debug. Consider using CSS custom properties for negative margin values to make your code easier to read and to change.

.parent {
    --top-padding: 3rem;
    --border-width: 2px;
    padding-top: var(--top-padding);
    border-top: var(--border-width) 2px red;
}
.child {
    margin-top: calc(-1 * (var(--top-padding) + --border-width));
}

If you found this post helpful, please share it with others. You may also be interested in learning about how to use CSS custom properties to create style API or why Tailwind CSS is a big deal.

Follow me on Twitter @ItsTrueInTheory to get the latest blog updates.

When
is not enough – A tour of 11 HTML and CSS line break examples

Shimin Zhang — Fri, 27 May 2022 17:26:29 +0000

The other day I was making copy changes and needed to add a line break to a CTA. When I reached for the trusty line break element <br>, I got a PTSD flashback of early 2000's web development – when <br> was frequently used to add vertical spacing. This got me thinking:

When is it wrong to used <br> and should I be using <p> or <pre> instead?

Should I use CSS to style line breaks instead of HTML elements? If so, how should I do it?

In this post, I'll go over various HTML and CSS-based methods for creating line breaks in your text, as well as methods for breaking up words to achieve the right typeset. I'll use the first stanza of Walt Whitman's 1865 poem 'O Captain! My Captain!' to demo each method.

HTML Line Break

Example 1: By default, browsers collapse all HTML whitespace characters into a single space character, removing all line breaks from the content. This is obviously an inappropriate choice. It strips away all rhythm from the poem.

Example 2: You may be tempted to break each line of the poem into its own paragraph element. This creates hard line breaks, but removes element semantics – a paragraph should be an entire stanza containing multiple lines. It also introduces unnecessary margins and padding between lines.

Example 3: This is the canonical use-case of a line break element <br> – to break up a line without introducing additional semantics. However, looking at the text of the poem we see that lines 5-8 contain indentations that are now stripped from the output.

Example 4: The preformatted element <pre> preserves both line breaks and additional white space characters from the HTML. But the <pre> element faithfully preserves all formats and does not allow for text-wrap. This causes overflow for our text, making it better suited for ASCII art and code blocks.

We've reached the limit of what HTML-only line-breaks can do for us, let's take a look at some CSS options.

CSS Line Break

Examples 5 & 6: The white-space CSS property is the main corresponding CSS method for controlling line breaks. Interestingly, there is a CSS line-break attribute, but it only deals with how punctuations behave with line-break for East Asian languages.

The white-space property's normal and pre values correspond to the default <p> tag and <pre> tag behavior, respectively.

Example 7: Things start to get interesting when we move on to white-space: pre-line, where whitespace characters are still collapsed but newline characters now create new lines. Note the indentation from lines 5-8 are still lost, it's as if all new line characters are now treated like <br>.

Example 8: The white-space value pre-wrap acts like the <pre> element, but also creates new lines so our text does not bleed outside of the parent container. This is the best CSS line break solution we have so far for our Whitman poem use case.

white-space has two more potential values. nowrap disables line breaks and collapses whitespace, and break-spaces that behaves like pre-wrap but treats end-of-line spaces without hanging.

So far, we've looked at solutions that break lines up using whitespace or newline character. What if we want to break a line up in the middle of a word?

Word Break

Example 9: The canonical HTML solution for dealing with word-break is the line break opportunity element <wbr> and its cousin the soft-hyphen . They both indicates to the browser that the location is a preferred location for word-break, but only if the browser deemed a word-break necessary.
Example 10: Instead of manually finding all word-break opportunities in your copy, you can use the CSS property word-break with the value break-all to let the browser choose when a word should be broken to form a new line. This is akin to automatically inserting <wbr> after every character.

_Example 11: La_stly, the CSS property hyphens with the value auto can be used to generate browser-determined hyphens for word-break. This is as if we added  to every non-whitespace character in our text. In my opinion, this option gives us our best poem typeset yet, I especially like how fearful's broken into 'fear-ful' and flows naturally from one line to the next. hyphens: manual uses the soft hyphen character to insert line breaks instead.

Final Word

There you have it, 11 examples of adding line breaks to your text!

Here are some rules of thumb:

In general, use CSS line breaks options over their HTML equivalent – separation of concerns between style and content.
The exception to the above rule is when the line break is semantic, such as adding <br> tags to indicate typographic line breaks.
Another exception is the usage of  choice of hyphen location is a semantic property of text.

If you found this post helpful, please share it with others. You may also be interested in learning if it's acceptable to use multiple H1 elements in 2022 or when you should use the px unit for styling.

How to Change CSS Styles with JavaScript – From Basic to Advanced Methods

Shimin Zhang — Fri, 20 May 2022 18:11:27 +0000

How do you use JavaScript to change CSS styles? This seems like an obvious question with an obvious answer: 'modify your site's stylesheets – potentially followed by a compilation step – then update styles at runtime via changing element attributes such as class and aria-*'.

Yet the answer is not complete, consider the following:

How do you update styles at run-time based on user interaction instead of a preset value? It's not feasible to programmatically generate unique class names for every possible color combination.
What if you do not have modification access to stylesheets or HTML? Such as a site builder generated site with third-party CSS files littered with !important properties.

In this post, I'll go over 4 methods of style updates using JavaScript and their use cases. We'll also consider each method's usefulness in terms of its CSS Complexity. That is, how easy is it to understand and modify.

Use Inline Style

Before the invention of CSS, legacy HTML attributes such as color, background, and border were used to style web pages. Inline CSS is the spiritual successor of these attributes, where CSS properties are controlled via the element's style attribute.

The following two ways of changing font size on a hero element are equivalent:

document.getElementById('hero').style = 'font-size: 12rem;';
document.getElementById('hero').style.fontSize = '12rem';

Using JavaScript to update inline CSS is generally considered bad practice for the following reasons:

It violates the separation of concerns between style and content, making the document hard to read and modify.
It removes the ability of CSS selectors to form semantic abstractions.
Without selectors, updating multiple elements on the page requires iterating through each element – a slow and error-prone process.
It bloats your HTML via repeated styles.
It does not have access to pseudo-elements and pseudo-classes that are only available via CSS selectors.

We are currently seeing a resurgence of inline CSS-lite via atomic CSS frameworks such as Tailwind CSS – see my previous posts on Tailwind. Atomic frameworks use CSS class names that translate to roughly one CSS property and rely on JS generate components to increase style reuse. This overcomes shortcomings 3, 5, and 4 from above – though I think the HTML bloat is still considerable.

While inline is CSS generally harmful, it has the benefit of not requiring stylesheet access to make style updates and can be used to make arbitrary run-time style changes.

When to modify inline-CSS: Run-time update of a single element style on the page, for quick dev tool tests, and when stylesheet access is unavailable.

Use HTML Attributes

Next up, we have the canonical answer of modifying element attributes other than style. It is the most popular for a good reason, it does a great job at creating reusable and semantically meaningful styles. Here are some examples:

// toggles HTML semantic state
document.getElementById('cta').disabled = true;
// a aria based semantic button state 
document.getElementById('cta').ariaExpanded = "true"; 
// a class based semantic primary variation
document.getElementById('cta').classList.toggle('primary');

Not much to add here, you are probably both familiar with and use this method extensively. It's both easy to understand and modify, and we have plenty of CSS methodologies to control its complexity.

I do want to point out that the examples above listed are in their order of meaningfulness. We should give precedence to HTML attribute-based states before leaning on class-based states – easier now that :has() selector is on the horizon.

The only downsides of the method are the two I mentioned in the introduction: that it is not possible to generate all arbitrary CSS styles ahead of time, and you need to be able to modify all stylesheets on the site.

When to modify (non-style) attributes: all cases when you have access to stylesheets and have pre-defined styles.

Use CSSOM

The next method for JavaScript-based CSS modification is the surgical knife of the front-end toolkit: directly modifying CSS stylesheet objects. While the previous two methods modify the HTML DOM to affect the style, in some instances it is easier to directly change the CSS Object Model (CSSOM) instead.

By accessing the document's styleSheets object, we can make arbitrary changes to a site's styles with the full power of CSS. For example:

const thirdPartyStylesheet = document.styleSheets[0];
//index 15 rule color: red !important;
thirdPartyStylesheet.deleteRule(15);

You can even add new dynamically generated stylesheets to the site via the CSSStyleSheet constructor. In my experience, this is the best way to deal with third-party CSS stylesheets or site builders with limited CSS capabilities.

The CSSOM approach avoids the dreaded CSS selector escalation where you litter inline style with !important to override third-party styles. It can also be more performant than looping through multiple elements to dynamically update their styles.

The main drawback of the CSSOM approach is how difficult it is to understand and debug. Dev-tool support for modified CSSOM is lacking and unless documented in 24-point font, it can drive future maintainers crazy. Like a surgical knife, use it sparingly and provide plenty of warning.

When to modify CSSOM: best used to remove unwanted third-party styles instead of adding new styles, good for changing styles you have no control over.

Use CSS Custom Properties

The last approach for dynamically updating CSS styles is through CSS custom properties. Though it technically does not use any new APIs, using custom properties is sufficiently different from the previous approaches that it deserves mentioning.

The custom properties can be used with any of the previous methods:

const themeColor = document.getElementById('color-picker').value;
// use with inline style
document.body.style=`--theme-color: ${themeColor};`;
// use in CSSOM
const stylesheet = document.styleSheets[0];
stylesheet.insertRule(`:root { --theme-color: ${themeColor}; }`);

An element's CSS custom properties are inherited by its children. We can use them with inline styles and not worry about selecting and looping through all elements in DOM – we just need to find their shared ancestor. Because of this, custom properties can also be used to modify pseudo-elements with inline style.

The biggest downside of using custom properties is they require planning and stylesheet access. When used judiciously, they can modify multiple styles with a single style update, such as generating an entire color palette with one color update.

Compare to the previous approaches, custom properties require as much if not more planning than the element attribute approach, but can be used for run-time style updates. It's easier to maintain than the CSSOM approach– there are fewer changes to keep track of – but you need stylesheet access.

When to use CSS Custom Properties: When you need to make complex run-time style changes, when you want to create new relationships between styles properties, or when you need to pierce the Shadow DOM to style lots of web components.

Take-Aways

Next time you need to change CSS style via Javascript, ask yourself:

Is this a pre-defined style update or is its value determined dynamically at run-time?
Am I overriding an existing third-party style?
Do I need to modify a single element, or multiple ones on the page, including pseudo-elements and classes?
Do I want this change to affect multiple derived properties, or shared by multiple elements on the page?

Front-end development is evolving quicker than ever and with no signs of slowing down. It's helpful to periodically slow down and take a look at all the tools available in our front-end toolkit.

And speaking of new tools, I am especially looking forward to learning and using typed style properties through the Houdini custom properties API.

The Unreasonable Effectiveness of the To-do List – Zeigarnik Effect and Developer Productivity

Shimin Zhang — Fri, 13 May 2022 17:05:29 +0000

I touched on the business cost of context switching in last week's post. This week, I want to dig deeper into a hidden cost of context switching: the cognitive costs of unfinished tasks.

Ever notice you are more effective when working on one project at a time instead of juggling multiple projects concurrently?

Do you have multiple meetings in the day so you are constantly stressed about what to do next and unable to focus?

In a more general form, do work-related thoughts intrude into your non-working hours?

I'm an anxious person by nature. Learning about the Zeigarnik Effect and how it shapes my mental capacity has been a productivity and mental health game-changer. While I am not a 'productivity expert', I want to document how I deal with the cognitive cost of juggling multiple unfinished tasks.

The Zeigarnik Effect

The Zeigarnik Effect states that an uncompleted task has an associated cognitive overhead. The task will periodically demand our attention and drains our mental resources until it is completed.

The effect is named after the Russian psychologist Bluma Zeigarnik. While on vacation in 1923, Zeigarnik noticed the same restaurant server who previously remembered the entire table's orders did not recognize her when she went back to fetch her forgotten purse – merely minutes after the table finished paying.

Inspired by this realization, Zeigarnik later performed a series of experiments to confirm that we keep a 'cognitive cache' for any uncompleted tasks, making their context easily retrievable. Later studies confirm her initial hypothesis, though with the caveat that this cognitive penalty only occurs when we do not have a well-formed plan on how to complete the tasks. See Masicampo 2011 on how plan making can eliminate the negative cognitive effects of unfinished tasks.

The Zeigarnik Effect partly explains why we have trouble constantly context-switching and juggling multiple projects. Each unfinished task drains our mental capacity and reduces our ability to focus – that is, until they are 'garbage collected'. According to this 2020 study, unfinished work tasks can lead to excess rumination and negatively affect our sleep quality – even on the weekends.

Dealing with Unfinished Tasks

My number one tool for dealing with the Zeigarnik Effect is the humble text-based to-do list. Specifically, I use a single page of the macOS Notes app to keep all my work-related to-dos.

If I'm in the middle of a task and have to context switch to a meeting or bug intake, I chunk the unfinished portion of the task into a new to-do list item and add it to the front of the queue. Whenever a new task comes up during a meeting, I translate it into an actionable item – even if it's as simple as a 'ping X to confirm Y'.

I rearrange the to-do list periodically based on priority – oftentimes multiple times a day – so I always have a rough plan of attack for the next few business days. And because the tasks are in actionable form, they do not drain my attention the same way a list of unknowns would. This allows me to focus deeply on the task at hand.

I first came across the benefits of this approach when I read David Allen's Getting Things Done. As part of the GTD workflow, I wrote down goals that captured my attention and clarified the actionable steps needed to achieve them. The simple act of writing actionable steps towards a goal down and putting them away provided immediate and immense stress relief.

Why do I use a text to-do list when Jira tickets, Trello boards, and Gitlab issues are available? Because it is easy – which epic and milestone should I tie 'ping Sarah about the checkout workflow copy' to? Plus, small tasks that do not merit an entire Jira ticket will still drain your mental resources – so they are added to the list regardless of size. If the list gets uncomfortably long overtime, sharpen your machete and remove the lowest priority items – anything that's truly important will resurface later – another tactic I borrowed from Getting Things Done.

Meditation's another tool that helped me deal with the negative aspects of the Zeigarnik Effect. I try to meditate between 5-10 minutes a day – it's the garbage collection process for my mental health. Any unfinished tasks occupying my mind will surface to the conscious mind during meditation. I can either make a quick plan to deal with it and file it away mentally or physically – or failing at that, meditation is the daily practice of not being so easily distracted by them.

The last thing I do to shield myself from the Zeigarnik effect is I always choose to stop coding after finishing a milestone instead of leaving code half-finished. While some developers swear by finishing the day mid-code – so they can easily jump in the next day – I find the practice causes work to bleed into my personal life. If forced to, I add a 'fix failing tests' to the top of the to-do pile before switching to something else.

Final Word

I first came across the term Zeigarnik Effect in Kathy Sierra's Badass: Making Users Awesome. While I mostly wrote about its detrimental effects in this post, you can also use it to help you perform your best – see this article on how professional athletes use the Zeigarnik Effect to reduce performance anxiety.

Here are the key take ways points:

Interrupted and unfinished tasks will drain your mental resources, leading to stress and poor performance.
You can eliminate the negative effects of unfinished tasks through plan-making.
The act of turning unfinished thoughts and tasks into concrete next steps – such as a to-do list – can be a quick and effective way to combat the Zeigarnik Effect.

If you found this post helpful, please share it with others. You may also be interested in learning about how to spot 'Fake Agile' teams during interviews or using Bloom's Taxonomy for faster skill development.

If you have any tips on how you deal with the Zeigarnik Effect, leave a comment below or ping me on Twitter @ItsTrueInTheory.

Why a Meeting Costs More than a MacBook Pro – the Business Case for Fewer Developers in Meetings

Shimin Zhang — Fri, 06 May 2022 15:37:52 +0000

Developers are famous for disdaining meetings. Meetings force us to context switch, kill our flow, and sap our job satisfaction long term. Yet, managers and scrum masters can't seem to get enough of them, and the resulting tension is all over our calendars. Paul Graham (internet) famously documented this phenomenon in his essay Maker's Schedule, Manager's schedule.

Large organizations are especially known for overstuffing developer calendars with pointless meetings – at least pointless to developers. And when a scrum master goes rogue, a dev can have days when nothing of actual value gets done between retros, sprint plannings, demos, and process alignments.

I sat through a particularly useless meeting the other week with a meeting screen full of other devs – oddly, it was initiated by a tech lead on a different team. During the boredom, I started wondering :

How can we make a business case for fewer pointless meetings on our calendars?
How can we add more value to the meetings we attend?
How can we have fewer meetings of the pointless kind and more of the value-added kind?

The Opportunity Cost

I was an accountant in my previous life, so I want to put a number on exactly how much a meeting can cost. Here's my ballpark calculation of the opportunity cost of a meeting for the company, regardless of whether it is pointless.

Here are my assumptions: these are US-centric, adjust for your local market conditions:

The meeting is 1 hour long, involving a PM and a team of 4 developers.
The developers have an average total compensation of $200,000 and 2 Weeks of PTO.
On average, an employee costs an employer 1.5X their compensation in other benefits.
An average developer is in a maximally productive flow-state on average between 4-6 hours per day, we'll use 5 hours for our calculation.
The business value-added per developer is 80% from flow state and 20% from non-flow state following the Pareto principle.
This is a badly scheduled meeting in an organization with too many meetings already – cutting into flow state time. Each developer on average wastes 30 minutes before and after the meeting to context switch and the time is otherwise non-value adding. (See this study for the cost of context switching).

Using these assumptions, we see that each developer's inflow state per hour costs to the company is ($200,000 * 1.5 * 0.8) / ((52-2) * 5 * 5) = $192 per 'flow hour'.

At a cost of 2 hours in 'flow hours' per developer and 4 developers in this meeting, the meeting's developer opportunity cost is $1536. The meeting's opportunity cost is higher than the price of a brand-new M1 MacBook Pro. If the meeting was pointless, might as well cancel it and fly one of the devs to Bali instead.

In my experience, corporations with the most meetings are often also stingiest with dev equipment and educational/training expenses – a classic case of penny wise and pound foolish.

What you could be looking at instead of your PM's screen with his favorite spreadsheet.

Value-Added Meetings

Because of my accountant tendencies – and because I used to be a freelancer – I try my best to make sure I add enough business value to every meeting to justify my presence. Politics aside, it actually makes me feel a bit bad to only sit in on one. I hate wasting my time.

Value-added can be everything from providing actual technical perspective and expertise to simply keeping everyone on track. Cutting a 15-minute detour in an 8 developer meeting is enough value added to justify attending. Of course, it's even better if you cut the meeting short when it's going nowhere, or suggest it be canceled, to begin with.

An even better way to get value from a meeting – especially for senior devs and tech leads – is to attend for the rest of the team and write a one-page summary that can be consumed at the rest of the team's leisure.

Take the meeting from the previous section: A senior dev hashed out the issue with the PM one on one and spends an extra 30 minutes post-meeting summarizing the key points learned and decisions made. The senior dev just added $1500 worth of business value in an hour and a half of work – a real force multiplier.

Have Better Meetings

I'm by no means a meeting expert (nor do I really wish to become one), but here are some meeting tips that work well for me:

Batching meetings: When possible, reschedule meetings to right around my team's daily standup and at the end of the day when I'm ready for a mental break. I try to keep the 11 am-4 pm block of my day free. Bonus point: the best way to batch meetings is to skip them.
Have an agenda: This is meeting 101 stuff, but it is too often ignored. Have the action items and desired meeting results spelled out ahead of time, this allows you to cut them short once a decision is made. Bonus point: be the guy who says 'sounds like we finished everything on the agenda, shall we call it?'.
Separate the async from the sync: You wouldn't block the main JS thread with functions that can be resolved asynchronously, so why block a synchronous meeting going over information that can be provided via email and read whenever? Bonus point: sometimes the act of writing down the context turns a meeting into an email or slack poll.

Final Word

Skip more meetings, make a case that the shareholders aren't paying you hundreds of dollars an hour to listen – that could get through the MBA types.

Manage your meetings, and crush the ones you choose to attend. Be a force multiplier and your team will thank you for your leadership.

If you found this post helpful, please share it with others. You may also be interested in learning about How an MR comment hierarchy can Speed Up Delivery or Use 'Disagree and Commit' to get through technical disagreements.

If you have any tips for the community about better meetings, leave a comment below or ping me on Twitter @ItsTrueInTheory.

Got Messy Spaghetti Stylesheets? 4 Techniques for Managing CSS Complexity

Shimin Zhang — Fri, 29 Apr 2022 19:31:58 +0000

Last week, I wrote about the definition of CSS complexity and how CSS features have inherent complexity – that is, complexity outside of a web designer's control.

This week, I want to take a look at some tried and true techniques for unwinding your spaghetti CSS. The techniques are covered in their general form – with links to framework level implementation examples.

This is not a 'list of CSS methodologies' post – there are enough of those. Nor will I try to convince you to use 'The One Framework / Process' – every team is different and every project's needs are unique.

My goal for this post is to provide a few metrics to analyze CSS technologies, which will hopefully help you (and myself) choose the right one for a new project.

Complexity Recap

Here's a quick summary of CSS complexity:

CSS complexity is anything related to the CSS of a project that makes it hard to understand and modify.

CSS complexity shows up in 3 forms:

Change Amplification: making a style change require multiple edits.
High Cognitive load: a large amount of context is needed to make a change_._
Unknown unknowns: when it is not clear where to make a change.

Ok, on to the techniques!

Limit Selector Combination

One of the biggest source of CSS complexity is selector explosion and the resulting specificity escalation – where an nth level element with a single class on the page has >2^n possible combination of potential class based selectors. CSS's machine friendly specificity score calculations only adds to this problem. (See example from last post)

This problem affects all 3 symptoms of complexity: In order to make a style change, you now have to remember all selectors targeting the element (high cognitive load) track down the right ones (unknown unknowns), and potentially change multiple files (change amplification),

Because this is a foot-gun, all CSS frameworks and best practices imposes limits to the selector space. The the advice 'don't use elements in your selectors' as an example, it removes a substantial subsets of potential selectors.

Framework examples:

Tailwind sticks to a single level of class based specificity – not including normalizing CSS.
Block Element Modifier (BEM) takes a similar approach and recommends against using combined selector for variations – limiting selector space to class based selectors with at most 2 levels.
Scalable and Modular Architecture for CSS (SMACSS) does not restrict selector type, instead opting for limiting depth. It allows for layout ids and modules can potentially double up on class selectors.
The example of never using elements in your selector came from Object Oriented CSS (OOCSS).

The exact number of allowed selectors isn't as important as the need to have a principled way to limit selector depth.

The difficulty of limiting selectors is it needs to be both documented and enforced. It's easy to slip up when 'design needs this change done yesterday'.

Reduce Property Overlap

Source order is another major source (sorry) of CSS complexity. The same component on different pages might have different styles due to different import orders – especially if selector specificity is flattened.

This leads to both unknown unknowns (which file to change?) and high cognitive load (remember to always include foo.css before bar.css).

The best way to combat this is ensuring overlapping selectors do not overlap in CSS properties. And if they have to overlap, make sure their relative specificity is unambiguous.

Framework examples:

Atomic frameworks like Atomic CSS and Tailwind takes a single purpose approach to selectors, so CSS properties are naturally never overlapping – this is also why Tailwind's @apply is an anti-pattern when overused.
BEM is against global modifiers for this reason also, and modifier styles should always be declared after the block.
When global utilities are encouraged, as is the case with ITCSS, utility classes are encouraged to have !important applied to all values. So the property value is always clear.
CUBE CSS gets around to this problem by separating layer concerns from visual properties. Layout classes and blocks should not share properties.

When not using a utility first approach, it can be difficult to keep track of all classes' overlapping properties in a project. I think this is an area with a need for better tooling.

Restrict Selector Scope

CSS is global in scope – at least pre cascade layers. As with code, global CSS leads to name conflicts in large projects. When creating a new component, you need to keep in mind every class name used in the project along with potential 3rd-party classes.

This imposes a cognitive load penalty that scales with the size of the project and the number of developers working on it.

The solution to this problem is the same as in programming, you reduce selector scope to eliminate possibility of collision.

Framework examples:

Component based CSS frameworks originating with OOCSS inherently limits selector scope to only elements inside the 'CSS object'.
ITCSS / BEMIT introduces a Hungarian notation of class names to aid in reading – this reduces cognitive load when reading CSS.
Taking the idea to somewhat of an extreme, CSS modules explicitly makes all CSS locally scoped by default.

There's not much downside to limiting CSS scope, although when taken too far you'll end up with larger stylesheets than needed. You can prevent this through planning out sensible global default styles, I especially like CUBE CSS's approach to progress enhancement.

Style Colocation

The last problem I want to take a look at is the inherent complexity of using class name based CSS hooks.

Image you have a large, existing e-commerce site. One day, your designer asks you to add a purple decorator to female gendered product category headings and another for male ones. Assuming this was not an abstraction previously included in your site's markup, now you need to come up with a semantic and non clashing class name for gendered heading variation. Then you need to update the code that generates the reusable heading template to add logic for heading--male and heading--female. Side Note: there are lots of other ways to do this, but for this example I'm limiting it to a BEM modifier.

In my opinion, this is 'play-pretend separation of concerns', a style-only update now triggers a 'semantic' html rabbit hole. I'm not the only one to feel this way, I first came across a clear description of this problem in this Adam Wathan post.

This pattern leads to change amplification and unknown unknowns, you have to find the right HTML template and its corresponding CSS file, make the same modification in both places at the same time, and if you make a typo in either case, check two files to find it.

This problem is best mitigated by placing style information right next to HTML templates. This way, even if you have to invent a new 'semantic classname', you at least can do it in the same file.

Framework examples:

Some leave out style hook class names all together, instead use aria attribute and semantic HTML elements to separate style from markup. See this Heydon Pickering Smashing Magazine Article and Enduring CSS chapter.
Atomic approaches (ACSS, Tailwind) get around this by using only style based hooks, reading the class is looking at its style – no need to cross reference.
CSS-in-JS category of tooling (JSS, Styled-Components, etc.) does 'inline++' styling, which also has the added benefit of placing style information right next to template.
Lastly, JS frameworks like Vue and Svelte provide an all in one experience, where template, style, and functionality all live in the same file.

The largest drawback of this approach is it violates the traditional concept of separate JS, CSS and HTML files, each responsible for its own domain of the web experience.

Take Aways

Next time you read about 'the next big CSS paradigm', you can map its features to one of the general techniques above. And if you are looking to create your own CSS workflow / framework, I hope you will take these general patterns into your consideration.

I finished the initial draft of this post feeling like I've only made a dent in the topic – serves me right for trying to cover an area as broad as 'how make CSS less complex'. So please let me know if I've missed one – or a dozen – of your favorites. Leave a comment below or ping me on Twitter @ItsTrueInTheory.

Why Your CSS is Always Messy and Chaotic – Understanding CSS Complexity

Shimin Zhang — Fri, 22 Apr 2022 16:14:02 +0000

Does the thought of making a minor style update in a large front-end project give you pause? It does for me. It can be especially hard when I'm modifying a project written by another team, even if the change is small.

Somehow, CSS stylesheets (preprocessed or otherwise) are always a jumbled mess of classes and ids. Why is it common to have clean JS/Python/PHP code and spaghetti CSS in the same code base?

This week, I want to take a look at what makes CSS complex, using the ontology of software complexity from John Ousterhout's excellent book A Philosophy of Software Design. This post sets the table for why CSS gets so messy – before we dig into design patterns and solutions next week.

What is Complexity?

Let's start off with a complexity definition. From A Philosophy of Software Design: "Complexity is anything related to the structure of a software system that makes it hard to understand and modify the system.".

This definition fits CSS quite well. Complex CSS is hard to understand and harder to modify – obligatory link to the CSS stool joke.

Ousterhout also points out three symptoms of complexity that make a piece of code hard to work with:

Change Amplification

Change amplification occurs when a seemingly simple change requires changes in multiple places.

Example in CSS land: you are tasked with changing all paragraph text colors on a website from black to navy. With a simple HTML page, it's as simple as a one-line p { color: navy; }. On a large project, you spend the whole day defeating the highest specificity that applies to all <p> elements on all pages – only to discover the checkout gadget's shipping confirmation modal has a paragraph element that somehow inherited text color from the teal heading.

Cognitive Load

Cognitive load is the amount of information a developer needs to keep in mind in order to make a change.

Example in CSS land: You are asked to change the font-size of the hero section CTA button on large viewports from 20px to 22px. Here's a list of information you may have to keep in mind:

Default body font-size from user agent stylesheets.
Existing button font-size for small and medium viewports.
font-size of hero section text because the em unit seems like a good fit.
Maybe we use rem instead, does the project use the standard 16px rem size or 10px rem size for ease of calculation?
Potential hero section variation of the button and its font-size.
Any font-size utility classes the project may have.

Unknown Unknowns

You face unknown unknowns when it is not obvious where to get the information needed to complete a task, or where to make the necessary change.

Example in CSS land: You are changing the error message color for a <span> element in a login widget on the category page. Do you make the change in utilities.css, form.css, widget.css, login.css, category.css, or index.css? Depending on your project's CSS methodology, this could be a component variation, a new component, or a new utility class.

Why CSS gets Complex

Next, let's take a look at different technical causes of CSS complexity.

Selector Space

While CSS properties belong to a single matched element at a time, CSS selectors are matched against all elements in the DOM. So, as a project grows in size and the number of total selectors – both actual and potential – grows, we have a natural increase in CSS complexity.

The total number of CSS properties in the DOM grows linearly with DOM size – a page with n total elements at x properties per element have at most nx total adjustable properties.

On the other hand, the size of the set of potential selectors grows exponentially with respect to DOM depth. Assume using only a single class per element, a m level deep DOM element has 2^m number of applicable class-based selectors.

Since the total number of potential selectors grows exponentially on large projects, it impacts both cognitive load and change amplification – to understand and modify its implemented subset.

If you ever wondered why front-end developers spend so much time tinkering with and cursing at CSS selectors, it's because the selector solution space for any given change is HUGE.

Specificity

In my experience, there's no quicker road to unmanageable CSS than "specificity escalation". Because any moderately complex project will have a huge set of potential selectors for each change, and because CSS selector specificity score is additive in nature, a project's average CSS selector specificity tends to increase as it grows.

As Chris Coyier pointed out in this answer about CSS code smell, when you see a selector like #articles .comments ul > li > a.button in your dev tools, it's already too late.

Specificity-related complexity is symptomatic in all 3 categories. We already covered the need to create ever more specific CSS selectors in the change amplifications case – eventually reaching id selectors, !important, and inline styles.

Specificity escalation also means developers reading and modifying CSS now need to keep a detailed mental model of the DOM in their mind when working – is it .comments inside #articles or is it .comments inside uls inside #articles?

Lastly, ever-increasing selector length means the number of locations that a style change may belong to also increases linearly. In the selector example above, should the change go in articles.css, comments.css, global.css or just use 'find in the project' – and what if you use a preprocessor that supports nested selector?

Source Order

CSS source order gives us a way to consistently predict how a style resolves when multiple selectors have the same specificity score. It also handles when multiple values are declared for the same property in the same scope – an especially tricky combination with CSS shorthands.

The rule is simple, the value that appears last wins.

Straight forward, right? Not so fast. This means each change we make is potentially affected by all other selectors with the same specificity. Your .nav .button could be affected by .header .button. In fact, you need to be aware of the intersection of all sets of elements matched by each selector with the same specificity score as the one you are working on. I can't even keep the entire DOM in my head at once, never mind the subset matched by all stylesheets. It's easy to see how this is a significant cognitive load that grows with project size.

Source order is an even bigger problem in large projects where multiple stylesheets are included per page – either plain CSS or via preprocessor imports. Assume you are changing the color of the span in the following BEM-based DOM structure to green:

<div class="widget">
    <div class="widget__content">
        <div class="media-box">
            <span class="media-box__label">Change Me</span>
        </div>           
    </div>
</div>

and the CSS files:

/* widget.css */
.widget .widget__content {
    color: red;
}

/* media.css */
.media .media__label {
    color: blue;
}

If you have no guarantees on the order of the stylesheet imports, which file do you change? This is a clear case of unknown unknowns, and it grows linearly with project file size.

Do you change both 'just to be safe' and thus engage in change amplification? Or do you write .widget .widget__content .media-box and engage in specificity escalation?

Inheritance

CSS inheritance governs how certain CSS properties, when not specified, inherit values from their parent elements. Some common properties that inherit include color, font-size, and line-height.

Inheritance is not as problematic as the other issues covered so far. It's a layer of abstraction that has little impact on change amplification and does not produce unknown unknowns. What it does is lead to additional cognitive load, even if the issues are mostly discovered via the browser – can you picture what "hello world" in the below example look like?

<div class="a">
    <div class="b">
        <div class="c">
            <div class="d">
                <p>Hello World</p>
            </div>
        </div>
    </div>
</div>

.a {
  color: blue;
  font-size: 14px;
  letter-spacing: 2px;  
  line-height: 3;
}
.b {
  font-size: 12px;
  font-weight: 800;
  letter-spacing: -1px;  
}
.c {
 color: teal;
 font-weight: 600;
 font-family: 'Serif'   
}
.d {
  font-size: 18px;
  font-family: 'arial'  
}

Final Word

I hope I've convinced you that CSS is inherently complex, and its complexity grows superlinearly with the size of your project.

Next time you get frustrated with a design change that seems to take much longer than it should, know it's probably caused by the project's CSS complexity.

Next time you see a long selector in a code review – call it out and nip specificity escalation in the bud.

And if you are starting a new project, I hope this post has further convinced you to adopt a tried and true CSS methodology and enforce it – really enforce it. No need to make CSS more complex than it has to be.

Next week, I'll go over some historically successful patterns for combating CSS complexity, their tradeoffs, and the methodologies that use them.

If you found this post helpful, please share it with others. You can also follow me @itstrueintheory or on Twitter @itstrueintheory to get the latest blog updates.

3 Interview Questions to Spot "Fake Agile" Software Engineering Teams

Shimin Zhang — Fri, 15 Apr 2022 15:29:24 +0000

Last week, I wrote about how software companies can claim to "do the Agile" while implementing waterfall or spiral models of software development.

If "fake agile" is the norm, asking a hiring team "do you do real agile?" is pointless. Nor is it helpful to ask about various agile-related ceremonies. No team is going to tell you 'Yeah, we waste about an hour every morning going over trivial issues during standup' – especially not in an interview setting.

When I interview, I want to find out if the team follows the Agile Manifesto and its Principles. If the core is rotten, the rest (SAFe/Lean/XP/Crystal/TDD) are just lipstick on a pig.

Note: I am not advocating that Agile is the end all be all way to create software. Waterfall, spiral, and other SDLC methods have their uses. I happen to usually look for web development roles and like an agile environment.

Here are 3 questions to help you find out if the company you are interviewing with is doing AgileFail – ask a developer you'll be working with:

"Tell me about the last time you refactored a module."

Follow up to get an answer on when it last happened, how large was the refactor, what caused it, and if management was involved.

A waterfall development process usually refactors at the beginning of a project, or when the project can no longer bear the weight of technical debt and outdated design decisions. This leads to large and long refactor periods, often after spending much time convincing management and multiple missed deadlines.

A spiral model team has built-in refactor opportunities, after milestones or batches of customer feedback, leading to medium-to-large-sized refactors.

An agile team has a refactoring as you go mentality. Only a handful of modules are touched at most and require little to no management wrangling.

An agile answer would sound something like: 'I abstracted out the shipping calculation last week while adding DHL shipment support, it was the right opportunity to separate the UPS specific logic from common carrier abstraction.'.

Related Agile Principles:

Continuous attention to technical excellence

and good design enhances agility.

The best architectures, requirements, and designs

emerge from self-organizing teams.

"Tell me about the last piece of user feedback that became a feature."

Follow up with questions on how user feedback is gathered, how frequently that communication occurs, and how involved devs are in the feature design process.

A ScrumFail team often would blank on this question, features are decided on and designed by individuals with no interaction with the development team. Or the product owner decides to add a feature to meet a KPI and the requirements are handed down at the beginning of a months-long planning period.

A spiral development team gets these periodically – such as during milestone deliverable reviews – and spend a chunk of time incorporating those new feedback into the existing software.

An agile team gets user feedback in the form of direct user interactions and usage data, developers are involved early and often in new feature development.

Here's a hypothetical answer that I would love: "The product owner told us users reported the shipping calculation selector was confusing, so I worked with our UX designer on a few alternative designs. They are currently being A/B tested".

Agile Principles involved:

Business people and developers must work

together daily throughout the project.

Individuals and interactions over processes and tools

Customer collaboration over contract negotiation

"Tell me about the last feature of yours that got dropped."

This one is simple, I want to confirm that features get dropped, period. Bonus points if the feature is dropped due to user feedback or otherwise gets bumped by a higher priority item.

Waterfall teams have a deadline for each piece of work – coerced or otherwise – and simply do not drop features. Of course, unexpected high-priority tickets keep flying in. So developers are constantly sprinting forward while dodging incoming P0s. This road leads to misery and burnout.

Spiral process teams check in on a predetermined schedule and may decide to cut out-of-scope or infeasible features.

An agile team tries to plan things out, but they also know that plans do not survive first contact with the enemy. And if you are responsive to change, you have to frequently drop outdated plans to make room for new ones. Features may start as a research spike or proof of concept, but they are validated via user feedback and they get dropped if priorities change.

A good answer here would look like this: "Last month I was working with the designer on a new checkout workflow, but we got a spike of complaints about shipping options after we expanded services to Europe so the checkout flow work got dropped to a later date".

Agile Principles involved:

Responding to change over following a plan

Agile processes promote sustainable development.

The sponsors, developers, and users should be able

to maintain a constant pace indefinitely.

Take-Aways

Why these questions and not "how do you decide on a new feature?" or "How often do you refactor?"? Because the alternatives invite calorie-free answers like "user feedback is the most important guide for our product roadmap" and "we write the highest quality code that gets the job done".

I want concrete examples from the past, not hopeful future fluff. So if you are on the job market looking for a team that cares more about being agile than going through the motions to look agile, ask these questions:

"Tell me about the last time you refactored a module or class."
"Tell me about the last piece of user feedback that became a feature."
"Tell me about the last feature of yours that got dropped."

If you find this post helpful, you may also be interested in learning more about how fake agile is done, or how a comment hierarchy can improve your code review process.

DEV Community: Shimin Zhang

My Favorite Books of 2022

Every Layout by Heydon Pickering and Andy Bell

The Mom Test by Rob Fitzpatrick

Philosophy of Software Design by John Ousterhout

Designing Data-Intensive Applications by Martin Klepperman

Badass: Making Users Awesome by Kathy Sierra

Reactive Design Pattern by Roland Kuhn with Brian Hanafee and Jamie Allen

The Timeless Way of Building by Christopher Alexander

Javascript readability vs performance: a false tradeoff

Benchmarking Our Functions

V8 Bytecode

V8 Optimized Javascript

Takeaways

Additional Readings

Troubleshooting a JavaScript memory leak

JS Garbage Collection

Setting up

Shallow vs Retained Size

3 useful CSS properties to customize your web interactions

user-select

pointer-events

Resize

Conclusion

Are negative CSS margins bad practice?

Offset Padding

Overlapping Boxes

Break Out of Parent Container

Take-Aways

When is not enough – A tour of 11 HTML and CSS line break examples

HTML Line Break

CSS Line Break

Word Break

Final Word

How to Change CSS Styles with JavaScript – From Basic to Advanced Methods

Use Inline Style

Use HTML Attributes

Use CSSOM

Use CSS Custom Properties

Take-Aways

The Unreasonable Effectiveness of the To-do List – Zeigarnik Effect and Developer Productivity

The Zeigarnik Effect

Dealing with Unfinished Tasks

Final Word

Why a Meeting Costs More than a MacBook Pro – the Business Case for Fewer Developers in Meetings

The Opportunity Cost

Value-Added Meetings

Have Better Meetings

Final Word

Got Messy Spaghetti Stylesheets? 4 Techniques for Managing CSS Complexity

Complexity Recap

Limit Selector Combination

Reduce Property Overlap

Restrict Selector Scope

Style Colocation

Take Aways

Why Your CSS is Always Messy and Chaotic – Understanding CSS Complexity

What is Complexity?

Change Amplification

Cognitive Load

Unknown Unknowns

Why CSS gets Complex

Selector Space

Specificity

Source Order

Inheritance

Final Word

3 Interview Questions to Spot "Fake Agile" Software Engineering Teams

"Tell me about the last time you refactored a module."

"Tell me about the last piece of user feedback that became a feature."

"Tell me about the last feature of yours that got dropped."

Take-Aways

When
is not enough – A tour of 11 HTML and CSS line break examples