Home

Awesome

Принципи за писане на консистентен, идиоматичен CSS код

Този документ описва наръчник за стил на писане, при разработката на CSS код. Тези насоки насърчават използването на вече съществуващи, общи, логични модели. Адаптирайте ги както се наложи за да създадете свой собствен наръчник за стил.

Този документ подлежи на промяна и новите идеи са добре дошли. Моля, допринасяйте към него.

Съдържание

  1. Общи положения
  2. Празни символи (whitespace)
  3. Коментари
  4. Формат
  5. Практически пример

Благодарности

Лиценз

<a name="general-principles"></a>

1. Общи положения

"Част от това да бъдеш добър участник в успешен проект е осъзнаването, че писането на код за себе си е Лоша Идея™. Ако хиляди хора ще ползват твоя код, тогава го пиши, така че да бъде максимално четим, не намесвай своите предпочитания за това как да хитрувате в рамките на спецификацията. " - Idan Gazit

<a name="whitespace"></a>

2. Празни символи (whitespace)

Използвайте само един стил за целия код на проекта. Винаги бъдете консистентни в употребата на празни символи (интервал, табулация и нов ред). Използвайте ги за да подобрите четимостта на кода.

Идея: конфигурирайте редактора си да показва невидимите символи, или автоматично да премахва празните символи на края на реда.

Идея: използвайте конфигурационен файл за EditorConfig (или еквивалент), за да спомогнете за поддържането на единнатa конвенция при употребата на празни символи във вашия код.

<a name="comments"></a>

3. Коментари

Добре коментираният код е изключително важен. Отделете време да опишете компонентите, начина на работа с тях, техните ограничения и това как са конструирани. Не оставяйте останалите в екипа, да се опитват да познаят предназначението на код, който не е очевиден.

Стилът на коментарите трябва да бъде лесен и консистентен за единна база от код.

Идея: конфигурирайте своя редактор, така че чрез клавишни комбинации да въвеждате темплейти за коментари.

Пример:

/* ==========================================================================
   Section comment block
   ========================================================================== */

/* Sub-section comment block
   ========================================================================== */

/**
 * Short description using Doxygen-style comment format
 *
 * The first sentence of the long description starts here and continues on this
 * line for a while finally concluding here at the end of this paragraph.
 *
 * The long description is ideal for more detailed explanations and
 * documentation. It can include example HTML, URLs, or any other information
 * that is deemed necessary or useful.
 *
 * @tag This is a tag named 'tag'
 *
 * TODO: This is a todo statement that describes an atomic task to be completed
 *   at a later date. It wraps after 80 characters and following lines are
 *   indented by 2 spaces.
 */

/* Basic comment */

<a name="format"></a>

4. Формат

Избрания от вас формат за кода трябва да поддържа кода: четим; лесен за коментари; намалява възможносттите за грешки; да резултира в полезни diff-ове и blame-ове.

