رویکردهای مستندسازی در CSS

مستندسازی در CSS

مستندسازی در CSS یکی از مهم ترین مقوله های این حوزه است. در دنیای سی اس اس معمولا به صورت نادرستی از مستندسازی استفاده می شود. از آنجایی که مستندات در سی اس اس توسط کاربر نهایی دیده نمی شود به همین دلیل اغلب اوقات نادیده گرفته می شود. البته در کنار این موارد اگر شما برای اولین بار است که کدهای تان مستندسازی می کنید برای تان بسیار سخت خواهد بود که چه چیزی را مستند کنید و اینکه چگونه به صورت کارا و مفید این کار را انجام دهید.

مستندسازی CSS شما می تواند تاثیر بسیار زیادی روی پروژه شما داشته باشد: از تشویق برای رویکردهای کدنویسی بهتر تا آوردن اعضای جدید به فایل های تان. در این مقاله قصد دارم به شما مزایا مستندسازی سی اس اس را توضیح دهم و مواردی که در تیم و در Bitoviروی آن ها کار کرده ایم را با شما به اشتراک بگذارم. بیاید شروع کنیم.

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

قواعد اساسی را تعیین کنید

کار کردن روی مستندسازی در ابتدا برای شما و تیم تان بدون اینکه بدانید چه چیزی را می خواهید مستندسازی کنید و اینکه چگونه می خواهید عمل نماید، واضح نیست. بنابراین اولین مرحله برای شما این خواهد بود که چه قراردادها و اعمالی می خواهید تعیین کنید تا در آینده از آن ها استفاده نمایید و اینکه چگونه می خواهید آن ها را به فاز اجرا دربیاورید.

 می توانید این کار را روی یک مستند زنده انجام دهید که هر کسی می تواند در تیم می تواند روی آن مشارکت انجام دهد. بعد از آنکه رویکردهای شما تغییر کرد و جامع شدند، می توانید آن ها را بروز نگه دارید. استفاده از مستند Google Doc به صورت اشتراکی، یا یک صفحه ویکی و یا یک صفحه در «راهنمای روش زنده تان» راه های بسیار مناسبی برای این کار است.

حال بیاید نگاهی به قاعد اساسی که می توانید شامل مستندسازی کنید، بیاندازیم.

ساختار پایه ای کدهای تان را تشریح کنید

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

بعد از انجام اینکار، حال بهتر است توجه بسیار ویژه ای به مکان هایی بیاندازید که ممکن است جای ابهام داشته باشند. برای مثال نشان دادن اینکه در فایل button.css محتویاتی برای استایل دهی به دکمه ها وجود دارد خیلی کمک کننده نیست، بجای آن می توانید پوشه custom را نشانه بگذارید و بگویید اینجا استایل های سفارشی مربوط به وبسایت قرار گرفته است.

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

یکی دیگر از المان های مهم این است که به هر جایی که استایل جدید به آن اعمال می شود باید نگاه کنیم و هر مرحله جدیدی که اضافه می شود باید به آن اشاره داشته باشیم. در مثال بالا این حالت به درستی توضیح داده شده است، اما با توجه به ماهیت سی اس اس بسیار مناسب خواهد بود اگر بتوانیم این اطلاعات را در قسمت جزئیات بنویسیم.

استانداردهای کدنویسی تان را ایجاد کنید

استانداردهای کدنویسی تان یا راهنما های استایل سی اس اس راهی -توافقی- برای نوشتن کدهای CSS توسط دیگر اعضای گروه است. این موارد معمولا شامل بهترین رویکردها برای نوشتن کدها می شود که شامل قالب بندی، نام گذاری، سینتکس و… می شود. بسیاری از شرکت ها روش هایی که استفاده می کنند را به اشتراک می گذراند .در اینجا چند مورد وجود دارد که برای ساخت شیوه استایل تان بسیار مفید است: لیست «انجام بدهید» در مقابل «انجام ندهید»

از استایل های طولانی خودداری کنید

وقتی که فایل استایل تان را به فایل های کوچکتری تقسیم می کنید، مستندسازی روی آن ها بسیار ساده تر می شود. با این کار می توانید زمان بسیاری را ذخیره نمایید و نیازی به شفاف سازی در رابطه با مستندات مختلف نیستید.

برای مثال بجای اینکه یک ۸۰۰ خط کد استایل داشته باشید که در آن تمام متغیر های داخل پوسته تان استایل دهی شده اند می توانید برای هر متغیر یک فایل جداگانه را طراحی نمایید. این کار زمان شما را ذخیره می کند و پیدا کردن آنچیزی که می خواهید را ساده تر می نماید. همچنین به میزان زمان آپلود کل فایل در هر زمان که می خواهید تغییری را ایجاد کنید فکر نمایید.

