search

w3ctag / design-principles

A small-but-growing set of design principles collected by the TAG while reviewing specifications
https://w3ctag.github.io/design-principles
178 stars 46 forks source link

New principle: Events should only fire during actual state transitions #483

Open LeaVerou opened 7 months ago

LeaVerou commented 7 months ago

This was brought up in our discussion of https://github.com/w3ctag/design-reviews/issues/843

It started as a naming observation: change is far more common than update in event names. Then we realized that update may be more appropriate when the event invocation happens regardless of actual state change. However, that does not seem to be followed by the web platform, e.g. reading the MDN docs on timeupdate, it sounds like it would only fire when the time has actually updated.

Regardless, events that fire when things have not actually changed should be an antipattern. This is basically polling in disguise: the whole architectural reason to use events is that they fire during state transitions. Not only is this wasteful, it’s unclear whether there is an actual benefit to it (compared to only firing the event when there is a state transition).

annevk commented 7 months ago

That's correct. And the state transition and event are to be coupled together in a single task. You don't want to have one task updating the state and another firing the event.

LeaVerou commented 7 months ago

Discussed today in a breakout with @plinss:

There are two components to this:

  1. Naming guidance (change over update)
  2. Behavior guidance (events should not fire if no state transition has happened)

The first seems quite straightforward: change is definitely the de facto standard in the Web Platform right now, with timeupdate and compositionupdate being the outliers. Are there reasons these were not named timechange and compositionchange? If so, we should encode those reasons in the naming guidance. If not, we should list them as antipatterns.

The second also seems uncontroversial, but until the requesters reply in https://github.com/w3ctag/design-reviews/issues/843 it's unclear if there has ever been an offender to this, in either an existing technology, a proposed one, or even a (popular) authorland one. If there is no example of anyone getting this wrong, I question the value of spending time writing it, though @plinss and I could not reach consensus about whether that means deprioritizing it or closing it altogether.

So to sum up:

  1. We should definitely encode the naming guidance in the naming section of the Design Principles
  2. Wrt the behavior guidance, let's leave this open for a bit and see if offenders emerge, and we can prioritize accordingly.
annevk commented 7 months ago

I think it's worth drawing a more explicit line between https://w3ctag.github.io/design-principles/#js-rtc and https://w3ctag.github.io/design-principles/#event-design. Even if there's no known offenders, there's quite a few people struggling with the event loop.