@mdo'dan Kod Rehberi

Esnek, uzun ömürlü ve sürdürülebilir HTML ve CSS standartları.

İçindekiler

HTML

CSS

Altın kural

İster buradaki, ister size ait olan, kabul edilmiş kuralları her zaman iyileştirmeye çalışın. Küçük ya da büyük farketmez, neyin yanlış olduğunu söyleyin. Bu Kod Rehberine eklemeler yapmak ya da katkıda bulunmak için lütfen GitHub üstünde bir konu açın.

Kodun her satırı, tek bir kişi tarafından yazılmış gibi görünmelidir, katkıda bulunanların sayısı bir şeyi değiştirmez.

HTML

Yazım kuralları

<!DOCTYPE html>
<html>
  <head>
    <title>Sayfa başlığı</title>
  </head>
  <body>
    <img src="images/sirket-logo.png" alt="Şirket">
    <h1 class="merhaba-dunya">Merhaba dünya!</h1>
  </body>
</html>

HTML5 doctype

Bu basit doctype ifadesini her HTML sayfasının başında kullanarak mümkün olan tüm tarayıcılarda standart modun kullanılmasını ve daha tutarlı çıktılar üretilmesini sağlamaya çalışın.

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

Dil özniteliği

HTML5 şartnamesi diyor ki:

Geliştiricilerin kök html elemanına lang özniteliğini vererek dokümanın dilini belirtmeleri önerilir. Bu kullanım, metni konuşmaya çeviren araçların hangi telaffuzu kullanacaklarını beliremelerine, çeviri araçlarının hangi kuralları kullanacaklarını belirlemelerine, vb., yardımcı olur.

Şartnamede lang özniteliği hakkında daha fazla bilgi edinebilirsiniz.

Sitepoint'teki dil kodları listesine de göz atabilirsiniz.

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

IE uyumluluk modu

Internet Explorer, doküman uyumluluk modu <meta> tagını özelleştirerek, tarayıcının çıktı üretirken hangi IE sürümünü kullanacağını belirtmemize olanak sağlar. Şartlar aksini gerektirmediği sürece en doğru olan, edge modunu kullanarak en son desteklenen sürümün kullanılmasını istemektir.

Detaylı bilgi için, bu harika Stack Overflow makalesini okuyun.

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

Karakter kodlaması

Doğru bir karakter kodlaması kullanarak, hızlı ve kolay bir şekilde, içeriğinizin düzgün çıktılanmasını sağlayın. Bunu yaparken (&raquo;, &copy;, gibi) özel HTML öğeleri yerine karşılıkları olan özel karakterleri kullanmak isterseniz, bunları destekleyen bir karakter kodlaması (genellik UTF-8) kullanabilirsiniz.

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

CSS ve JavaScript yerleştirmeleri

İlgili HTML5 şartnamelerine göre, CSS ve JavaScript dosyalarını/kodlarını yerleştirirken type özniteliğinin değerini text/css ve text/javascript olarak belirtmeye gerek yok; çünkü bu değerler, ilgili html etiketleri için önceden tanımlanmış değerler.

HTML5 şartname linkleri

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

<!-- Dahili (satır içi) CSS -->
<style>
  /* ... */
</style>

<!-- JavaScript -->
<script src="kod-rehberi.js"></script>

Pratiklik önemli

HTML standartlarını ve anlamlılığı korumaya çalışın fakat pratikliği göz ardı etmeyin. Mümkün olduğu sürece, kodunuzdaki karmaşıklığı en aza indirin.

Öznitelik sıralaması

Kodun okunurluğunu artırmak için HTML öznitelikleri bu belirli sırada gelmelidir.

class özniteliği, yeniden kullanılabilen harika bileşenler oluşturur, bu nedenle önce gelir. id özniteliği ise daha spesifiktir ve daha az kullanılmalıdır (örneğin sayfa içinde yer imi tanımlarken), bu nedenle ikinci sıradadır.

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

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

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

Boolean öznitelikler

Boolean özniteliklerin bir değer atanmaya ihtiyacı yoktur. XHTML, boolean özniteliklere bir değer atanmasını zorunlu kılar ama HTML5'te böyle bir zorunluluk yoktur.

Daha detaylı bilgi için WhatWG'nin boolean öznitelikler bölümüne bakalım:

Bir eleman üzerinde bir boolean niteliğin varlığı true değerini temsil eder ve niteliğin yokluğu false değerini temsil eder.

Eğer bir öznitelik değeri atamak zorundaysanız -ki değilsiniz- WhatWG'nin prensiplerini dikkate alın:

Eğer özniteliğe bir değer verildiyse, bu değer ya boş bir string olmalı ya da öznitelik adının kendisi olmalı, başında veya sonunda boşluk olmadan.

Kısacası bir değer atamayın.

<input type="text" disabled>

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

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

HTML kodunu sadeleştirmek

HTML yazarken, gereksiz üst eleman kullanmaktan kaçının. Çoğu zaman bu, iterasyon ve yeniden düzenleme gerektirir ama daha az HTML üretir. Şu örneği ele alalım:

<!-- Pek iyi değil -->
<span class="avatar">
  <img src="...">
</span>

<!-- Daha iyi -->
<img class="avatar" src="...">

JavaScript ile oluşturulmuş HTML kodu

JavaScript içinde yazılmış HTML kodları, içeriğin bulunmasını/düzenlenmesini zorlaştırır ve performansını da düşürür. Mümkün olduğunca bundan kaçının.

