subtleGradient/idiomatic-web-naming.html

## idiomatic-web-naming.html
<html>
<!-- It's normal NOT TO indent the children of the html element -->

<body>
<!-- It's normal NOT TO indent the children of the body element -->

<div style="background-color: lime" data-moo-mar-maz="abc123" id="abc123">
  <!-- It's normal TO indent the innards of almost all HTML elements -->
  Hello World.
</div>

<!-- It's normal NOT TO indent the contents of PRE tags -->
<pre>Hello
World!</pre>

<style>
/* It's normal NOT TO indent the CSS inside style tags */
div#abc123[data-moo-mar-maz="abc123"] {background-color: lime}
</style>

<script>
// It's normal NOT TO indent the code inside script tags

const COLOR_MOO_MAR = 'blue';

let element = document.getElementsByTagName('div')[0];
element.style.backgroundColor = COLOR_MOO_MAR;
element.dataset.mooMarMaz = 'def234';
</script>

## idiomatic-web-naming.md

      
    Raw
  

              idiomatic-web-naming.md
            
          
    Web Naming Conventions


normal == idiomatic

expressions that are natural to a native speaker


weird == idiosyncratic

something belonging characteristically or exclusively to some person, group, or thing

This is about language, not people. "Normal" web naming conventions are idiomatic. A web person knows the feel of HTML, CSS, and JS. Some things feel normal and natural, while other things feel unnatural and foreign. There are many dialects and sub languages within the web communities.
Naming styles. Normal and Weird

idiomatic vs idiosyncratic
Normal / idiomatic


lower-dash-separated is normal for HTML and CSS


aka lisp-case, spinal-case, kebab-case, dash-case, caterpillar-case


camelCase is normal for JS

These are often convertable.

The CSS background-color becomes backgroundColor in JS

but the HTML data-moo-mar-maz="123" becomes element.dataset.mooMarMaz = '123' in JS

JS can't use lower-dash-separated because in JS - is for doing math.

You can put it in quotes if necessary, but you'd better have a good reason because it's weird.

element.style.backgroundColor is the same as element.style['background-color']

Only used for specific things


UpperCamelCase normal for JS class names. (not normal for CSS class names, but some people like it)


e.g. Math, Date, RegExp, HTMLDListElement


UPPER_SEPARATED_BY_UNDERSCORES normal for JS constants. (super weird in HTML or CSS)


e.g. Math.SQRT1_2

Weird / idiosyncratic

I love weird stuff! But code is not exactly speech and not exactly a machine. The group responsible for long term maintainance of a codebase has the most important voice in deciding the paticular idiosyncratic choices of that codebase. If that's just you, go nuts, do whatever you like.
You don't need to remember all the weird stuff. But if you see this stuff, this may help you tell the difference between valid idiosyncratic choices vs stuff that is wrong and broken.
If you see anything that uses these styles, it should be a yellow flag that something unusual (idiosyncratic) is going on.

While many different ways of doing things (idiosyncracies) are technically possible, you may regret doing things differently from the group that you're trying to cooperate with. 1 Corinthians 10:23

lower_separated_by_underscores aka snake_case is technically valid in HTML, CSS, and JS, but it's just weird.

If you see this, it's probably safe to assume that whomever wrote this code is either new to client-side web programming or prefers some other programming language where snake_case is idiomatic


-lower-dash-separated-starting-with-a-dash is only(?) used for browser-specific css property names

e.g. -webkit-border-vertical-spacing


--lower-dash-separated-starting-with-two-dashes is for CSS Variables (Custom Properties), but CSS Variables aren't supported in IE11
camelSnake_hybrid or camelSnake__hybrid is sometimes used for JS method names for very specific reasons. If the context doesn't make it obvious, ask the person who originally wrote the code.
_camelCaseStartingWithAnUnderscore is often used in JS for quasi-private property/method/variable names

This has been hotly debated in the JS community forever
If you see this, assume that you're not supposed to use it
_ underscore by itself is usually Lodash or maybe Underscore or maybe a placeholder variable that should be ignored


