cloudfour / cloudfour/guides

Add section about documenting magic numbers

Open
#73 0 comments 1 reaction 0 assignees View on GitHub
enhancement
Dominant language
No language data
Stars
24
Forks
1
PR merge metrics
No merged PRs in 30d

Description

@spaceninja wrote this in a PR comment thread about why we prefer to convert "magic numbers" into variables. We should add a section rephrasing this to the CSS Guide:

> Magic numbers in CSS files are a mystery. Why is it this particular value? What happens if I change it? Does it match anything else?

> Turning your magic numbers into variables or custom properties is a form of documentation and safety checks:

> By naming your number, you help explain what it means. $touch-target-size tells you at a glance what the number means and opens the door to reuse elsewhere.

> It's also a form of safety check — if you set this value here and then it also gets used somewhere else but both locations are hard-coded, then a future dev doesn't know they need to update both if we want those sizes to match.

> Thus, as a general practice, unless we have good reason, we convert almost all values to variables, custom properties, or design tokens.

> Sometimes you really do have a special one-off magic number. "The component is sized at 137px wide because that's the only size that looks good". In those cases, when you don't need to reuse the value, then a descriptive comment explaining the source of the magic number is sufficient.

> But in general, coming across a magic number with an unclear meaning and source is a red flag in a CSS file.

> In almost every instance, I have found that what felt arbitrary made more sense when converted to a standard design token that already exists, or by documenting it so it could be reused.

> In this case, your magic number is a very good one that can and should be reused elsewhere — minimum touch target size! That's a great case for making a design token, or at least a variable.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.