.selector-1,
.selector-2,
.selector-3[type="text"] {
    -webkit-box-sizing: border-box;
    -moz-box-sizing: border-box;
    box-sizing: border-box;
    display: block;
    font-family: helvetica, arial, sans-serif;
    color: #333;
    background: #fff;
    background: linear-gradient(#fff, rgba(0, 0, 0, 0.8));
}

.selector-a,
.selector-b {
    padding: 10px;
}

Ред на атрибутите

Ако атрибутите са консистентно подредени, то това трябва да се случва на един и същ, лесен принцип.

Малките екипи ще предпочетат да обособяват свързаните помежду им атрибути (напр. позициониране и box-model).

.selector {
    /* Positioning */
    position: absolute;
    z-index: 10;
    top: 0;
    right: 0;
    bottom: 0;
    left: 0;

    /* Display & Box Model */
    display: inline-block;
    overflow: hidden;
    box-sizing: border-box;
    width: 100px;
    height: 100px;
    padding: 10px;
    border: 10px solid #333;
    margin: 10px;

    /* Other */
    background: #000;
    color: #fff;
    font-family: sans-serif;
    font-size: 16px;
    text-align: right;
}

По-големите екипи могат да предпочетат лесната подръжка, която носи азбучния ред.

Изключения и леки отклонения

Големи блокове с дефиниции от един ред използват по-различен, едноредов формат. В такива случаи, трябва да се поставя интервал след отварящата скоба и преди затварящата.

.selector-1 { width: 10%; }
.selector-2 { width: 20%; }
.selector-3 { width: 30%; }

Дълги, разделени от запетая стойности за атрибути - например няколко CSS градиента, или множество сенки - могат да бъдат подреждани на няколко реда, за по-добра четимост, както на кода, така и в diff. Съществуват няколко формата, които могат да бъдат използвани, по-долу можете да намерите един от тях.

.selector {
    background-image:
        linear-gradient(#fff, #ccc),
        linear-gradient(#f3c, #4ec);
    box-shadow:
        1px 1px 1px #000,
        2px 2px 1px 1px #ccc inset;
}

CSS препроцесори: допълнителни уточнения по форматирането

Различните CSS препроцесори имат различни възможности, функционалности и синтаксис. Вашите конвенции трябва да бъдат разширени така, че да позволят особеностите на всеки използван препроцесор. Следните правила са адаптирани за Sass.

.selector-1 {
    @extend .other-rule;
    @include clearfix();
    @include box-sizing(border-box);
    width: x-grid-unit(1);
    // other declarations
}

<a name="example"></a>

5. Практически пример

Пример, показващ различните конвенции.

/* ==========================================================================
   Grid layout
   ========================================================================== */

/**
 * Column layout with horizontal scroll.
 *
 * This creates a single row of full-height, non-wrapping columns that can
 * be browsed horizontally within their parent.
 *
 * Example HTML:
 *
 * <div class="grid">
 *     <div class="cell cell-3"></div>
 *     <div class="cell cell-3"></div>
 *     <div class="cell cell-3"></div>
 * </div>
 */

/**
 * Grid container
 *
 * Must only contain `.cell` children.
 *
 * 1. Remove inter-cell whitespace
 * 2. Prevent inline-block cells wrapping
 */

.grid {
    height: 100%;
    font-size: 0; /* 1 */
    white-space: nowrap; /* 2 */
}

/**
 * Grid cells
 *
 * No explicit width by default. Extend with `.cell-n` classes.
 *
 * 1. Set the inter-cell spacing
 * 2. Reset white-space inherited from `.grid`
 * 3. Reset font-size inherited from `.grid`
 */

.cell {
    position: relative;
    display: inline-block;
    overflow: hidden;
    box-sizing: border-box;
    height: 100%;
    padding: 0 10px; /* 1 */
    border: 2px solid #333;
    vertical-align: top;
    white-space: normal; /* 2 */
    font-size: 16px; /* 3 */
}

/* Cell states */

.cell.is-animating {
    background-color: #fffdec;
}

/* Cell dimensions
   ========================================================================== */

.cell-1 { width: 10%; }
.cell-2 { width: 20%; }
.cell-3 { width: 30%; }
.cell-4 { width: 40%; }
.cell-5 { width: 50%; }

/* Cell modifiers
   ========================================================================== */

.cell--detail,
.cell--important {
    border-width: 4px;
}

Преводи

<a name="acknowledgements"></a>

Благодарности

Благодаря на всички, които предоставиха преводи, както и на тези, които допринесоха към idiomatic.js. Idiomatic.js бе извор на вдъхновение, цитати и правила.

<a name="license"></a>

Лиценз

Principles of writing consistent, idiomatic CSS от Nicolas Gallagher, е лицензирано като Creative Commons Attribution 3.0 Unported License. Същото се отнася за всички документи и преводи в това хранилище.

Базирано на труд от github.com/necolas/idiomatic-css.