آموزش و یادگیری نحوه نوشتن توضیحات در CSS

قبل از هر چیز مرجع نمونه را ببینید: توضیح تگ details در HTML. (تفاوت ساختار مقالات ما با آن لینک: مقالات ما داخل <article class="html-lesson"> قرار می‌گیرند و بخش‌ها با <h2>، <pre><code>، <strong> و <span style="color:red;"> برای تأکید نوشته می‌شوند.) در مقدمه اگر دنبال دورهٔ ساختاریافته هستید، حتماً به دوره آموزش CSS سر بزنید.

چرا نوشتن توضیحات (کامنت) در CSS مهم است؟

توضیحات یا کامنت‌ها باعث می‌شوند کد شما خواناتر، قابل نگهداری‌تر و قابل درک برای دیگر توسعه‌دهندگان شود. در پروژه‌های تیمی و هنگام بازگشت به یک پروژه قدیمی، کامنت‌های خوب زمان زیادی صرفه‌جویی می‌کنند.

نحوه نوشتن کامنت در CSS

در CSS از سینتکس چندخطی استفاده می‌شود:

/* این یک کامنت تک‌خطی یا چندخطی در CSS است */

نمونه مستندسازی کامپوننت:

/* Component: Card
   Usage: .card .title
   Notes: responsive padding, uses --card-bg */
.card {
    background: var(--card-bg);
    padding: 1rem;
}

الگوهای مفید برای کامنت‌گذاری

• Header برای توضیح فایل: نام، نگهدارنده، ورژن و تاریخ.
• Component Block برای هر کامپوننت: نام، کاربرد و وابستگی‌ها.
• TODO / FIXME برای مواردی که نیاز به پیگیری دارند: /* TODO: refactor responsive padding */.

مثال‌های عملی و نکات نگارشی

مثال توضیح یک بخش و جداکننده بین بخش‌ها:

/* ===========================
   Layout - Header
   =========================== */
.header { ... }

/* Component: Button
   Variant: primary, size: md */
.btn--primary { ... }

نکات:

• از کامنت‌های کوتاه و مفید استفاده کنید؛ توضیحات طولانی را برای مستندات جداگانه نگه دارید.
• از نشانه‌گذاری یکنواخت (مثلاً استفاده از همان الگوی Header) برای خوانایی استفاده کنید.
• از TODO و FIXME برای پیگیری کارهای نیمه‌تمام استفاده کنید.

ابزارها و اتوماسیون مرتبط با کامنت

• Stylelint: می‌تواند وجود یا فرمت کامنت‌ها را بررسی کند و قوانین دلخواه شما را enforce کند.
• Prettier: فرمتینگ کلی کد (کامنت‌ها را نیز در قالب ثابت نگه می‌دارد).
• در فرآیند CI می‌توانید چک کنید که فایل‌ها دارای header موردنظر (مثلاً license یا metadata) باشند.

قواعد پیشنهادی برای تیم‌ها

خطاهای رایج هنگام نوشتن کامنت

• استفاده از کامنت‌های قدیمی و نادرست: همیشه کامنت را همزمان با تغییر کد بروزرسانی کنید.
• نوشتن کامنت‌های زائد و تکراری که باعث شلوغی می‌شوند — «کامنت کمتر و مفیدتر» بهتر است.
• گذاشتن اطلاعات حساس یا بزرگ در کامنت (مانند کلیدها) — این اطلاعات نباید در کد منبع قرار گیرند.

ادامه آموزش

برای نمونه‌های بیشتر و بهترین شیوه‌ها در پروژه‌های واقعی، به دوره آموزش CSS مراجعه کنید. این لینک در مقدمه هم درج شده تا دسترسی راحت‌تری داشته باشید.