Panduan Pedoman Kode oleh @mdo

Standar untuk membuat HTML dan CSS yang fleksibel, tahan lama, dan berkelanjutan.

Daftar isi

HTML

CSS

Peraturan Emas

Ikuti pedoman ini, atau pedoman sendiri, setiap waktu. Kecil atau besar, katakan ketika ada yang salah. Untuk penambahan atau kontribusi pada Pedoman Kode ini, silahkan buka sebuah issue di GitHub pembuat pedoman yang asli, @mdo (dalam Bahasa Inggris).

Sedangkan untuk koreksi pada penerjemahan, silahkan buka sebuah issue di GitHub ke saya, @diagramatics.

Setiap baris kode harus terlihat seperti ditulis oleh satu orang saja, walaupun berapapun kontributor yang telah membantu.

HTML

Sintaksis

<!DOCTYPE html>
<html>
  <head>
    <title>Judul halaman</title>
  </head>
  <body>
    <img src="images/company-logo.png" alt="Company">
    <h1 class="hello-world">Halo, dunia!</h1>
  </body>
</html>

Doctype pada HTML5

Paksakan mode yang telah distandarisasi dan rendering yang lebih konsisten di setiap browser yang mampu dengan sebuah doctype sederhana di awal dari semua halaman HTML.

<!DOCTYPE html>
<html>
  <head>
  </head>
</html>

Atribut Bahasa

Dari spec HTML5:

Penulis didorong untuk menentukan sebuah atribut lang pada elemen root html, memberikan bahasa dokumen tersebut. Ini membantu alat sintesis bahasa untuk menentukan pengucapan yang dipakai, alat penerjemah untuk menentukan peraturan apa yang dipakai, dan sebagainya.

Baca lebih lanjut mengenai atribut lang di spec tersebut (Bahasa Inggris).

Pergi ke Sitepoint untuk sebuah daftar dari kode-kode bahasa (Bahasa Inggris).

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

Mode kompatibilitas IE

Internet Explorer mendukung penggunaan sebuah tag <meta> kompatibilitas dokumen untuk menentukan versi IE yang mana yang me-render halaman tersebut. Kecuali keadaan membutuhkan sebaliknya, ini sangat berguna untuk memerintahkan IE untuk menggunakan mode terbaru yang mendukung dengan mode edge.

Untuk informasi lebih lanjut, baca artikel Stack Overflow yang hebat ini (Bahasa Inggris).

<meta http-equiv="X-UA-Compatible" content="IE=Edge">

Encoding pada karakter

Pastikan rendering yang tepat secara cepat dan mudah dengan menyatakan sebuah encoding karakter yang jelas. Ketika menggunakannya, kamu boleh menghindari pemakaian character entities pada HTML kamu, asalkan encoding mereka cocok dengan encoding pada dokumen (umumnya UTF-8).

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

Include pada CSS dan JavaScript

Per spec HTML5, tidak diperlukan untuk menyatakan sebuah type ketika meng-include file-file CSS dan JavaScript secara text/css dan text/javascript sebagai bawaan mereka masing-masing.

Tautan-tautan spec HTML5

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

<!-- CSS di dalam dokumen -->
<style>
  /* ... */
</style>

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

Kepraktisan atas kemurnian

Berjuanglah untuk mempertahankan standar dan semantik HTML, tetapi tidak dengan mengorbankan kepraktisan. Gunakan markup sesedikit mungkin dengan lika-liku sesedikit mungkin kapanpun juga.

Urutan atribut

Atribut HTML harus ditulis dengan urutan berikut agar kode lebih mudah dibaca.

Class sangat berguna untuk komponen-komponen yang akan dipakai ulang, sehingga class diurutkan pertama. ID lebih spesifik dan harus digunakan dengan hemat (misalnya untuk bookmark pada halaman), sehingga ID diurutkan kedua.

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

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

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

Atribut boolean

Sebuah atribut boolean adalah atribut yang tidak perlu value yang dinyatakan. Pada XHTML diperlukan value tersebut, tetapi HTML5 tidak membutuhkannya.

