فهرست محتوا

قانون طلایی

Every line of code should appear to be written by a single person, no matter the number of contributors.

همیشه از این قوانین یا موارد شخصی خودتان استفاده کنید. هر خطای کوچک یا بزرگی بود آن را گزارش دهید. در صورت داشتن هرگونه نظر ، پیشنهاد ، انتقاد یا مشارکت یک Issue ثبت کنید.

HTML

<!doctype html>
<html>
  <head>
    <title>Page title</title>
  </head>
  <body>
    <img src="images/company-logo.png" alt="Company">
    <h1 class="hello-world">Hello, world!</h1>
  </body>
</html>

ترکیب

  • از حروف بزرگ برای تگ ها استفاده نکنید ( همچنین برای doctype )
  • برای جلو بردن کدها از tab معادل 2 فاصله خالی استفاده کنید
  • کدهای زیرمجموعه فقط باید یک بار جلو بروند ( معادل 2 فاصله خالی )
  • برای مقادیر تگ های همیشه از ( " ) استفاده کنید نه ( ' )
  • برای المان های مستقل مانند ( <img> ) از اسلش استفاده نکنید — در HTML5 این مورد اختیاری می باشد
  • تگ های اختیاری پایانی را حذف نکنید ( مانند </li> یا </body>)
<!doctype html>
<html>
  <head>
  </head>
</html>

نوع سند HTML5

اجرای حالت استاندارد و رندر گیری بهتر در هر مرورگی با قراردادن این تگ در ابتدای هر فایل HTML انجام خواهد شد.

<html lang="en">
  <!-- ... -->
</html>

ویژگی lang

با استفاده از این ویژگی در تگ <html> به ابزارهای سینتکس یا ترجمه کمک می کنید که زبان محتوای وب سایت شما را دریافت کرده و متناسب با آن به کاربران خدمات دهند.

<meta http-equiv="x-ua-compatible" content="ie=edge">

سازگاری با Internet Explorer

مرور گر Internet Explorer یک تگ <meta> دارد که با استفاده از آن می توانید مشخص کنید این مرورگر از کدام نسخه برای رندرگیری صفحات استفاده نماید. در صورتی که تنظیمات خاصی برای این مورد مد نظر ندارید ، می توانید از مقدار edge استفاده کنید تا همیشه آخرین نسخه اعمال شود.

جهت اصلاعات بیشتر , این صفحه از سایت Stack Overflow را مطالعه کنید.

<head>
  <meta charset="UTF-8">
</head>

رمزنگاری کارکتر ها ( رمزگذاری یونیکد )

با اعلام نوع کدگذاری می توانید به راحتی از ارائه صحیح محتوا به کاربران اطمینان پیدا کنید. هنگام انجام این کار ممکن است از استفاده اشخاص برای کارکتر های غیرمجاز نیست جلوگیری کنید تا مطمئن شوید داده های ورودی آن ها مطابق با وب سایت شما باشد. کدگذاری صفحات معمولا UTF-8 می باشد

<!-- External CSS -->
<link rel="stylesheet" href="code-guide.css">

<!-- In-document CSS -->
<style>
  /* ... */
</style>

<!-- JavaScript -->
<script src="code-guide.js"></script>

وارد کردن CSS و JavaScript

طبق قواعد HTML5 ، نیازی به تعریف ویژگی type برای فایل های جاوا اسکریپت یا CSS نیست. مانند text/css و text/javascript که این موارد به صورت پیشفرض اعمال شده و صحیح هستند.

لینک قواعد HTML5

صحیح و شفاف

همیشه برای حفظ استاندارد های HTML تلاش کنید. تا جای ممکن کدهایی با کمترین علامت گذاری و مشکل بنویسید

<a class="..." id="..." data-toggle="modal" href="#">
  Example link
</a>

<input class="form-control" type="text">

<img src="..." alt="...">

ترتیب ویژگی ها

ویژگی ها HTML جهت خوانا تر بودن کد باید به ترتیب قرار بگیرند.

  • class
  • id, name
  • data-*
  • src, for, type, href, value
  • title, alt
  • role, aria-*
<input type="text" disabled>

<input type="checkbox" value="1" checked>

<select>
  <option value="1" selected>1</option>
</select>

مقادیر Boolean

مقادیر صحیح / غلط مانند disabled ، checked یا selected نیازی به تعریف به عنوان مقدار یک ویژگی ندارند. زبان XHTML به تعریف این ویژگی ها نیاز داشت ولی اکنون در HTML5 می توانید آن ها را به صورت مستقل استفاده کنید.

برای مثال در گذشته عبارتی مانند disabled=disabled نیاز بود ولی اکنون می توانید آن را به این صورت بنویسید : disabled

<!-- Not so great -->
<span class="avatar">
  <img src="...">
</span>

<!-- Better -->
<img class="avatar" src="...">

کاهش تگ ها

تا جای ممکن تگ های اضافی در کد خود استفاده نکنید تا در پایان ، کد HTML کوتاه ، منظم و خوانا تری داشته باشید. برای مثال کد روبرو را نگاه کنید :

کدهای ایجاد شده توسط اسکریپت

کدهای HTML که توسط جاوا اسکریپت ایجاد می شوند ، ناخوانا بوده و در آینده پیدا کردن و ویرایش آن ها سخت تر خواهد بود. تا جای ممکن از این روش خودداری کنید.

CSS

/* Bad CSS */
.selector, .selector-secondary, .selector[type=text] {
  padding:15px;
  margin:0px 0px 15px;
  background-color:rgba(0, 0, 0, 0.5);
  box-shadow:0px 1px 2px #CCC,inset 0 1px 0 #FFFFFF
}

/* Good CSS */
.selector,
.selector-secondary,
.selector[type="text"] {
  padding: 15px;
  margin-bottom: 15px;
  background-color: rgba(0,0,0,.5);
  box-shadow: 0 1px 2px #ccc, inset 0 1px 0 #fff;
}

ترکیب

  • برای جلو بردن کدها از tab معادل 2 فاصله خالی استفاده کنید
  • وقتی که استایل ها را به صورت دسته ای اعمال میکنید ، اسامی انتخابگر ها را در یک خط بنویسید
  • جهت خوانا بودن بیشتر قبل از براکت شروع کننده ی بلک ، یک فاصله خالی بگذارید
  • براکت پایان دهنده ی بلاک را در یک خط جدید قرار دهید
  • بعد از هر علامت : برای ویژگی ها ، یک فاصله خالی بگذارید
  • جهت خطایابی بهتر ، هر تعریف را در یک خط جداگانه قرار دهید
  • در پایان هر خط تعریف ، یک ; علامت بگذارید ، آخرین خط اختیاری است ولی جهت خطایابی بهتر آن را بگذارید
  • ویژگی هایی که مقادیر آن ها چندگانه هستند و با علامت , از هم جدا می شوند ، پس از علامت یک فاصله خالی بگذارید. مانند ( box-shadow )
  • درون مقادیر آرایه ای مانند rgb(), rgba(), hsl(), hsla, یا ()rect از علامت , استفاده نکنید. در این صورت مقادیری که مربوط به رنگ هستند ، با دیگر مقادیر متمایز خواهند شد.
  • در اول مقادیر عددی از 0 استفاده نکنید ( برای مثال 5. به جای 0.5 و 5px.- به جای 0.5px- )
  • برای مقادیر رنگی HEX از حروف انگلیسی کوچک استفاده کنید ، مانند fff به هنگام مشاهده کد ، حروف کوچک راحت تر از یکدیگر تشخیص داده می شوند.
  • در صورت ممکن برای مقادیر رنگی HEX از عبارت خلاصه تر استفاده کنید. برای مثال fff به جای ffffff
  • به هنگام استفاده از ویژگی های یک تگ HTML در انتخاب گر ها ، مقدار آن را در " بگذارید. مانند input[type="text"]. در بعضی موارد آن ها اختیاری هستند.
  • برای مقادیر 0 از واحد ها استفاده نکنید و صرفا همان 0 خالی را بگذارید مانند margin: 0 به جای margin: 0px
.declaration-order {
  /* Positioning */
  position: absolute;
  top: 0;
  right: 0;
  bottom: 0;
  left: 0;
  z-index: 100;

  /* Box-model */
  display: block;
  float: right;
  width: 100px;
  height: 100px;

  /* Typography */
  font: normal 13px "Helvetica Neue", sans-serif;
  line-height: 1.5;
  color: #333;
  text-align: center;

  /* Visual */
  background-color: #f5f5f5;
  border: 1px solid #e5e5e5;
  border-radius: 3px;

  /* Misc */
  opacity: 1;
}

ترتیب ویژگی ها

در یک بلاک ، ویژگی هایی که در یک دسته بندی مرتبط وجود دارند باید به ترتیب قرار بگیرند :

  1. محل قرارگیری - Positioning
  2. ابعاد و حالت - Box model
  3. ویژگی های متنی - Typographic
  4. ویژگی ها ظاهری - Visual
  5. متفرقه - Misc

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

جهت مشاهده لیست کامل ویژگی ها و ترتیب قرارگیری آن ها به این صفحه مراجعه کنید.

<!-- Use link elements -->
<link rel="stylesheet" href="core.css">

<!-- Avoid @imports -->
<style>
  @import url("more.css");
</style>

از import@ استفاده نکنید

در مقایسه با <link> ، @import بسیار کند تر عمل می کند. این مورد باعث می شود درخواست های اضافی ثبت شود و خطایابی را بسیار سخت تر می کند. می توانید از راه های جایگزین استفاده کنید :

  • استفاده از چند <link> جداگانه
  • کل فایل های CSS را با استفاده از کتابخانه های پیش پردازنده مانند Sass یا Less کامپایل کرده و به یک فایل تبدیل کنید
  • در صورت استفاده از فریموورک هایی مانند Rails یا Jekyll می توانید تمام فایل های CSS خود را با یکدیگر الحاق کنید
.element { ... }
.element-avatar { ... }
.element-selected { ... }

@media (min-width: 480px) {
  .element { ...}
  .element-avatar { ... }
  .element-selected { ... }
}

انتخاب گر های media@

در صورت استفاده از این انتخاب گر ها ، آن ها در نزدیک ترین مکان به بلاک های مربوطه قرار دهید. هیچوقت آن ها را به صورت جداگانه در جای دیگر ( مثلا آخر کد ها - مانند خیلی از قالب های آماده که خریداری می کنید ) قرار ندهید. جهت سهولت در برنامه نویسی و خطایابی های آینده ، آن ها را کنار بلاک مربوطه استفاده کنید.

/* Prefixed properties */
.selector {
  -webkit-box-shadow: 0 1px 2px rgba(0,0,0,.15);
          box-shadow: 0 1px 2px rgba(0,0,0,.15);
}

ویژگی های پیشوند دار

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

/* Single declarations on one line */
.span1 { width: 60px; }
.span2 { width: 140px; }
.span3 { width: 220px; }

/* Multiple declarations, one per line */
.sprite {
  display: inline-block;
  width: 16px;
  height: 15px;
  background-image: url("../img/sprite.png");
}
.icon           { background-position: 0 0; }
.icon-home      { background-position: 0 -20px; }
.icon-account   { background-position: 0 -40px; }

تعریف های یک خطی

در صورتی که بلاک شما فقط یک ویژگی دارد , آن ویژگی و براکت ها را تنها در یک خط قرار دهید.

/* Bad example */
.element {
  margin: 0 0 10px;
  background: red;
  background: url("image.jpg");
  border-radius: 3px 3px 0 0;
}

/* Good example */
.element {
  margin-bottom: 10px;
  background-color: red;
  background-image: url("image.jpg");
  border-top-left-radius: 3px;
  border-top-right-radius: 3px;
}

حالت های خلاصه

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

  • padding
  • margin
  • font
  • background
  • border
  • border-radius

برای مثال نیاز نیست هنگام تنظیم ویژگی padding تمام جهات را مقدار دهی کنیم. زیرا به صورت پیشفرض 0 هستند.

با اینکار کدهای CSS خلاصه تر نوشته و از بازنویسی مقادیر پیشفرض خودداری می کنید.

// Without nesting
.table > thead > tr > th {  }
.table > thead > tr > td {  }

// With nesting
.table > thead > tr {
  > th {  }
  > td {  }
}

کدنویسی تو در تو برای Less و Sass

ار تو در تو کردن بی دلیل کدها خودداری کنید ، این که می توانید چنین کاری کنید دلیل کافی برای انجام دادنش نیست.

مطالعه بیشتر :

// Bad example
.element {
  margin: 10px 0 @variable*2 10px;
}

// Good example
.element {
  margin: 10px 0 (@variable * 2) 10px;
}

عملگر ها در Less و Sass

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

/* Bad example */
/* Modal header */
.modal-header {
  ...
}

/* Good example */
/* Wrapping element for .modal-title and .modal-close */
.modal-header {
  ...
}

نظرات درون کد

کدهای شما ممکن است توسط افراد دیگری نیز خوانده یا خطایابی شوند ( برای مثال در پروژه های متن باز یا پروژه های گروهی ). سعی کنید همیشه نظرات مفید و کارآمدی در مورد کدهایی که نوشته اید قرار دهید.

از خلاصه نویسی های بی مورد پرهیز کرده و در صورت نیاز حتی جملات طولانی و کامل برای کد خود قرار دهید.

/* Bad example */
.t { ... }
.red { ... }
.header { ... }

/* Good example */
.tweet { ... }
.important { ... }
.tweet-header { ... }

نام کلاس ها

  • برای نام کلاس ها فقط از حروف کوچک و خط تیره استفاده کنید. خط تیره به صورت رایج موارد مرتبط با هم را نشان می هد ، برای مثال نام های : btn. و btn-danger.
  • از عبارات مرتبط و معنا دار استفاده کنید. برای مثال نام btn. برای button مناسب است ولی نام s. هیچ معنا و مفهوم خاصی ندارد.
  • تا جای ممکن نام کلاس ها را کوتاه در نظر بگیرید. از اسامی بلند و بیهوده استفاده نکنید.
/* Bad example */
span { ... }
.page-container #stream .stream-item .tweet .tweet-header .username { ... }
.avatar { ... }

/* Good example */
.avatar { ... }
.tweet-header .username { ... }
.tweet .avatar { ... }

انتخاب گر ها

  • جهت رندرگیری بهتر از کلاس ها استفاده کنید و اسامی پیشفرض تگ های HTML را در کدهای CSS خود به کار نبرید.
  • هرگز چند انتخابگر مختلف را به صورت متوالی استفاده نکنید ( یا مثلا ["..."=^class] ) سرعت مرورگر تحت تاثیر این موارد قرار خواهد گرفت.

مطالعه بیشتر :

/*
 * Component section heading
 */

.element { ... }


/*
 * Component section heading
 *
 * Sometimes you need to include optional context for the entire component. Do that up here if it's important enough.
 */

.element { ... }

/* Contextual sub-component or modifer */
.element-heading { ... }

سازماندهی

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

تنظیمات ویرایشگر

تنظیمات ویرایشگر خود را به این صورت قرار دهید تا کدهای تمیز و خوانا تری داشته باشید :

  • مقدار هر tab را برابر با 2 کارکتر خالی قرار دهید
  • کارکترهای خالی آخر هر خط را حذف کنید
  • کدگذاری را روی UTF-8 قرار دهید
  • آخر هر فایل یک خط خالی بگذارید

سعی کنید این تنظیمات را در یک فایل editorconfig. اعمال کنید تا در هر ویرایشگری قابل استفاده باشد و نیاز به تنظیم مجدد نباشد ( برای مثال اگر کدهای شما توسط فرد دیگری با ویرایشگر متفاوت باز شود ، آن فرد نیاز به تنظیم ویرایشگر خود ندارد و این فایل همین کار را انجام خواهد داد )

مطالعه بیشتر :