Add section about documenting magic numbers

Đang mở
  • Có gì không ổn?
#73 0 bình luận 1 reaction 0 người được giao Xem trên GitHub

Chưa có ai nhận issue này.

Đánh giá

Độ khó
1/5
Thời gian dự kiến
1-3 giờ
Mức phù hợp với người mới
48/100
Loại issue
Tài liệu
Độ rõ ràng
Khá rõ ràng
Mức độ hoạt động
Đình trệ
Công nghệ
css
Lĩnh vực
documentation

Hướng nghiên cứu

Xác định CSS Guide trong repository và xem xét cấu trúc các phần cũng như phong cách hiện có của tài liệu. Thêm một phần diễn đạt lại hướng dẫn đã cung cấp về việc ghi chú magic numbers, biến, custom properties, design tokens và các chú thích mang tính mô tả; công việc được xem là hoàn tất khi hướng dẫn được tích hợp rõ ràng mà không thay đổi nội dung không liên quan.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

enhancement

@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.

Ngôn ngữ chính
Không có dữ liệu ngôn ngữ
Star
24
Fork
1
Merge trung bình
3 giờ 48 phút
Pull request đã merge (30 ngày)
1

Chuẩn bị môi trường

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của cloudfour/guides

Tất cả issue của cloudfour/guides

Issue tương tự

Thêm issue về Documentation

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.