Untuk pembacaan lebih lanjut, lihat bagian di WhatWG mengenai atribut boolean (Bahasa Inggris):

Keberadaan sebuah atribut boolean pada sebuah elemen mewakili value 'true', dan ketidakberadaan dari atribut tersebut mewakili value 'false'.

Jika kamu harus memasukkan value dari atribut tersebut, dan kamu tidak perlu melakukannya, ikuti pedoman dari WhatWG berikut:

Ketika ada atribut yang dimaksud, value dari atribut tersebut harus merupakan string kosong atau [...] nama resmi atribut tersebut, tanpa spasi di depan atau dibelakangnya.

Kesimpulannya, jangan tambahkan sebuah value.

<input type="text" disabled>

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

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

Mengurangi markup

Ketika mungkin, hindari elemen induk tidak berguna ketika menulis HTML. Seringkali ini memerlukan perulangan dan penyusunan ulang struktur, tetapi menghasilkan HTML yang lebih sedikit. Ambil contoh berikut ini:

<!-- Tidak terlalu bagus -->
<span class="avatar">
  <img src="...">
</span>

<!-- Lebih baik -->
<img class="avatar" src="...">

Markup yang dibuat dari JavaScript

Menulis markup di sebuah file JavaScript membuat konten tersebut susah dicari, susah diedit, dan kecepatannya menurun. Hindarilah ketika mungkin.

CSS

Sintaksis

Ada pertanyaan pada istilah yang digunakan disini. Lihat bagian sintaksis dari artikel Cascading Style Sheets di Wikipedia Bahasa Inggris.

/* Contoh tidak baik */
.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
}

/* Contoh baik */
.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;
}

Urutan deklarasi

Deklarasi properti yang berkaitan harus dikelompokkan dengan urutan:

Related property declarations should be grouped together following the order:

  1. Peletakkan
  2. Model kotak
  3. Tipografi
  4. Visual

Peletakkan diurutkan pertama karena dapat menghilangkan sebuah elemen dari alur normal dokumen tersebut dan mengesampingkan style dari model kotak yang berkaitan.

Semua deklarasi yang lain dilakukan di dalam komponen tersebut atau tanpa mempengaruhi dua bagian sebelumnya, dan karena itulah mereka diletakkan terakhir.

Untuk daftar lengkap dari properti dan urutannya, lihat Recess (Bahasa Inggris).

.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;
}

Jangan gunakan @import

Dibandingkan dengan <link>, @import lebih lambat, menambah request halaman ekstra, dan dapat menyebabkan masalah-masalah tak terduga lainnya. Hindarilah dan pilih pendekatan alternatif:

Untuk informasi lebih lanjut, baca artikel ini oleh Steve Souders (Bahasa Inggris).

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

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

Peletakan media query

Letakkan media query dekat dengan set aturan yang berhubungan ketika bisa. Jangan dikumpulkan semuanya di sebuah stylesheet yang terpisah atau di ujung dokumen. Itu hanya membuat orang-orang luput dari penglihatan mereka kedepannya. Ini contoh sebuah pengarutan yang umum.

.element { ... }
.element-avatar { ... }
.element-selected { ... }

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

Properti yang mempunyai prefix

Ketika menggunakan properti yang memiliki vendor prefix, indent setiap properti sehingga value dari pertanyaan tersebut tersusun rapi untuk editan multi-line yang mudah.

Di Textmate, gunakan Text → Edit Each Line in Selection (⌃⌘A). Di Sublime Text 2, gunakan Selection → Add Previous Line (⌃⇧↑) dan Selection → Add Next Line (⌃⇧↓).

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

Deklarasi tunggal

Di kejadian ketika sebuah set peraturan memiliki hanya satu deklarasi, pertimbangkan untuk menghilangkan line break untuk lebih mudah dibaca dan edit yang lebih cepat. Setiap set peraturan dengan dua atau lebih deklarasi harus dipisahkan ke baris masing-masing.