$camelCaseStartingWithADollarSign

$ by itself is almost always jQuery


dash-case-with-123-numbers this is weird. I don't know why off the top of my head. It's probably fine I guess?

Other stuff not related to naming


Debating code style is weird in 2018

This was marely acceptable in 2006, but today it is almost never tolerated

We have tools such as Prettier that make it easy for teams to choose a style and stick to it or safely change the style of an entire codebase


Indenting with tabs (\t characters) is uncommon

Back in 2007 it was normal for much of the MooTools community


Indenting with 4 spaces is less common, but not particularly weird

AFAIK most people indent with 2 spaces these days


JavaScript with minimal semicolons is less common, but some people prefer it
CRLF newlines are normal on Windows, but weird on Mac and Linux

Most version control software will solve this for you


Invalid, old, or broken in some way

Don't try it. It's not worth it. The reasons why are interesting, but not very useful.

000CamelCaseStartingWithANumber
123-dash-case-starting-with-numbers
UPPER-DASH-SEPARATED normal for 1996 style HTML. If you see this, be afraid!

e.g. <BODY BGCOLOR=WHITE TEXT=BLACK LINK=RED VLINK=MAROON ALINK=FUCHSIA><H1 ALIGN=CENTER><BLINK> All that and a bag a chips! NOT! </BLINK></H1>


Terminology -- how to talk about specific stuff

HTML tags, elements, and nodes

All elements are nodes, but not all nodes are elements. HTML tag(s) define an element, but not always.
HTML "tags" are for creating elements

Tags are not elements in the same way that blueprints are not an office building. Any given office building probably had blueprints. But maybe it didn't. Elements may have originally been defined by tags. But maybe the elements were created with JS without using any tags. Or maybe the browser just created the elements for you because it was The Right Thing To Do.
Examples of HTML tags

<div> is an opening div tag
</div> is a closing div tag
<br /> is a self-closing break tag (aka "break tag")
</br> is nonsense. Break tags don't need to be closed.

If you did stuff like this back in 2006, it would cause unspeakably insane bugs and inconsistencies that are nearly impossible to diagnose. I've seen things. Things you wouldn't believe. The horror. THE. HORROR. /me stares into the middle-distance for 45 minutes, muttering incoherantly


<br> is also a break tag

HTML parsers have no trouble with this. This is fine. Really. Really! However, the self-closing style is preferred.

It is preferred by many people who could go on and on about why they prefer this style at length. I am one of those people.
Using this style of break tag feels tantalizingly exciting and dangerous to people who were once passionate about XHTML but became disillusioned and are having trouble completely accepting the fact that HTML5 is a thing and that 2003 browsers were marely tolerating our unnecessary slashes while alternately scratching their heads or rolling their eyes while smiling at us condescendingly. "Aww, look at those adorable webdevs!" Firefox would say, "they think they're speaking our language." "Adorable!" Internet Explorer would agree. "But what's a 'burr-slash'? AND WHERE'S THE CLOSING BURR-SLASH?!"


<br/> is worse than <br> because some ancient browsers saw this as an opening br/ ("burr slash") tag (which is obviously insane nonsense). Or maybe it was </br> that caused this bug. I'm not sure if I should be thrilled or ashamed that I don't remember. /me resists the urge to read through the Slick.js git history

This is probably fine in 2018, but it still makes me feel very uncomfortable. It's like a curse word that is suddenly inexplicably acceptable in modern english. I'm not going to shame you for saying it, but it would be good for you to know why it causes some people (not me!) to react with seemingly extreme passionate violent rage.
Using the "burr slash" (vs "bee arr space slash" aka "break tag") style of break tag will out you as someone who has no war stories about the horrors (and shameful nostalgic delight) of IE5 development of yesteryear


<BR>

Yes, I am very interested in seeing your Alf pog collection


Examples

dataset / data attributes


