31:T648,md`# Observable anti-patterns and code smells Here are a few things that you might do a bunch in JavaScript ‘in general’ but are often more trouble than they're worth within in the context of Observable. **Table of contents** 1. **Timers**: use them sparingly, a lot of times there’s a better way 2. **Mutation**: try to avoid it! 3. **Generators**: the return value doesn’t matter 4. **Re-selecting elements**: it's much better to reference elements in a notebook using variables than it is to reference them using class or tag names. ## Timers The first is _timers_. These take a bunch of forms in traditional JavaScript: \`\`\`js // Good ol' setTimeout lets you run a function after a given // number of milliseconds. setTimeout(() => console.log('hi!'), 1000); // setInterval is like that, but runs a function 'every' given // number of milliseconds. setInterval(() => console.log('hi!'), 1000); \`\`\` Now timers will still ‘work’ in Observable, but a lot of the time they’ll cut against the grain. That's because cells are often _re-evaluated_, so it's important that everything a cell does can be cleaned up. Timers tend to just glom on to a page. If you set an interval, evaluate that JavaScript, and then evaluate it 10 more times, you just get 10 timers. For example, let's say you wanted a cell that was an ever-increasing number, which ticks upward every 1 second. Probably the most ‘idiomatic’ way to do this is with Promises.delay. Consult the excellent [standard library notebook](https://beta.observablehq.com/@mbostock/standard-library) for all the details here.`32:T5fc,md`Note that when you run the second cell - the one that calls \`.splice\` - the third one, the one that displays \`a.length\`, doesn't automatically update. Because the .splice method mutates the array in-place and doesn't return a new value, the notebook can't know when or if \`a\` is being changed in this case. This is a bummer! One of my favorite things about Observable notebooks is that _cell evaluation order doesn't matter_. They don't run top-to-bottom, they simply run whenever values are needed or updated. Mutation really mucks that up. Luckily, this is a pitfall that can be avoided. When you run into a method that works by default with mutation, you can make your code nice and ‘immutable’ instead by: - Using an alternative that doesn't mutate the data - for instance, using [Array#concat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/concat), which returns a new Array, instead of [Array#push](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/push), which modifies an array in-place - Making a copy of the data and mutating that: for instance, by using [Array#slice()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/slice) Here's an example of the latter, as an alternative to the code-smelly example you just tried. Instead of calling \`.splice\` directly on the given array, I use \`.slice()\` first to create a shallow copy of the array, and assign the new value to a new variable.`33:T42b,md`Boo! That's an example of something that looks like it'd work in JavaScript in the wild, but isn't a good idea here. Remember that in Observable, _the order of cells doesn't mean the same thing as the order of code in the rest of the world_. Cells don't run top-down: they run in dependency order. And if two cells don't have a dependency relationship - one cell doesn't rely on the other's name - there's no guarantee that they'll run in any specific order. This is a _good thing_. In math class, when your teacher says "What’s the sum of a and b, if a is 5 and b is 4?", your brain doesn’t crash because you don’t know the value of a and b _before_ hearing the first part of the question. Just like in mathematics, it doesn’t matter that you learn the value of b later – you’re able to integrate that information into an answer. So, the example above might even work in some cases, when Mercury is in retrograde perhaps, but there are no guarantees. Here's, instead, an example of using a dependency relationship between the two to ensure order:`34:[] 2f:{"title":"Observable anti-patterns and code smells","cells":[{"id":0,"value":"$31","pinned":false,"hidden":false,"mode":"ojs"},{"id":16,"value":"{\n let i = 0;\n yield i;\n while (true) {\n yield Promises.delay(1000, ++i);\n }\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":21,"value":"md`The example above is pretty good, if I might say so myself: it automatically pauses when you leave the tab, it isn't much code, it ‘cleans up’ and restarts easily when you re-evaluate the cell.\n\nHow would you do that with setInterval? There are a few ways, none of which are all that pretty. Here's the first - what is to me the naïve way that I’d guess, and it has a big drawback: it’s constantly yielding the same value in between those 1 second ticks. It yields lots and lots of 0s before getting to 1.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":24,"value":"{\n let i = 0;\n yield i;\n let interval = setInterval(() => {\n i++;\n }, 1000);\n try {\n while (true) {\n yield i;\n }\n } finally {\n clearInterval(interval); // but dispose if re-evaluated.\n }\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":30,"value":"md`This way is technically better: it only yields a value when the value changes, but then again you're having to use some standard library methods to make it all fit together.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":32,"value":"Generators.observe(notify => {\n let i = 0;\n notify(i);\n let interval = setInterval(() => notify(++i), 1000);\n return () => clearInterval(interval);\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":44,"value":"mutation = md`## Mutation\n\nNotebooks work better and are much more understandable if you keep _mutation_ to a minimum. Mutation being defined here as ‘changing a variable in-place’: not creating a new variable that’s some modification of an old one, but instead changing the original variable's value. Some common sources of mutation in JavaScript are:\n\n- Array methods like .sort() and .splice() that modify arrays in-place\n- Similar methods on custom objects that modify them\n- Stateful regular expression methods\n\nFor example, here’s a notebook that has a cell that defines an array, another that mutates that array in-place by splicing out an element from it.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":49,"value":"// Run this cell\na = [1, 2, 3, 4]","pinned":true,"hidden":false,"mode":"ojs"},{"id":52,"value":"// Then run this cell a few times\na.splice(0, 1)","pinned":true,"hidden":false,"mode":"ojs"},{"id":56,"value":"// Then run this one\na.length","pinned":true,"hidden":false,"mode":"ojs"},{"id":64,"value":"$32","pinned":false,"hidden":false,"mode":"ojs"},{"id":74,"value":"b = [1, 2, 3, 4]","pinned":true,"hidden":false,"mode":"ojs"},{"id":76,"value":"c = {\n let copy = b.slice();\n copy.splice(0, 1);\n return copy;\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":81,"value":"c.length","pinned":true,"hidden":false,"mode":"ojs"},{"id":86,"value":"md`Now, it doesn’t matter how many times you evaluate the cells - they all end up with exactly the same values, because you aren't mutating any data in-place.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":272,"value":"md`Let’s also talk about objects! If you have some object and then _assign_ to some property of it, you have untracked mutation, which is usually bad.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":275,"value":"myObject = ({hi:'Tom'})","pinned":true,"hidden":false,"mode":"ojs"},{"id":280,"value":"myObject.key = Date.now()","pinned":true,"hidden":false,"mode":"ojs"},{"id":284,"value":"myObject","pinned":true,"hidden":false,"mode":"ojs"},{"id":287,"value":"md`As you can see by running them, these cells interact with each other in a way that the notebook can’t track: running the second one doesn’t update the results in the third, because we don’t statically track mutation.\n\nLuckily, there are simple ways to avoid this: following, again, the rule that if you want to get a modified object, it should be a new object, not a modification of the one you have. [Spread syntax](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax), noted as ... in code, makes this great:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":290,"value":"myObjectWithKey = ({ key: Date.now(), ...myObject })","pinned":true,"hidden":false,"mode":"ojs"},{"id":300,"value":"md`This new variable - myObjectWithKey - is myObject _plus_ some other properties.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":309,"value":"md`Now, lots of common cases you don't need a library, but if you are dealing with modifying objects and arrays a lot, you may want to use something like [lodash](https://lodash.com/docs/4.17.5), which lets you avoid mutation by providing lots of useful functions. For example, here's using lodash to create another object based on myObjectWithKey that _lacks_ a property.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":312,"value":"_ = require('lodash')","pinned":false,"hidden":false,"mode":"ojs"},{"id":315,"value":"myObjectWithoutHi = _.omit(myObjectWithKey, 'hi')","pinned":true,"hidden":false,"mode":"ojs"},{"id":319,"value":"md`Avoiding mutation is important for working with Observable, but it’s not just some quirk of our system: it’s a good practice in general, and sticking these principles tends to yield better code regardless of where you’re working, whether in a web application, server programming, or in the API of a module.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":92,"value":"md`## Generators\n\n- Don't use \\`return\\` in a generator that crosses cell boundaries.\n\nGenerators are a very rich JavaScript feature, with lots of subtle techniques. There are, though, some ways to use them ‘wrong’ in the Observable context. The first thing is: **the return value of a generator is ignored**, so don't \\`return\\` from a generator. Here’s an example: a counter that should go up to 10.\n\nSo, each iteration of the \\`for\\` loop yields 0, 1, 2…, and then you might expect the last statement - \\`return i\\` to print \\`10\\`. But it doesn’t, because it’s a return, not a yield.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":95,"value":"{\n let i = 0;\n for (; i < 10; i++) {\n yield i;\n }\n return i;\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":104,"value":"md`This, on the other hand, does what you expect: print numbers starting with 0 and ending with 10. Because it uses a yield, not a return, to yield the last value.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":98,"value":"{\n let i = 0;\n for (; i < 10; i++) {\n yield i;\n }\n yield i;\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":106,"value":"md`This advice is all about generators that _cross cell boundaries_. In a JavaScript sense, you should think of cell boundaries as calling \\`generator.next()\\` and ignoring its value if \\`done\\` is true: that's what they do internally.\n\nFor generators that _don’t_ cross cell boundaries, you _can_ use some of the places where the return value is important, like this one: the \\`yield*\\` statement produces the return value as the lvalue.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":113,"value":"{\n function* hasReturnValue() {\n yield 'a';\n yield 'b';\n return 'The result';\n }\n let finalValue = yield* hasReturnValue();\n yield finalValue;\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":128,"value":"reselectingElements = md`## Re-selecting elements\n\nIn many notebooks, you’ll be adding elements to a page and later manipulating them. If it’s a d3 chart, you might add a \\`\\` group, and then place some bars and lines and other graphical elements inside of it.\n\nOnce you create an element, there are generally two ways to get a reference to it again in another cell:\n\n1. Using the variable it was assigned to.\n2. Selecting it again based on a class, id, or tag name - with \\`d3.select()\\`, \\`document.querySelector()\\`, or another function that lets you query the page for an element.\n\n_Note that this advice only applies for getting elements out of nowhere - you will still likely use sub-selectors to select within elements you already have references to. It also doesn't apply to using \\`d3.select()\\` with a variable as its argument, only with a string._\n\nIt’s almost always preferable to do the former, not the latter. Here's an example of doing it the not-very-great way:\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":140,"value":"html`

`","pinned":true,"hidden":false,"mode":"ojs"},{"id":143,"value":"document.querySelector('#my-fun-element').innerText = 'What a fun element!'","pinned":true,"hidden":false,"mode":"ojs"},{"id":151,"value":"$33","pinned":false,"hidden":false,"mode":"ojs"},{"id":158,"value":"myElement = html`

`","pinned":true,"hidden":false,"mode":"ojs"},{"id":161,"value":"myElement.innerText = 'This is my element and I know this will work always and forever'","pinned":true,"hidden":false,"mode":"ojs"},{"id":176,"value":"md`An example of this technique with d3:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":184,"value":"chart = {\n const svg = d3.select(DOM.svg(width, 100));\n const x = d3.scaleLinear().range([0, width]);\n const y = d3.scaleLinear().range([20, 80]);\n \n svg.append(\"path\")\n .datum(d3.range(0, 1, 0.001).map(() => Math.random()))\n .attr(\"fill\", \"none\")\n .attr(\"stroke\", \"steelblue\")\n .attr(\"stroke-width\", 1.5)\n .attr(\"stroke-linejoin\", \"round\")\n .attr(\"stroke-linecap\", \"round\")\n .attr(\"d\", d3.line()\n .x((d, i) => x(i * 0.001))\n .y(y));\n \n return svg.node();\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":228,"value":"viewof randomize = html``","pinned":true,"hidden":false,"mode":"ojs"},{"id":221,"value":"randomize, d3.select(chart).select('path').attr('stroke', `hsl(${Math.random() * 100}, 100%, 50%)`)","pinned":true,"hidden":false,"mode":"ojs"},{"id":167,"value":"md`Note how we use _d3_.select to get a reference to the chart, but instead of selecting it based on the fact that it’s an svg element, or by its ID, we use the cell variable - \\`chart\\`. _d3_.select isn't a code smell - using it too broadly is. And we use \\`.select('path')\\` as a sub-selection: we can be sure that it'll only select \\`path\\` nodes within that chart, not elsewhere on the page, or within other cells.\n\nThere are other advantages to avoiding selectors. Selectors can easily get you in a trap with **uniqueness**: it's easy to write broad selectors like \\`d3.select('g')\\` and assume that they'll just select your chart's \\`\\` - but then you add more charts and end up accidentally selecting those too. Same goes for selecting by class names - you might add another element with the same class in the future.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":179,"value":"d3 = require('d3@4')","pinned":false,"hidden":false,"mode":"ojs"}],"files":"$W34","stdlib":"1","titling":"auto"}