CSS را همراه با یک راهنمای استایل در ذهن مستندسازی کنید

یکی از راه های دست یابی به یک نقطه مهم در مستندسازی سی اس اس، کدنویسی خود سی اس اس است. منظورمان این است که ممکن است پایه بسیار خوبی برای انجام این کار نداشته باشید اما اجبار برای پیاده سازی قواعد مستندسازی می تواند شما را برای داشتن یک سیستم بهتر ترغیب نماید.

اینجاست که مستندسازی سی اس اس با یک راهنمای سبک در ذهن به سراغ شما می آید. ایده پشت این قضیه این است که یک راهنمای استایل می تواند به شما برای پیاده سازی یک ساختار خوب برای سی اس اس تان کمک می کند، به این دلیل که برای ساختن یک مورد شما نیاز دارید تا بتوانید بین موارد زیر تمایز قائل شوید:

  • استایل اصلی که ظاهر و احساس اپلیکیشن تان را خلق و تعریف می کند (مانند هر فریمورک سی اس اس که شما از آن استفاده می کنید).
  • شخصی سازی انجام شده برای یک کامپوننت خاص
  • شخصی سازی که برای یک صفحه خاص انجام شده است.

استایل شیت های تان را به بخش های دیگری تقسیم کنید

بعد از اینکه فایل استایل مان را به فایل های کوچکتری با قابلیت مدیریت پذیری بالا تبدیل کردیم، حال نوبت آن است که به این کوچک سازی با استفاده از قرار دادن آن ها در بخش های کوچکتر ادامه دهیم.  برای شروع کار با این موضوع هر استایلی باید حداقل شامل یک عنوان و یک توضیح مختصر و کوتاه باشد.

عنوان این قسمت باید مانند نام آن ساده، قابل درک باشد و با حرف اول بزرگ نوشته شده باشد تا بتواند بهتر نمایش یابد، برای مثال عبارت «Buttons» برای فایل «button.css». البته این عنوان می تواند درست مانند نام فایل نیز باشد.

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

محتوای فایل استایل تان را شاخص گذاری کنید

درست کردن یک تصویر کلی از اینکه درون فایل استایل تان چه چیزهایی قرار دارد بسیار مهم و کاری مناسب است. به همین دلیل است که استایل شیت های طولانی هنوز پابرجا هستند (این موضوع برای چنین فایل هایی اهمیت دوچندانی خواهد داشت).

با وجود آنکه آن ها فوق العاده مفید هستند اما باید اقرار کنم که به سادگی توسط افراد مختلف فراموش می شوند. همچنین بروزرسانی کردن آن ها نیز وقتی قسمت جدیدی به استایل اضافه می شود یا یک ویرایش کلی صورت می گیرید بسیار سخت و زجرآور است.

یکی دیگر از راه های برای قرار دادن شاخص ها در فایل استایل شیت تان این است که به سازنده فایل راهنمای سی اس اس این اجازه را بدهید تا فایل شما را مشاهده کند و براساس آن با پیدا کردن بخش هایی که ایجاد نموده اید، شاخص گذاری را برای تان ایجاد کند.

پیدا کردن قسمت شیرین از مستندسازی

اینجاست که راز مستندسازی تبدیل به یک دروغ می شود. بسیار ساده است که به راحتی از مستندسازی فرار کنید و در نهایت شما بمانید و کدهای اولیه تان و قسمت های بزرگی که مستندسازی نشده اند. درست مانند هر چیز دیگری در زندگی راز، پیدا کردن بالانس و تعادل است. مستندات همان مکان هایی هستند که نیاز به توجه بسیاری دارند به این دلیل که آن ها همراه با پیام های مهم، منابع اپلیکیشن و مواردی از این دست می آیند.

 مطمئنا این بدان معنا نیست که هر کدی که نوشته اید را مستندسازی کنید اما مستندسازی در کل بسیار مهم است و باید برای فایل های تان از آن استفاده کنید. پس مستندسازی باید بخشی از روند کاری تان باشد و نباید آن را فراموش کنید، اما چگونه این کار را به بهترین شکل انجام دهید؟

۰ پاسخ به "رویکردهای مستندسازی در CSS"

    ارسال یک پیغام

    نشانی ایمیل شما منتشر نخواهد شد. بخش‌های موردنیاز علامت‌گذاری شده‌اند *

    ارتباط با کافه بلوط

    آدرس : خراسان جنوبی ، بیرجند ، پارک علم وفناوری خراسان جنوبی ، اتاق 101
    آدرس ایمیل: dp.cafebaloot@gamil.com

    logo-samandehi دروازه پرداخت معتبر

    All Right Reserved For Cafe Baloot 2018

    X