English "The moo mar maz data attribute of a div tag"
HTML <div data-moo-mar-maz="111 222 333"></div>
CSS Selector

[data-moo-mar-maz] all elements with the data-moo-mar-maz attribute with any value or no value
[data-moo-mar-maz="123"] all elements whose data-moo-mar-maz attribute's value is exactly 123
[data-moo-mar-maz*="2"] all elements whose data-moo-mar-maz attribute's value contains 2 anywhere
[data-moo-mar-maz^="1"] all elements whose data-moo-mar-maz attribute's value starts with 1
[data-moo-mar-maz$="3"] all elements whose data-moo-mar-maz attribute's value end with 3
[data-moo-mar-maz~="222"] all elements whose data-moo-mar-maz attribute's value contains the word 222


JS

Get elements: document.querySelectorAll(myAwesomeCSSSelector)
Get an element's data-moo-mar-maz attribute value

element.dataset.mooMarMaz good
element.getAttribute('data-moo-mar-maz') bad


Set an element's data-moo-mar-maz attribute value

element.dataset.mooMarMaz = "Howdy!" good
element.setAttribute('data-moo-mar-maz', "Ahoy") bad


Concepts

Languages/Syntaxes/Grammars


HTML
HTML datasets data- attributes

Defined in HTML
Used in CSS and JS


CSS
CSS Selectors

Used in CSS and JS


CSS Styles

Used in CSS and HTML style attribute values


JS

Names of things

HTML


tag
node
element
attribute

id
class
data attribute


parent/sibling/child

CSS


CSS selector

id, class, attribute, pseudo-class, pseudo-element


id

CSS Selector #moo-mar-maz
HTML <br id="moo-mar-maz" />
JS element.id good
JS element.getAttribute('id') bad


class

CSS Selector .moo-mar-maz
HTML <br class="moo-mar-maz" />
JS element.className

A JS "class" and an HTML/CSS "class" are completely different concepts, so an HTML/CSS class is called className in JS


style attribute / value

example 1

name: background color
value: lime
Usage

HTML <br style="background-color:lime" />
CSS br {background-color:lime}
JS element.style.backgroundColor = 'lime'; good
JS element.style['background-color'] = 'lime'; bad


JS


JS variable -- make them, use them, change them

let mooMarMaz = 123;
var mooMarMaz = 123; old
e.g. window; document; mooMarMaz


JS constant -- make them, use them, NEVER change them

const MOO_MAR_MAZ = 123;
var MOO_MAR_MAZ = 123; old
e.g. Math.SQRT1_2


JS class -- make them, subclass them, instantiate them

class Animal {}
class CowOrWhatever extends Animal {}
let fred = new CowOrWhatever();


JS property

element.style CSSStyleDeclaration instance
element.dataset DOMStringMap instance
style.backgroundColor String instance
style['background-color'] String instance
dataset.mooMarMaz String instance
element.height String instance
JS method

document.getElementsByTagName('div') returns an HTMLCollection instance
123.456.toString() returns a String instance
Math.random() returns a number
element.getAttribute('data-moo-mar-maz') returns a String instance
	<html>
	<!-- It's normal NOT TO indent the children of the html element -->

	<body>
	<!-- It's normal NOT TO indent the children of the body element -->

	<div style="background-color: lime" data-moo-mar-maz="abc123" id="abc123">
	<!-- It's normal TO indent the innards of almost all HTML elements -->
	Hello World.
	</div>

	<!-- It's normal NOT TO indent the contents of PRE tags -->
	<pre>Hello
	World!</pre>

	<style>
	/* It's normal NOT TO indent the CSS inside style tags */
	div#abc123[data-moo-mar-maz="abc123"] {background-color: lime}
	</style>

	<script>
	// It's normal NOT TO indent the code inside script tags

	const COLOR_MOO_MAR = 'blue';

	let element = document.getElementsByTagName('div')[0];
	element.style.backgroundColor = COLOR_MOO_MAR;
	element.dataset.mooMarMaz = 'def234';
	</script>