Faktor utama pada hal ini adalah deteksi error—misalnya sebuah CSS validator mengatakan bahwa ada syntax error pada Baris 183. Dengan sebuah deklarasi tunggal, tidak ada yang luput. Dengan deklarasi ganda, baris yang terpisah diperlukan untuk kesehatan jiwa.

/* Deklarasi tunggal dalam satu baris */
.span1 { width: 60px; }
.span2 { width: 140px; }
.span3 { width: 220px; }

/* Lebih dari satu deklarasi, satu setiap barisnya */
.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; }

Penulisan pendek

Berjuang untuk membatasi penggunaan deklarasi yang ditulis pendek pada hal-hal dimana anda harus mengeset secara jelas setiap value yang ada. Properti yang ditulis pendek yang sering digunakan secara berlebihan berisi:

Seringkali kita tidak perlu mengeset semua value yang diwakili sebuah properti yang ditulis pendek. Misalnya, heading pada HTML hanya mengeset margin atas dan bawah, jadi ketika diperlukan, override kedua value tersebut. Penggunakan properti yang ditulis pendek secara berlebihan sering mengarah ke penulisan kode yang lebih ceroboh dengan override yang tidak diperlukan dan efek samping yang tidak diinginkan.

Mozilla Developer Network mempunyai sebuah artikel bagus mengenai properti yang ditulis pendek (Bahasa Inggris) untuk mereka yang tidak terbiasa dengan notasi dan perilaku.

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

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

Nesting pada LESS dan SASS

Hindari nesting yang tidak diperlukan. Hanya karena kamu bisa nesting, bukan berarti kamu harus selalu melakukannya. Pertimbangkan nesting ketika kamu harus mencakup style pada sebuah induk dan ada dua atau lebih elemen yang harus di-nesting.

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

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

Operator di Less and Sass

Untuk dapat dibaca lebih mudah, bungkus semua operasi matematika dalam tanda kurung menggunakan dengan satu spasi diantara nilai, variabel dan operator.

// Contoh yang buruk
.element {
  margin: 10px 0 @variable*2 10px;
}

// Contoh yang baik
.element {
  margin: 10px 0 (@variable * 2) 10px;
}

Komentar

Kode itu ditulis dan dijaga oleh orang-orang. Pastikan kode kamu deskriptif, dikomentari dengan bagus, dan dapat dipahami orang lain. Komentar pada kode yang bagus mencakup konteks dan kegunaan. Jangan hanya mengulang sebuah nama komponen atau nama dari class.

Pastikan untuk menulis dalam kalimat yang lengkap atau komentar yang lebih besar dan frase singkat untuk catatan umum.

Be sure to write in complete sentences or larger comments and succinct phrases for general notes.

/* Contoh tidak baik */
/* Modal header */
.modal-header {
  ...
}

/* Contoh baik */
/* Wrapping element for .modal-title and .modal-close */
.modal-header {
  ...
}

Nama class

Menggunakan peraturan-peraturan ini tanpa ada perbedaan juga berguna ketika membuat nama-nama variabel Sass and Less.

It's also useful to apply many of these same rules when creating Sass and Less variable names.

/* Contoh tidak baik */
.t { ... }
.red { ... }
.header { ... }

/* Contoh baik */
.tweet { ... }
.important { ... }
.tweet-header { ... }

Selector

Bacaan tambahan:

/* Contoh tidak baik */
span { ... }
.page-container #stream .stream-item .tweet .tweet-header .username { ... }
.avatar { ... }

/* Contoh baik */
.avatar { ... }
.tweet-header .username { ... }
.tweet .avatar { ... }

Penyusunan

/*
 * 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 { ... }

Preferensi editor

Set editor kamu pada pengaturan berikut untuk menghindari kode yang umumnya tidak konsisten dan diff yang kotor:

Set your editor to the following settings to avoid common code inconsistencies and dirty diffs:

Pertimbangkan mendokumentasi dan menerapkan preferensi ini pada file .editorconfig project kamu. Sebagai contoh, lihat .editorconfig pada Bootstrap. Pelajari lebih banyak mengenai EditorConfig (Bahasa Inggris).