Add section about documenting magic numbers
まだ誰も着手していません。
評価
- 難易度
- 1/5
- 見積もり時間
- 1〜3時間
- 初心者へのやさしさ
- 48/100
- issue の種類
- ドキュメント
- 明瞭さ
- おおむね明確
- 活発さ
- 停滞
- 技術スタック
- css
調査の方向性
リポジトリ内の CSS Guide を特定し、既存のセクション構成とスタイルを確認します。magic numbers、変数、custom properties、design tokens、説明的なコメントのドキュメント化に関して提供されたガイダンスを言い換えるセクションを追加します。関連のない内容を変更せず、ガイダンスが明確に統合されていれば完了です。
索引モデルが issue の本文から書いたものです。
説明
@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.
- 主要言語
- 言語のデータがありません
- スター
- 24
- フォーク
- 1
- 平均マージ
- 3時間 48分
- マージ済み PR（30日）
- 1
環境構築
- Dockerfile・Docker Compose ファイルなし
- プルリクエストのテンプレートなし
- コントリビューションガイドを読む
はじめの一歩
- issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
- 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
- リポジトリをフォークし、ブランチを切って変更します。
- issue 番号を参照したプルリクエストを送ります。
cloudfour/guides のほかの issue
-
難易度 3/5 1〜2日 初心者へのやさしさ 35/100
-
enhancement
難易度 2/5 1〜3時間 初心者へのやさしさ 35/100
-
難易度 3/5 1〜2日 初心者へのやさしさ 25/100
-
難易度 2/5 1〜2日 初心者へのやさしさ 45/100
-
Add a Web Accessibility Guide再び着手できるかも @gerardo-rodriguez が 2392 日前に担当しましたが、オープン中のプルリクエストはありません。 オープン
cloudfour/guides の issue をすべて見る
似ている issue
-
Windows docs: pin a tested ConPTY version for Kitty graphics; 1.25.260930003 corrupts large uploadsオープン
難易度 1/5 1〜3時間 初心者へのやさしさ 88/100
raphamorim/rio#2021 ·
メンテナーはふだん 1 日以内に返信
-
sync-en
難易度 1/5 1〜3時間 初心者へのやさしさ 84/100
メンテナーはふだん 1 日以内に返信
-
sync-en
難易度 1/5 1時間未満 初心者へのやさしさ 76/100
メンテナーはふだん 1 日以内に返信
-
area:docs phase:release priority:p0 type:test
難易度 2/5 1〜3時間 初心者へのやさしさ 66/100
-
Перевод устарел
難易度 1/5 1時間未満 初心者へのやさしさ 62/100