Çevirmen Notu: Muhtemelen Bootstrap kütüphanesini kullanmış ya da en azından duymuşsunuzdur. Bu makalenin yazarı olan @mdo, Bootstrap'ın geliştiricilerindendir. Bootstrap'ın JavaScript kodlarına baktığımızda neredeyse hiç HTML kodu üretilmediğini ve düzgün çalışmak için belirli bir HTML yapısına ihtiyaç duyduğunu görürüz. Yani kendisi bu nasihate başarılı bir şekilde uymuş.

CSS

Yazım kuralları

Kafanızda burada kullanılan terimlerle alakalı soru işaretleri mi var? Vikipedi'deki Cascading Style Sheets makalesinin Syntax bölümüne bakın.

/* Kötü 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
}

/* İyi 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;
}

Tanımlama sırası

İlişkili özellik tanımlamaları aşağıdaki sırayla gruplanmalıdır:

  1. Posizyonlama
  2. Box model
  3. Tipografi
  4. Görsellik

Pozisyonlama önce gelir, çünkü bir eleman pozisyonlandığında ilgili element, dokümanın normal sıralamasından çıkarılabilir ve bu da box model ile ilişkili stillerin yeniden hesaplanmasına neden olur. Sonrasında box model, bileşenin boyutlarını ve konumunu netleştirmek için gelir.

Bileşenin içinde yer alan diğer tüm özellikler önceki iki bölümü (pozisyonlama ve box model) etkilemeden en sona eklenir.

Özelliklerin ve özellik sıralamalarının tam bir listesi için lütfen Recess'e bakın.

.declaration-order {
  /* Pozisyonlama */
  position: absolute;
  top: 0;
  right: 0;
  bottom: 0;
  left: 0;
  z-index: 100;

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

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

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

  /* Karışık */
  opacity: 1;
}

@import kullanmayın

<link> ile karşılaştırıldığında, @import yavaştır, ekstra sorgu gerektirir ve beklenmeyen sorunlara sebep olabilir. Bunlardan kaçınmak için farklı bir yaklaşım tercih edin:

Daha fazla bilgi için Steve Souders'ın makalesini okuyun.

<!-- link elemanını kullanın -->
<link rel="stylesheet" href="core.css">

<!-- @import kullanmaktan kaçının -->
<style>
  @import url("more.css");
</style>

Medya sorguları

Medya sorgularını, mümkün olduğu müddetçe ilgili CSS kural gruplarının yakınına yerleştirin. Tüm medya sorgularını tek bir dosyada ya da CSS dosyasının en sonunda paketlemeyin. Aksi taktirde insanların bu kodları gözden kaçırması ihtimalini arttırmış olursunuz. İşte tipik bir kulalnım:

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

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

Önekli özellikler

Önekli özellikleri kullanırken her bir özelliğe girinti verin, öyle ki alttaki ve üstteki özellikler kolayca aynı anda (multi-line) düzenlenebilsin.

Textmate'de Text → Edit Each Line in Selection (⌃⌘A) kullanın. Sublime Text 2'de Selection → Add Previous Line (⌃⇧↑) ve Selection → Add Next Line (⌃⇧↓) kullanın

/* Önekli özellikler */
.selector {
  -webkit-box-shadow: 0 1px 2px rgba(0,0,0,.15);
          box-shadow: 0 1px 2px rgba(0,0,0,.15);
}

Tek satırlık tanımlamalar

Bri kural setinin sadece bir tanımlama içerdiği durımlarda, okunabilirlik ve hızlı düzenlenebilirlik için satır sonlarını silmeyi düşünün. Birden fazla tanımlama içeren kural setlerinde her tanımlama ayrı bir satıra yazılmalıdır.

Buradaki anahtar faktör hata yakalamadır. Örneğin CSS validator 183. satırda bir hata yazım hatası olduğunu söylüyor. Tek tanımlamalı bir kural setinde sorun yok, hatayı kaçırmazsınız. Birden fazla tanımlamalı bir sette ise her bir tanımlamayı ayrı satıra almak, akıl sağlığınız için bir gerekliliktir.

/* Tek tanımlama, tek satır */
.span1 { width: 60px; }
.span2 { width: 140px; }
.span3 { width: 220px; }

/* Birden fazla tanımlama, satır başına bir tanım */
.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; }

Shorthand notation

Strive to limit use of shorthand declarations to instances where you must explicitly set all the available values. Common overused shorthand properties include:

Often times we don't need to set all the values a shorthand property represents. For example, HTML headings only set top and bottom margin, so when necessary, only override those two values. Excessive use of shorthand properties often leads to sloppier code with unnecessary overrides and unintended side effects.

The Mozilla Developer Network has a great article on shorthand properties for those unfamiliar with notation and behavior.

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

Nesting in Less and Sass

Avoid unnecessary nesting. Just because you can nest, doesn't mean you always should. Consider nesting only if you must scope styles to a parent and if there are multiple elements to be nested.

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

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

Operators in Less and Sass

For improved readability, wrap all math operations in parentheses with a single space between values, variables, and operators.

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

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

Comments

Code is written and maintained by people. Ensure your code is descriptive, well commented, and approachable by others. Great code comments convey context or purpose. Do not simply reiterate a component or class name.

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

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

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

Class names

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

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

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

Selectors

Additional reading:

/* Bad example */
span { ... }
.page-container #stream .stream-item .tweet .tweet-header .username { ... }
.avatar { ... }

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

Organization

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

Editor preferences

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

Consider documenting and applying these preferences to your project's .editorconfig file. For an example, see the one in Bootstrap. Learn more about EditorConfig.