Repository: necolas/idiomatic-css
Branch: master
Commit: 19ad3d767406
Files: 18
Total size: 186.2 KB
Directory structure:
gitextract_7ezio74a/
├── README.md
└── translations/
├── cs-CZ/
│ └── README.md
├── da-DK/
│ └── README.md
├── de-DE/
│ └── README.md
├── es-ES/
│ └── README.md
├── fr-FR/
│ └── README.md
├── id-ID/
│ └── README.md
├── it-IT/
│ └── README.md
├── ja-JP/
│ └── README.md
├── ko-KR/
│ └── README.md
├── nl-NL/
│ └── README.md
├── pl-PL/
│ └── README.md
├── pt-BR/
│ └── README.md
├── ru-RU/
│ └── README.md
├── sr-SR/
│ └── README.md
├── tr-TR/
│ └── README.md
├── zh-CN/
│ └── README.md
└── zh-TW/
└── README.md
================================================
FILE CONTENTS
================================================
================================================
FILE: README.md
================================================
# Principles of writing consistent, idiomatic CSS
The following document outlines a reasonable style guide for CSS development.
These guidelines strongly encourage the use of existing, common, sensible
patterns. They should be adapted as needed to create your own style guide.
This is a living document and new ideas are always welcome. Please
contribute.
## Table of contents
1. [General principles](#general-principles)
2. [Whitespace](#whitespace)
3. [Comments](#comments)
4. [Format](#format)
5. [Practical example](#example)
[Acknowledgements](#acknowledgements)
[License](#license)
<a name="general-principles"></a>
## 1. General principles
> "Part of being a good steward to a successful project is realizing that
> writing code for yourself is a Bad Idea™. If thousands of people are using
> your code, then write your code for maximum clarity, not your personal
> preference of how to get clever within the spec." - Idan Gazit
* Don't try to prematurely optimize your code; keep it readable and
understandable.
* All code in any code-base should look like a single person typed it, even
when many people are contributing to it.
* Strictly enforce the agreed-upon style.
* If in doubt when deciding upon a style use existing, common patterns.
<a name="whitespace"></a>
## 2. Whitespace
Only one style should exist across the entire source of your code-base. Always
be consistent in your use of whitespace. Use whitespace to improve
readability.
* _Never_ mix spaces and tabs for indentation.
* Choose between soft indents (spaces) or real tabs. Stick to your choice
without fail. (Preference: spaces)
* If using spaces, choose the number of characters used per indentation level.
(Preference: 4 spaces)
Tip: configure your editor to "show invisibles" or to automatically remove
end-of-line whitespace.
Tip: use an [EditorConfig](http://editorconfig.org/) file (or equivalent) to
help maintain the basic whitespace conventions that have been agreed for your
code-base.
<a name="comments"></a>
## 3. Comments
Well commented code is extremely important. Take time to describe components,
how they work, their limitations, and the way they are constructed. Don't leave
others in the team guessing as to the purpose of uncommon or non-obvious
code.
Comment style should be simple and consistent within a single code base.
* Place comments on a new line above their subject.
* Keep line-length to a sensible maximum, e.g., 80 columns.
* Make liberal use of comments to break CSS code into discrete sections.
* Use "sentence case" comments and consistent text indentation.
Tip: configure your editor to provide you with shortcuts to output agreed-upon
comment patterns.
Example:
```css
/* ==========================================================================
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. Format
The chosen code format must ensure that code is: easy to read; easy to clearly
comment; minimizes the chance of accidentally introducing errors; and results
in useful diffs and blames.
* Use one discrete selector per line in multi-selector rulesets.
* Include a single space before the opening brace of a ruleset.
* Include one declaration per line in a declaration block.
* Use one level of indentation for each declaration.
* Include a single space after the colon of a declaration.
* Use lowercase and shorthand hex values, e.g., `#aaa`.
* Use single or double quotes consistently. Preference is for double quotes,
e.g., `content: ""`.
* Quote attribute values in selectors, e.g., `input[type="checkbox"]`.
* _Where allowed_, avoid specifying units for zero-values, e.g., `margin: 0`.
* Include a space after each comma in comma-separated property or function
values.
* Include a semi-colon at the end of the last declaration in a declaration
block.
* Place the closing brace of a ruleset in the same column as the first
character of the ruleset.
* Separate each ruleset by a blank line.
```css
.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;
}
```
#### Declaration order
If declarations are to be consistently ordered, it should be in accordance with
a single, simple principle.
Smaller teams may prefer to cluster related properties (e.g. positioning and
box-model) together.
```css
.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;
}
```
Larger teams may prefer the simplicity and ease-of-maintenance that comes with
alphabetical ordering.
#### Exceptions and slight deviations
Large blocks of single declarations can use a slightly different, single-line
format. In this case, a space should be included after the opening brace and
before the closing brace.
```css
.selector-1 { width: 10%; }
.selector-2 { width: 20%; }
.selector-3 { width: 30%; }
```
Long, comma-separated property values - such as collections of gradients or
shadows - can be arranged across multiple lines in an effort to improve
readability and produce more useful diffs. There are various formats that could
be used; one example is shown below.
```css
.selector {
background-image:
linear-gradient(#fff, #ccc),
linear-gradient(#f3c, #4ec);
box-shadow:
1px 1px 1px #000,
2px 2px 1px 1px #ccc inset;
}
```
### Preprocessors: additional format considerations
Different CSS preprocessors have different features, functionality, and syntax.
Your conventions should be extended to accommodate the particularities of any
preprocessor in use. The following guidelines are in reference to Sass.
* Limit nesting to 1 level deep. Reassess any nesting more than 2 levels deep.
This prevents overly-specific CSS selectors.
* Avoid large numbers of nested rules. Break them up when readability starts to
be affected. Preference to avoid nesting that spreads over more than 20
lines.
* Always place `@extend` statements on the first lines of a declaration
block.
* Where possible, group `@include` statements at the top of a declaration
block, after any `@extend` statements.
* Consider prefixing custom functions with `x-` or another namespace. This
helps to avoid any potential to confuse your function with a native CSS
function, or to clash with functions from libraries.
```scss
.selector-1 {
@extend .other-rule;
@include clearfix();
@include box-sizing(border-box);
width: x-grid-unit(1);
// other declarations
}
```
<a name="example"></a>
## 5. Practical example
An example of various conventions.
```css
/* ==========================================================================
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;
}
```
## Translations
* [Bahasa Indonesia](https://github.com/necolas/idiomatic-css/tree/master/translations/id-ID)
* [Bulgarian](https://github.com/vestimir/idiomatic-css)
* [Česky](https://github.com/necolas/idiomatic-css/tree/master/translations/cs-CZ)
* [Dansk](https://github.com/necolas/idiomatic-css/tree/master/translations/da-DK)
* [Deutsch](https://github.com/necolas/idiomatic-css/tree/master/translations/de-DE)
* [Español](https://github.com/necolas/idiomatic-css/tree/master/translations/es-ES)
* [Français](https://github.com/necolas/idiomatic-css/tree/master/translations/fr-FR)
* [Italiano](https://github.com/necolas/idiomatic-css/tree/master/translations/it-IT)
* [日本語](https://github.com/necolas/idiomatic-css/tree/master/translations/ja-JP)
* [한국어](https://github.com/necolas/idiomatic-css/tree/master/translations/ko-KR)
* [Nederlands](https://github.com/necolas/idiomatic-css/tree/master/translations/nl-NL)
* [Polski](https://github.com/necolas/idiomatic-css/tree/master/translations/pl-PL)
* [Português (Brasil)](https://github.com/necolas/idiomatic-css/tree/master/translations/pt-BR)
* [Русский](https://github.com/necolas/idiomatic-css/tree/master/translations/ru-RU)
* [Srpski](https://github.com/necolas/idiomatic-css/tree/master/translations/sr-SR)
* [Türkçe](https://github.com/necolas/idiomatic-css/tree/master/translations/tr-TR)
* [正體中文](https://github.com/necolas/idiomatic-css/tree/master/translations/zh-TW)
* [简体中文](https://github.com/necolas/idiomatic-css/tree/master/translations/zh-CN)
<a name="acknowledgements"></a>
## Acknowledgements
Thanks to everyone who has provided translations and to all those who
contributed to [idiomatic.js](https://github.com/rwldrn/idiomatic.js). It was a
source of inspiration, quotations, and guidelines.
<a name="license"></a>
## License
_Principles of writing consistent, idiomatic CSS_ by Nicolas Gallagher is
licensed under the [Creative Commons Attribution 3.0 Unported
License](http://creativecommons.org/licenses/by/3.0/). This applies to all
documents and translations in this repository.
Based on a work at
[github.com/necolas/idiomatic-css](https://github.com/necolas/idiomatic-css).
================================================
FILE: translations/cs-CZ/README.md
================================================
# Zásady psaní konzistentního, idiomatického CSS
Tohle je příručka stylu (_style guide_) pro psaní CSS. Neberte ji jako
nařizující, nechci jiným lidem vnucovat styl psaní kódu podle svých preferencí.
Následující zásady ale silně podporují využívání existujících vzorů jež
považuji za obvyklé a rozumné.
Na dokumentu se pracuje a nové nápady vítám. Přispějte jimi prosím.
[Idiomatic CSS anglicky](https://github.com/necolas/idiomatic-css/)
## Obsah
1. [Obecné principy](#general-principles)
2. [Bílá mezera](#whitespace)
3. [Komentáře](#comments)
4. [Formát](#format)
5. [Pojmenovávání](#naming)
6. [Praktická ukázka](#example)
7. [Uspořádání](#organization)
8. [Build a deploy](#build-and-deployment)
[Poděkování](#acknowledgements)
<a name="general-principles"></a>
## 1. Obecné principy
> „Pokud chcete být dobrý správce úspěšného projektu, musíte si kromě jiného
> uvědomit, že psaní kódu pro sebe je dost blbý nápad. Pokud váš kód užívají
> tisíce lidí, musíte jej psát pro maximální srozumitelnost a ne pro svou
> radost z dodržení specifikace.” - Idan Gazit
* Nejste lidský kompiler ani kompresor kódu. Nesnažte se jím stát.
* Veškerý kód jednoho projektu by měl vypadat jako by ho napsal jediný člověk.
Bez ohledu na to kolik lidí přispělo.
* Striktně vymáhejte dohodnutý styl.
* V případě pochybností o dohodnutém stylu, použijte existující obecné vzory.
<a id="whitespace"></a>
## 2. Bílá mezera
V kódu vašeho projektu by měl existovat jen jediný styl užívání bílé mezery
(_whitespace_). Zlepšujte s její pomocí čitelnost.
* Nikdy pro odsazování nepoužívejte mezery a zároveň tabulátory.
* Vyberte si buď měkké odsazení (pomocí mezer) nebo skutečné tabulátory. Držte
se svého výběru bez výjimky. (Upřednostňujte mezery)
* Pokud používáte mezery, zvolte si počet znaků používaných pro úroveň
odsazení. (Upřednostňujte 4 mezery)
Tip: nastavte si editor tak, aby zobrazoval neviditelné znaky. To vám umožní
potlačit bílé mezery na konci řádků nebo nechtěné prázdné řádky s bílou
mezerou. Zabráníte tak zaneřádění commitů.
Tip: používejte soubor [EditorConfig](http://editorconfig.org/) (nebo něco
podobného) aby vám pomohl dodržovat úmluvy o bílých mezerách, které jste
dohodli pro celý projekt.
<a name="comments"></a>
## 3. Komentáře
Dobře komentovat kód je hrozně důležité. Udělejte si čas pro popis komponent,
toho jak pracují, jejich omezení, a způsobu jakým jsou sestrojeny. Nenechávejte
ostatní v týmu odhadovat účel neobvyklého nebo málo zřejmého kódu.
Styl komentářů by měl být jednoduchý a konzistentní pro celý projekt.
* Umísťujte komentáře na nový řádek nad jejich subjekt.
* Vyhněte se komentářům na konci řádky.
* Ponechte šířku řádky na citlivém maximu, například 80 znacích.
* Velkorysým používáním komentářů dělte CSS kód do jednotlivých sekcí.
* Pište komentáře ve větách (_sentence case_) a text konzistentně odsazujte.
Tip: Nastavte si editor tak, abyste dohodnuté komentářové vzory měli vždy po
ruce.
#### Example:
```css
/* ==========================================================================
Nadpis pro sekci
========================================================================== */
/* Nadpis pro podsekci
========================================================================== */
/**
* Kratky popis co se drzi komentaroveho formatu Doxygen
*
* Tady zacina prvni veta dlouheho popisu a chvili pokracuje dokud neskonci
* na dalsim radku.
*
* Nejdelsi popisek je idealni pro detailnejsi vysvetleni a dokumentace. Muze
* obsahovat ukazkove HTML, URL adresy nebo jakekoliv jine informace co se
* povazuji za nezbytne nebo uzitecne.
*
* @tag Tohle je znacka s nazvem „tag”
*
* @todo Tohle je popis ukolu (todo) co ma byt vyresen pozdeji.
* Zalomi se po 80ti znacich. Druhy a dalsi radky odsazujeme 2 mezerami.
*/
/* Jednoduchy komentar */
```
_(Pozn. překl. – Komentáře v kódu je lepší jednotně psát bez diakritiky. Hlavně
proto, že velká část českých vývojářů píše kód pomocí anglické klávesnice.)_
<a name="format"></a>
## 4. Formát
Zvolený formát musí zajistit aby číst kód a vytvářet v něm srozumitelné
komentáře bylo snadné. Omezte riziko náhodně vzniklých chyb. Výsledkem dobrého
a jednotného formátu je snadné porovnávání dvou verzí (_diff_) a čitelný
_blame_, jež ukazuje autora a commit poslední změny konkrétního řádku.
* V pravidlech obsahujících více selektorů mějte každý selektor na
samostatné řádce.
* Před otevírací složenou závorku pravidla vkládejte jednu mezeru.
* V bloku deklarací mějte každou deklaraci na zvláštním řádku.
* Každou deklaraci odsazujte o jednu úroveň.
* V deklaraci pište za dvojtečku jednu mezeru.
* Ve zkrácených variantách hexa hodnot barev používejte malá písmena
(např. `#aaa`).
* Konzistentně používejte jednoduché anebo dvojité „uvozovky”.
Doporučujeme dvojité (např. `content: ""`).
* Hodnoty atribut selektorů uvádějte v „uvozovkách” (např.
`input[type="checkbox"]`).
* Tam kde je to u nulových hodnot možné, vyhněte se uvádění jednotek
(např. `margin: 0`).
* Za každou čárku použitou jako oddělovač hodnot nebo parametrů funkcí
vložte mezeru.
* Na konec každé deklarace v bloku deklarací vložte středník.
* Uzavírací složenou závorku pro konec pravidla odsaďte stejně jako první
znak pravidla.
* Jednotlivá pravidla oddělujte prázdným řádkem.
```css
.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));
}
```
#### Pořadí deklarací
Deklarace v kódu jednoho projektu řaďte v souladu s jediným principem.
Upřednostňuji deklarovat nejprve konstrukčně důležité vlastnosti (např.
pozicování nebo box model).
```css
.selector {
/* Pozicovani */
position: absolute;
z-index: 10;
top: 0;
right: 0;
bottom: 0;
left: 0;
/* Zobrazeni & box model */
display: inline-block;
overflow: hidden;
box-sizing: border-box;
width: 100px;
height: 100px;
padding: 10px;
border: 10px solid #333;
margin: 10px;
/* Ostatni */
background: #000;
color: #fff
font-family: sans-serif;
font-size: 16px;
text-align: right;
}
```
Poměrně populární je také abecední pořadí. To má ale nevýhodu, že odděluje
příbuzné vlastnosti. Například – ofsety pozice (vlastnosti `top`, `left` apod.)
tak nemohou být seskupeny dohromady a vlastnosti box-modelu mohou skončit
rozptýlené po celém pravidle.
_(Pozn. překl. — Některé vlastnosti jsou navíc pro rychlý sken stylopisu
důležitější než jiné – position, z-index. I proto jim patří místo na začátku
pravidla.)_
#### Výjimky a mírné odchylky
Velké bloky pravidel s jednou deklarací můžete zapisovat trochu jinak — na
jeden řádek. V tomto případě by za otevírací a před uzavírací složenou závorkou
neměla chybět mezera.
```css
.selector-1 { width: 10%; }
.selector-2 { width: 20%; }
.selector-3 { width: 30%; }
```
Dlouhé bloky hodnot oddělované čárkou – jako třeba vícenásobná pozadí nebo
stíny – je lepší pro zlepšení čitelnosti nebo zajištění užitečnějších diffů
rozdělit do více řádků. Formátů jež je možné použít je mnoho. Tady je jeden
příklad:
```css
.selector {
background-image:
linear-gradient(#fff, #ccc),
linear-gradient(#f3c, #4ec);
box-shadow:
1px 1px 1px #000,
2px 2px 1px 1px #ccc inset;
}
```
### Preprocesory
Různé CSS preprocesory mají různé vlastnosti, funkce a syntaxi. Vaše konvence
byste měli rozšířit tak, aby vyhověly zvláštnostem preprocesoru, který
využíváte. Následující zásady se vztahují k Sass.
* Omezte zanořování pravidel na 1 úroveň. Přehodnoťte každé zanořování
hlubší než 2 úrovně. To omezí existenci příliš specifických selektorů.
* Vyhněte se velkému množství vnořených pravidel. Jakmile se čitelnost
začíná zhoršovat, rozdělte je. Doporučuji rozdělovat vnořená pravidla
jež zaberou více než 20 řádků.
* Direktivy `@extend` vždy zapisujte do prvních řádků pravidla.
* Tam kde je to možné seskupte direktivy `@include` hned za řádky s `@extend`.
* Zvažte prefixování vašich funkcí pomocí x- nebo jiného jmenného prostoru.
To vám pomůže vyhnout se kolizím s názvy nativních CSS funkcí nebo funkcí
z knihoven.
```scss
.selector-1 {
@extend .other-rule;
@include clearfix();
@include box-sizing(border-box);
width: x-grid-unit(1);
// ostatni deklarace
}
```
<a name="naming"></a>
## 5. Pojmenovávání
Pojmenovávání je těžké, ale velice důležité. Je to stěžejní část procesu vývoje
spravovatelného kódu. Dobrý způsob pojmenovávání vám zajistí škálovatelné
rozhraní mezi vaším HTML a CSS.
* Vyhněte se systematickému používání zkrácených názvů tříd. Nedělejte
věci těžké k pochopení.
* Pro třídy v HTML používejte čisté, smysluplné a odpovídající názvy.
* Vyberte srozumitelný a konzistentní vzorec pojmenovávání co dává smysl jak
v HTML tak CSS souborech.
* Selektory pro komponenty by měly využívat názvy tříd. Vyhněte se
používání generických značek (tagů) nebo unikátních id.
```css
/* Ukazky kodu se spatnymi pojmenovavanim selektoru */
.s-scr {
overflow: auto;
}
.cb {
background: #000;
}
/* Ukazky kodu s lepsim pojmenovanim selektoru */
.is-scrollable {
overflow: auto;
}
.column-body {
background: #000;
}
```
<a name="example"></a>
## 6. Praktická ukázka
```css
/* ==========================================================================
Mrizkovy layout
========================================================================== */
/**
* Ukazka HTML:
*
* <div class="grid">
* <div class="cell cell-5"></div>
* <div class="cell cell-5"></div>
* </div>
*/
.grid {
overflow: visible;
height: 100%;
/* Zamezi zalomeni inline-block bunek mrizky */
white-space: nowrap;
/* Odstrani mezeru mezi bunkami */
font-size: 0;
}
.cell {
position: relative;
display: inline-block;
overflow: hidden;
box-sizing: border-box;
width: 20%;
height: 100%;
/* Nastavime vnitrni okraj bunek */
padding: 0 10px;
border: 2px solid #333;
vertical-align: top;
/* Resetujeme bilou mezeru */
white-space: normal;
/* Resetujeme velikost pisma */
font-size: 16px;
}
/* Stavy bunky */
.cell.is-animating {
background-color: #fffdec;
}
/* Varianty sirky bunky
========================================================================== */
.cell-1 { width: 10%; }
.cell-2 { width: 20%; }
.cell-3 { width: 30%; }
.cell-4 { width: 40%; }
.cell-5 { width: 50%; }
/* Modifikatory bunky
========================================================================== */
.cell--detail,
.cell--important {
border-width: 4px;
}
```
<a name="organization"></a>
## 7. Uspořádání
Uspořádání (organizace větších celků) je důležitá vlastnost každé CSS části
kódu projektu, ale pro ty větší je dost zásadní.
* Logicky oddělujte odlišné části kódu.
* Pro odlišné komponenty kódu používejte oddělené soubory, které pak spojte
v sestavovacím (_build_) kroku.
* Pokud používáte preprocesor, zobecněte často používaný kód do proměnných
pro barvy, typografii atd.
<a name="build-and-deployment"></a>
## 8. Build a deploy
Určitě byste se měli pokusit na projektu nasadit nějaké nástroje pomocí kterých
můžete kód projektu prověřit lint analýzou, zkomprimovat a verzovat během
přípravy pro produkční použití. Pro tenhle účel existuje vynikající nástroj
[grunt](https://github.com/cowboy/grunt) od Bena Almana.
<a name="acknowledgements"></a>
## Poděkování
Díky všem co přispěli k [idiomatic.js](https://github.com/rwldrn/idiomatic.js).
Byl to můj zdroj inspirace, citací a zásad.
================================================
FILE: translations/da-DK/README.md
================================================
# Principper for at skrive konsistent, idiomatisk CSS
Dette dokument skitserer en række fornuftige og logiske retningslinjer til CSS udvikling.
Det er ikke ment som et asolut regelsæt og jeg ønsker ikke at presse min måde at
skrive CSS på ned over andres kode. Ikke desto mindre så indbyder disse principper
til at benytte allerede eksisterende og logiske kodemønstre.
Dette dokument er levende og nye tilføjelser og idéer er altid velkomne.
## Oversættelser
* [Dansk](https://github.com/necolas/idiomatic-css/tree/master/translations/da-DK)
* [Italiano](https://github.com/necolas/idiomatic-css/tree/master/translations/it-IT)
* [日本語](https://github.com/necolas/idiomatic-css/tree/master/translations/ja-JP)
* [Nederlands](https://github.com/necolas/idiomatic-css/tree/master/translations/nl-NL)
* [Português (Brasil)](https://github.com/necolas/idiomatic-css/tree/master/translations/pt-BR)
* [Srpski](https://github.com/necolas/idiomatic-css/tree/master/translations/sr)
* [Türkçe](https://github.com/necolas/idiomatic-css/tree/master/translations/tr-TR)
* [简体中文](https://github.com/necolas/idiomatic-css/tree/master/translations/zh-CN)
## Indholdsfortegnelse
1. [Generelle principper](#general-principles)
2. [Mellemrum](#whitespace)
3. [Kommentarer](#comments)
4. [Formatering](#format)
5. [Navngivning](#naming)
6. [Praktisk eksempel](#example)
7. [Organisering](#organization)
8. [Build og udrulning](#build-and-deployment)
[Anerkendelser](#acknowledgements)
<a name="general-principles"></a>
## 1. Generelle principper
> "En del af det at være en god forvalter af et succésfuldt projekt er at
> indse, at det at skrive kode til én selv er En Dårlig Idé™. Hvis tusindvis af
> mennesker bruger din kode, bør du optimere din kode til maksimal
> læsevenlighed, ikke til dine personlige preferencer og sjove eller underlige
> forkortelser." - Idan Gazit
* Al kode i kode-basen bør se ud som om, kun én person har skrevet det hele,
uanset hvor mange der rent faktisk har leveret indhold.
* Håndhæv den aftalte stil strengt.
* Hvis der er tvivl bør eksisterende, bredt accepterede kodemønstre benyttes.
<a name="whitespace"></a>
## 2. Mellemrum
Kun én stil bør eksistere på tværs af hele dit projekts kilde. Vær altid
konsistent i din brug af mellemrum. Brug mellemrum og ekstra linjeskift til at
forbedre læsbarheden.
* Du må _aldrig_ blande mellemrum og tablatorer ved indrykning.
* Vælg mellem bløde indrykninger (mellemrum) eller tabulatorer. Stå ved dit
valg uden forbehold. (Anbefales: mellemrum)
* Hvis du bruger mellemrum, vælges et antal der bruges pr. indrykningsniveau.
(Anbefales: 4 mellemrum)
Tip: Indstil din CSS-editor til at vise skjulte tegn. Dette giver dig mulighed
for, at slette mellemrum i slutningen af kodelinjer, slette uønskede
dobbelt-mellemrum og dermed undgå at "forurene" kode-commits.
<a name="comments"></a>
## 3. Kommentarer
Velkommenteret (og dermed veldokumenteret) kode er virkelig vigtigt. Brug tid
på at beskrive komponenter, hvordan de virker, deres begrænsninger og måden
hvorpå de er konstrueret. Overlad det ikke til andre i teamet at gætte sig frem
til, hvad usædvanlig eller ikke-indlysende kode skal bruges til.
Kommentar-stilen bør være simpel og konsistent på tværs er hele kode-basen.
* Placér kommentarer på en ny linje over den kode, de beskriver.
* Undgå kommentarer for enden af kodelinjer.
* Hold kommentarlinjer fornuftigt korte, fx 80 karakterer.
* Vær gavmild med kommentarer til at bryde CSS'en op i mindre sektioner.
* Brug korrekt grammetik i kommentarer og vær konsistent med tekst-indrykning.
Tip: Indstil din CSS-editor til at give dig genveje til at indsætte
tekststumper med de aftalte kommentar-mønstre.
#### CSS-eksempel:
```css
/* ==========================================================================
Afsnit kommentar-blok
========================================================================== */
/* Underafsnit kommentar-blok
========================================================================== */
/*
* Gruppe kommentar-blok.
* Idéel til fler-linjede forklaringer og dokumentation.
*/
/* Simpel kommentar */
```
#### SCSS-eksempel:
```scss
// ==========================================================================
// Afsnit kommentar-blok
// ==========================================================================
// Underafsnit kommentar-blok
// ==========================================================================
//
// Gruppe kommentar-blok.
// Idéel til fler-linjede forklaringer og dokumentation.
//
// Simpel kommentar
```
<a name="format"></a>
## 4. Formatering
Det valgte kodeformat skal tilsikre at koden er: nem at læse; nem at kommentere
klart; minimere risikoen for at introducere fejl ved et tilfælde; og resulterer
i brugbare diffs og blames
(https://git.wiki.kernel.org/index.php/Textconv#Blame_and_diff)
1. Én diskret selector pr. linje i multi-selector regelsæt.
2. Ét enkelt mellemrum før krøllet start-parentes i regelsæt.
3. Én erklæring pr. linje i regelsæt.
4. Ét indrykningsniveau på regelsæt.
5. Ét enkelt mellemrum efter kolon i hver erklæring.
6. Afslut _alle_ erklæringer med et semikolon - også den sidste.
7. Placér den krøllede slut-parentes på samme indrykningsniveau som det første
tegn i regelsættet.
8. Opdel de enkelte regelsæt med en tom linje.
```css
.selector-1,
.selector-2,
.selector-3 {
-webkit-box-sizing: border-box;
-moz-box-sizing: border-box;
box-sizing: border-box;
display: block;
color: #333;
background: #fff;
}
```
#### Erklæringers rækkefølge
Erklæringer bør sorteres i overensstemmelse med et simpelt princip. Mit
foretrukne princip er at gruppere relaterede egenskaber sammen, og
strukturmæssigt vigtigt egenskaber (fx positionering og box-modellen) erklæring
inden typografi, baggrund og farveegenskaber.
```css
.selector {
position: relative;
display: block;
width: 50%;
height: 100px;
padding: 10px;
border: 0;
margin: 10px;
color: #fff
background: #000;
}
```
Alfabetisk rækkefølge er også populær, men ulempen er, at denne sortering
adskiller relaterede egenskaber. For eksempel vil positioneringsegenskaber ikke
længere være samlet i en gruppe, og box-modellens egenskaber kan ende med at
blive spredt ud over hele regelsættet.
#### Undtagelser og små afvigelser
Store blokke af enkelt-linje erklæringer kan benytte et enkeltlinje-format. I
dette tilfælde bør der inkluderes et enkelt mellemrum før krøllet
start-parentes og inden krøllet slut-parentes.
```css
.selector-1 { width: 10%; }
.selector-2 { width: 20%; }
.selector-3 { width: 30%; }
```
Lange, kommaseparerede egenskaber - fx samlinger af farveforløb eller skygger -
kan arrangeres over flere linjer, i en betræbelse på, at forbedre læsbarheden
og producere mere brugbare diffs. Det er flere forskellige formater der kan
benyttes; en måde at gøre det på kan ses herunder.
```css
.selector {
box-shadow:
1px 1px 1px #000,
2px 2px 1px 1px #ccc inset;
background-image:
linear-gradient(#fff, #ccc),
linear-gradient(#f3c, #4ec);
}
```
#### Diverse
* Brug små bogstaver i hex værdier, fx `#aaa`.
* Brug enkelt- eller dobbelt-anførselstegn konsistent. Dobbelt-anførselstegn
foretrækkes, fx `content: ""`.
* Brug altid anførselstegn i selctorers egenskaber, fx
`input[type="checkout"]`.
* _Hvor det er muligt_ bør du undgå at specificere enheder for nul-værdier, fx
`margin: 0`.
### Preprocessors: Ekstra overvejelser i forbindelse med formatering
Forskellige CSS preprocessors har forskellige egenskaber, funktionalitet og
syntaks. Dine konventioner bør udvides og tilpasses, således at de imødekommer
de forhold, der er i de proprocessors der benyttes af gruppen. De efterfølgende
guidelines relaterer sig til SASS.
* Begræns indlejring til 1 niveau. Genovervej alle indlejringer der er mere end
2 niveauer dyb. Dette forhindrer alt for specifikke CSS selektorer.
* Undgå et højt antal indlejrede regler. Bryd dem op når læsbarheden begynder
at blive påvirket. Det anbefales at undgå indlejringer der breder sig over
mere end 20 linjer.
* Placér altid `@extend`-erklæringer på første linje i regelsæt.
* Hvis det er muligt, placeres `@include` i toppen af regelsættet, lige efter
`@extend`-erklæringer.
* Overvej at starte brugerdeficerede funktioner med `x-` eller lignende. Dette
hjælper med at undgå, at dine funktioner konflikter med (eller overskriver)
standard CSS-funktioner fra biblioteker og frameworks.
```scss
.selector-1 {
@extend .other-rule;
@include clearfix();
@include box-sizing(border-box);
width: x-grid-unit(1);
// andre erklæringer
}
```
<a name="naming"></a>
## 5. Navngivning
Du er ikke en menneskelig compiler/compressor, så lad være med at prøve at være
en sådan.
Brug klare og logiske navne til dine HTML-class'er. Vælg et forståelig og
konstistent navngivningsmønster der giver mening i både HTML- og CSS-filer.
```css
/* Eksempel på kode med dårlig navngivning */
.s-scr {
overflow: auto;
}
.cb {
background: #000;
}
/* Eksempel på kode med god navngivning */
.is-scrollable {
overflow: auto;
}
.column-body {
background: #000;
}
```
<a name="example"></a>
## 6. Praktisk eksempel
Et eksempel på en række forskellige konventioner.
```css
/* ==========================================================================
Gitter layout
========================================================================== */
/*
* HTML-eksempel:
*
* <div class="grid">
* <div class="cell cell-5"></div>
* <div class="cell cell-5"></div>
* </div>
*/
.grid {
overflow: visible;
height: 100%;
/* Undgå at "inline-block"-celler ombrydes */
white-space: nowrap;
/* Fjerner mellemrum mellem celler */
font-size: 0;
}
.cell {
box-sizing: border-box;
position: relative;
overflow: hidden;
width: 20%;
height: 100%;
/* Angiver mellemrum mellem celler */
padding: 0 10px;
border: 2px solid #333;
vertical-align: top;
/* Nulstil white-space */
white-space: normal;
/* Nulstil font-size */
font-size: 16px;
}
/* Cellers tilstande */
.cell.is-animating {
background-color: #fffdec;
}
/* Cellers dimensioner
========================================================================== */
.cell-1 { width: 10%; }
.cell-2 { width: 20%; }
.cell-3 { width: 30%; }
.cell-4 { width: 40%; }
.cell-5 { width: 50%; }
/* Celle-ændringer
========================================================================== */
.cell--detail,
.cell--important {
border-width: 4px;
}
```
<a name="organization"></a>
## 7. Organisering
Organisering af kode er en vigtig del af enhver CSS kodebase, og livsnødvendig
for store kodebaser.
* Lav en logisk separering mellem særskilte stumper af kode.
* Brug separate filer (sammenkædes i et build) for at bryde koden op i
særskilte komponenter.
* Hvis du bruger en preprocessor, opsættes fælles kode i variabler for farver,
typografi osv.
<a name="build-and-deployment"></a>
## 8. Builds og udrulning
Forud for brug i live-miljøer, bør projekter altid forsøge at inkludere en
generisk metode til at linte, teste, komprimere og versionere koden. Til dette
formål er [grunt](https://github.com/cowboy/grunt) af Ben Alman et fremragende
værktøj.
<a name="acknowledgements"></a>
## Anerkendelser
Tak til alle der har bidraget til
[idiomatic.js](https://github.com/rwldrn/idiomatic.js). I har været en
fantastisk kilde til inspiration, noteringer og retningslinjer.
================================================
FILE: translations/de-DE/README.md
================================================
# Grundlagen zum Schreiben von einheitlichem, idiomatischem CSS
Das folgende Dokument legt eine vernünftige Gestaltungsrichtlinie für die
CSS-Entwicklung dar. Diese Richtlinien ermutigen zur Verwendung existierender,
üblicher und sinnvoller Muster. Sie sollten nach Bedarf angepasst werden, um
eine eigene Gestaltungsrichtlinie zu erstellen.
Dies ist ein lebendiges Dokument, und neue Ideen sind immer willkommen. Bitte
trage bei.
[Idiomatic CSS auf englisch](https://github.com/necolas/idiomatic-css/).
## Inhaltsverzeichnis
1. [Allgemeine Grundlagen](#general-principles)
2. [Leerraum](#whitespace)
3. [Kommentare](#comments)
4. [Formatierung](#format)
5. [Praktisches Beispiel](#example)
[Danksagung](#acknowledgements)
[Lizenz](#license)
<a name="general-principles"></a>
## 1. Allgemeine Grundlagen
> „Ein Teil der Aufgabe eines guten Verwalters eines erfolgreichen Projekts ist
> es, zu realisieren, dass Code für sich selbst zu schreiben eine schlechte
> Idee™ ist. Wenn tausende Leute deinen Code verwenden, dann schreibe deinen
> Code für maximale Klarheit, nicht nach deinen persönlichen Vorlieben, wie
> man innerhalb der Spezifikation gerissen sein kann.“ - Idan Gazit
* Du bist kein menschlicher Code-Compiler/Kompressor, versuche also nicht,
einer zu sein.
* Der gesamte Code in jeder Code-Basis soll aussehen wie von einer einzigen
Person eingegeben, unabhängig davon wieviele Leute beigetragen haben.
* Erzwinge den vereinbarten Stil streng.
* Im Zweifel bei einer Stilentscheidung verwende bestehende, übliche Muster.
<a name="whitespace"></a>
## 2. Leerraum
Nur ein Stil soll in den gesamten Quellen deines Projekts existieren. Sei
stets konsistent beim Einsatz von Leerraum. Verwende Leerraum, um die
Lesbarkeit zu erhöhen.
* Mische _niemals_ Leerzeichen und Tabs zur Einrückung.
* Wähle zwischen weicher Einrückung (Leerzeichen) oder wirklichen Tabs. Bleibe
bei deiner Wahl ohne Abweichung. (Vorzug: Leerzeichen)
* Beim Einsatz von Leerzeichen wähle die Anzahl Zeichen pro Einrückebene.
(Vorzug: 4 Leerzeichen)
Tipp: Richte deinen Editor so ein, dass er unsichtbare Zeichen zeigt. Das
erlaubt dir, Leerzeichen am Zeilenende zu entfernen, unbeabsichtigte
Leerzeichen in leeren Zeilen und Commits zu verschmutzen.
Tipp: Verwende eine [EditorConfig](http://editorconfig.org/)-Datei (oder
entsprechend), um die grundlegenden Leerraum-Konventionen, die vereinbart
wurden, verwalten zu helfen.
<a name="comments"></a>
## 3. Kommentare
Gut kommentierter Code ist extrem wichtig. Nimm dir Zeit, Komponenten zu
beschreiben, wie sie arbeiten, welche Beschränkungen sie haben und wie sie
gebaut sind. Lass andere im Team nicht raten, was den Zweck von ungewöhnlichem
oder nicht offensichtlichem Code betrifft.
Der Kommentarstil soll einfach und konsistent innerhalb einer einzelnen
Code-Basis sein.
* Platziere Kommentare auf neuen Zeilen über ihrem Gegenstand.
* Behalte die Zeilenlänge bei einem sinnvollen Maximum, z.B. 80 Spalten.
* Mache großzügigen Gebrauch von Kommentaren, um CSS in einzelne Abschnitte zu
unterteilen.
* Beginne mit einem Großbuchstaben und verwende konsistente Einrückung.
Tip: Konfiguriere deinen Editor so, dass er Kürzel für die Ausgabe von
ausgemachten Kommentar-Mustern anbietet.
Beispiel:
```css
/* ==========================================================================
Abschnitt Kommentar-Block
========================================================================== */
/* Unterabschnitt Kommentar-Block
========================================================================== */
/**
* Kurze Beschreibung im Doxygen-Stilformat
*
* Der erste Satz der langen Beschreibung beginnt hier und wird auf dieser
* Zeile für eine Weile fortgeführt, bis er schließlich hier endet.
*
* Die lange Beschreibung ist ideal für detailliertere Erläuterungen und
* Dokumentation. Sie kann Beispiel-HTML, URLs und andere Information
* beinhalten, die nützlich oder notwendig erscheint.
*
* @tag Dies ist ein Schlagwort namens 'tag'
*
* @todo Dies ist eine Todo-Angabe, die eine unteilbare Aufgabe beschreibt,
* die später vollendet wird. Sie bricht nach 80 Zeichen um und folgende
* Zeilen sind mit zwei Leerzeichen eingerückt.
*/
/* Einfacher Kommentar */
```
<a name="format"></a>
## 4. Formatierung
Die gewählte Codeformatierung muss gewährleisten, dass der Code: leicht zu
lesen ist; leicht klar zu kommentieren ist; nicht dazu verleitet, unabsichtlich
Fehler einzuführen; und zu nützlichen Diffs und Blames der Versionsverwaltung
führt.
* Verwende einen einzelnen Selektor pro Zeile in Multi-Selektor-Regelsets.
* Füge ein einzelnes Leerzeichen vor der öffnenden Klammer eines Regelsets ein.
* Füge eine Deklaration pro Zeile in einem Deklarationsblock ein.
* Verwende eine Einrückungsebene für jede Deklaration.
* Füge ein einzelnes Leerzeichen nach dem Doppelpunkt jeder Deklaration ein.
* Verwende Kleinbuchstaben und Kurzschreibweise bei Hexwerten, z. B. `#aaa`.
* Verwende einfache oder doppelte Anführungszeichen konsistent. Doppelte
Anführungszeichen werden bevorzugt, z. B. `content: ""`.
* Setze Attributwerte in Selektoren in Anführungszeichen, z. B.
`input[type="checkbox"]`.
* _Wo es erlaubt ist,_ vermeide die Angabe von Einheiten für Nullwerte, z. B.
`margin: 0`.
* Füge ein Leerzeichen nach jedem Komma ein bei komma-getrennten Eigenschaften
oder Funktionswerten.
* Füge einen Strichpunkt nach der letzten Deklaration in einem
Deklarationsblock ein.
* Platziere die schließende Klammer eines Regelsets in derselben Spalte wie
das erste Zeichen des Regelsets.
* Trenne jedes Regelset mit einer Leerzeile.
```css
.selektor-1,
.selektor-2,
.selektor-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, #bbb);
background: linear-gradient(#fff, rgba(0, 0, 0, 0.8));
}
.selektor-a,
.selektor-b {
padding: 10px;
}
```
#### Deklarations-Reihenfolge
Deklarationen sollen nach einem einzelnen, einfachen Prinzip sortiert werden,
wenn sie geordnet werden. Ich bevorzuge es, strukturell wichtige Eigenschaften
(z.B. Positionierung und Box-Modell) vor allen anderen zu notieren.
```css
.selektor {
/* Positionierung */
position: absolute;
z-index: 10;
top: 0;
right: 0;
bottom: 0;
left: 0;
/* Anzeige & Box-Modell */
display: inline-block;
overflow: hidden;
box-sizing: border-box;
width: 100px;
height: 100px;
padding: 10px;
border: 10px solid #333;
margin: 10px;
/* Andere */
background: #000;
color: #fff;
font-family: sans-serif;
font-size: 16px;
text-align: right;
}
```
Streng alphabetische Sortierung ist ebenfalls populär, hat aber den Nachteil,
dass sie verwandte Eigenschaften trennt. Zum Beispiel sind Positions-Versätze
nicht mehr zusammen gruppiert und Box-Modell-Eigenschaften können sich über
einen ganzen Deklarationsblock verteilt wiederfinden.
#### Ausnahmen und leichte Abweichungen
Große Blöcke mit einzelnen Deklarationen können ein leicht unterschiedliches,
einzeiliges Format verwenden. In diesem Fall wird ein Leerzeichen nach der
öffnenden und vor der schließenden Klammer eingefügt.
```css
.selektor-1 { width: 10%; }
.selektor-2 { width: 20%; }
.selektor-3 { width: 30%; }
```
Lange, komma-getrennte Eigenschaftswerte - wie Sammlungen von Gradienten oder
Schatten - können über mehrere Zeilen angeordnet werden, um die Lesbarkeit zu
erhöhen und nützlichere Diffs zu produzieren. Es gibt verschiedene
Formatierungen, die verwendet werden können; ein Beispiel ist im Folgenden
gezeigt.
```css
.selektor {
background-image:
linear-gradient(#fff, #ccc),
linear-gradient(#f3c, #4ec);
box-shadow:
1px 1px 1px #000,
2px 2px 1px 1px #ccc inset;
}
```
### Präprozessoren: Zusätzliche Formatier-Überlegungen
Verschiedene CSS-Präprozessoren haben verschiedene Besonderheiten,
Funktionalität und Syntax. Deine Konventionen sollen so erweitert werden, dass
sie den Eigenheiten jedes verwendeten Präprozessors Rechnung tragen. Die
folgenden Richtlinien beziehen sich auf Sass.
* Beschränke Verschachtelungen auf eine Ebene Tiefe. Überprüfe jede
Verschachtelung tiefer als 2 Ebenen. Das verhindert übermäßg spezifische
CSS-Selektoren.
* Vermeide große Mengen verschachtelter Regeln. Brich sie in Teile auf, wenn
Lesbarkeit beeinträchtigt wird. Der Vorzug gilt dem Vermeiden von
verschachtelten Anweisungen mit mehr als 20 Zeilen Länge.
* Setze `@extend`-Angaben immer in die erste Zeile eines Deklarationsblocks.
* Wo möglich gruppiere `@include`-Angaben am Anfang eines Deklarationsblocks,
nach jedem `@extend`.
* Ziehe in Betracht, eigenen Funktionen `x-` oder einen anderen Namensraum
voranzustellen. Das hilft zu verhindern, dass deine Funktionen mit nativen
CSS-Funktionen verwechselt werden oder mit Funktionen anderer Bibliotheken
kollidieren.
```scss
.selektor-1 {
@extend .andere-regel;
@include clearfix();
@include box-sizing(border-box);
width: x-grid-unit(1);
// andere Deklarationen
}
```
<a name="example"></a>
## 5. Praktisches Beispiel
Ein Beispiel verschiedener Konventionen.
```css
/* ==========================================================================
Rasterlayout
========================================================================== */
/**
* Beispiel-Layout mit horizontalem Scrollen.
*
* Dies erzeugt eine Reihe von maximal-hohen, nicht umbrechenden Spalten, die
* horizontal innerhalb ihres Elternelements durchsucht werden können.
*
* Beispiel-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
* Darf nur `.cell`-Kinder enthalten.
*/
.grid {
height: 100%;
/* Verhindere Leerraum in Zellen */
font-size: 0;
/* Hindere inline-block-Zellen am Umbruch */
white-space: nowrap;
}
/**
* Grid-Zellen
* Keine vorgegebene Breite. Erweitere mit `.cell-n`-Klassen.
*/
.cell {
position: relative;
display: inline-block;
overflow: hidden;
box-sizing: border-box;
height: 100%;
/* Setzt den Abstand zwischen Zellen */
padding: 0 10px;
border: 2px solid #333;
vertical-align: top;
/* Stellt Leerraum wieder her */
white-space: normal;
/* Stellt Schriftgröße wieder her */
font-size: 16px;
}
/* Zell-Zustände */
.cell.is-animating {
background-color: #fffdec;
}
/* Zell-Abmessungen
========================================================================== */
.cell-1 { width: 10%; }
.cell-2 { width: 20%; }
.cell-3 { width: 30%; }
.cell-4 { width: 40%; }
.cell-5 { width: 50%; }
/* Zell-Modifikatoren
========================================================================== */
.cell--detail,
.cell--important {
border-width: 4px;
}
```
<a name="acknowledgements"></a>
## Danksagung
Danke an alle, die Übersetzungen erstellt haben und all jene, die zu
[idiomatic.js](https://github.com/rwldrn/idiomatic.js) beigetragen haben. Es
war eine Quelle der Inspiration, von Zitaten und Richtlinien.
<a name="license"></a>
## Lizenz
_Grundlagen zum Schreiben von einheitlichem, idiomatischem CSS_ von Nicolas
Gallagherist lizenziert unter der [Creative Commons Attribution 3.0
Unported-License](http://creativecommons.org/licenses/by/3.0/). Dies trifft
auf alle Dokumente und Übersetzungen in diesem Repository zu.
Basierend auf einer Arbeit auf
[github.com/necolas/idiomatic-css](https://github.com/necolas/idiomatic-css).
================================================
FILE: translations/es-ES/README.md
================================================
# Principios para escribir CSS idiomático y consistente
El siguiente documento ofrece una guía razonable de estilo para el desarrollo
de CSS. No es mi intención ser preceptivo y no deseo imponer mis preferencias
de estilo en el código de otras personas. Sin embargo esta guía anima
enérgicamente a que se utilicen los patrones existentes, que son de sentido
común.
Este es un documento vivo y nuevas ideas son siempre bienvenidas. Por favor
contribuya.
[CSS idiomático en inglés (Original)](https://github.com/necolas/idiomatic-css/)
## Tabla de contenido
1. [Principios generales](#general-principles)
2. [Espacios en blanco](#whitespace)
3. [Comentarios](#comments)
4. [Formato](#format)
5. [Nomenclatura](#naming)
6. [Ejemplos prácticos](#example)
7. [Organización](#organization)
8. [Construcción y distribución](#build-and-deployment)
[Agradecimientos](#acknowledgements)
<a name="general-principles"></a>
## 1. Principios generales
> "Parte de ser un buen administrador al crear un proyecto exitoso es darse
> cuenta que escribir código para uno mismo es una Mala Idea™. Si miles de
> personas están utilizando tu código, entonces escríbelo con la máxima
> claridad, no con tus preferencias personales de cómo ser inteligente con la
> especificación." - Idan Gazit
* Todo el código en una aplicación debe parecer como si sólo una persona lo
hubiese escrito, no importa cuántas personas hayan contribuido.
* Fuerce a que se respete el estilo acordado.
* Si tiene dudas utilice los patrones de uso común.
<a name="whitespace"></a>
## 2. Espacios en blanco
Sólo debe existir un estilo en el código de su proyecto. Siempre sea
consistente en el uso de los espacios en blanco. Utilice espacios en blanco
para mejorar la legibilidad.
* _Nunca_ mezcle espacios y tabulaciones para indentar.
* Elija entre indentaciones blandas (espacios) o tabulaciones reales. Apéguese
a su elección sin fallo. (Preferencia: espacios)
* Si utiliza espacios, elija el número de caracteres a usar para cada nivel de
indentación. (Preferencia: 4 espacios)
Consejo: configure su editor para que "muestre los caracteres invisibles". Esto
le permitirá eliminar los espacios en blanco al final de las líneas, eliminar
espacios en blanco de líneas en blanco y evitar commits con basura.
Consejo: Utilice el editor [EditorConfig](http://editorconfig.org/) (o algún
equivalente) para ayudarse a mantener las convenciones básicas que han sido
acordadas en su proyecto.
<a name="comments"></a>
## 3. Comentarios
Un código bien comentado es muy importante. Tómese el tiempo necesario para
describir los componente, cómo trabajan, sus limitaciones y la forma en que
fueron construidos. No deje que otros miembros de su equipo tengan que adivinar
el propósito de un código poco común o poco obvio.
El estilo de los comentarios debe ser siempre simple y consistente con un mismo
código base.
* Coloque los comentarios en una línea nueva sobre cada objeto.
* Evite los comentarios al final de las líneas.
* Mantenga el largo de cada línea con un máximo razonable, por ejemplo, 80
columnas.
* Haga un uso libre de los comentarios para separar código CSS en secciones
discretas.
* Realice comentarios que comiencen con una letra mayúscula y con indentación
consistente.
Consejo: configure su editor para que le ofrezca atajos para la creación de
comentarios comunes.
#### Ejemplo de CSS:
```css
/* ==========================================================================
Bloque de comentario de sección
========================================================================== */
/* Bloque de comentario de sub-sección
========================================================================== */
/*
* Pequeña descripción utilizando el formato de comentario Doxygen.
*
* La primer oración de una descripción larga comienza aquí y continúa en
* esta linea durante un tiempo para finalmente terminar aquí al final de
* este párrafo.
*
* Las descripciones largas son ideales para explicaciones de mayor detalle
* y documentación. Pueden incluir ejemplos de HTML, URLs o cualquier otro
* tipo de información que es considerada necesaria o útil.
*
* @tag Esto es una etiqueta llamada 'tag'
*
* @todo Esto es una declaración 'todo' ("a realizar") que describe una tarea
* atómica (específica) a realizar posteriormente. Continua luego de 80
* caracteres por lo que las lineas consecutivas son indentadas con dos
* espacios adicionales.
*/
/* Comentario básico */
```
<a name="format"></a>
## 4. Formato
El formato del código elegido debe asegurarse de que el código: es fácil de
leer, es fácil de comentar claramente, minimiza las posibilidades de introducir
errores accidentalmente, y facilita el hallazgo de diferencias y
responsabilidades.
* Utilice un selector discreto por línea en un conjunto de reglas con multi
selectores.
* Incluya un solo espacio antes de la llave de apertura en un conjunto de
reglas.
* Incluya una declaración por línea en un bloque de declaraciones.
* Utilice un nivel de indentación para cada declaración.
* Incluya un solo espacio luego de los dos puntos en una declaración.
* Utilice minúsculas y valores hexadecimales abreviados, ejemplo `#aaa`.
* Utilice comillas simples o dobles pero de forma consistente. Se prefiere la
utilización de comillas dobles, ejemplo `content: ""`.
* Utilice comillas en los valores de los atributos de los selectores, ejemplo
`input[type="checkbox"]`.
* _Siempre que pueda_, evite especificar valores de 0, por ejemplo `margin:
0`.
* Incluya un espacio luego de cada coma en las propiedades separadas por comas
o en los valores de las funciones.
* Siempre incluya un punto y coma al final de la línea de la última declaración
en un bloque de declaraciones.
* Coloque la llave de cierre de un conjunto de reglas en la misma columna que
el primer carácter del conjunto.
* Separe cada conjunto de reglas con una línea en blanco.
```css
.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));
}
```
#### Orden de las declaraciones
Las declaraciones deben ser ordenadas con un único principio. Mi preferencia es
que las propiedades relacionadas con la estructura (por ejemplo, de posición y
box-model) sean declaradas antes que las demás.
```css
.selector {
/* Posicionamiento */
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;
/* Otras */
background: #000;
color: #fff
font-family: sans-serif;
font-size: 16px;
text-align: right;
}
```
El ordenamiento alfabético es también muy popular, pero la desventaja es que
las propiedades relacionadas no se mantienen juntas. Por ejemplo, los
desplazamientos de posición no permanecen juntos y las propiedades de box-model
pueden ser esparcidas a través del bloque de declaraciones.
#### Excepciones y pequeñas desviaciones
Bloques grandes de una sola declaración pueden ser ligeramente diferentes,
utilizando el formato de una sola línea. En este caso, un espacio debe ser
incluido luego de la llave de apertura y antes de la llave de cierre.
```css
.selector-1 { width: 10%; }
.selector-2 { width: 20%; }
.selector-3 { width: 30%; }
```
Grandes propiedades de valores separados por coma -tal como una colección de
gradientes o sombras- pueden ser organizadas en múltiples líneas en un intento
de mejorar la legibilidad y producir visualizaciones de diferencias más
útiles. Hay varios formatos que pueden ser utilizados: uno, por ejemplo, es
mostrado más abajo.
```css
.selector {
background-image:
linear-gradient(#fff, #ccc),
linear-gradient(#f3c, #4ec);
box-shadow:
1px 1px 1px #000,
2px 2px 1px 1px #ccc inset;
}
```
### Preprocesadores: consideraciones a formatos adicionales
Cada preprocesador de CSS tiene sus características, funcionalidades y
sintaxis. Sus convenciones deben extenderse para adaptarse a las
particularidades de cada preprocesador en uso. La siguiente guía está referida
a Sass.
* Limítese a anidar con 1 nivel de profundidad. Corrija cualquier anidado de
más de 2 niveles. Esto previene que existan selectores de CSS muy
específicos.
* Evite realizar un gran número de reglas anidadas. Sepárelas cuando la
legibilidad comience a ser afectada. Se prefiere evitar el anidado que se
extiende a más de 20 líneas.
* Siempre coloque las declaraciones `@extend` en la primer línea de los bloques
declarativos.
* Dónde sea posible, agrupe las declaraciones `@include` en la parte superior
del bloque declarativo, luego de las declaraciones `@extend`.
* Considere prefijar funciones personalizadas con `x-` u otro separador. Esto
ayuda a evitar cualquier confusión potencial con una función nativa de CSS, o
entrar en conflicto con una función de alguna librería.
```scss
.selector-1 {
@extend .other-rule;
@include clearfix();
@include box-sizing(border-box);
width: x-grid-unit(1);
// other declarations
}
```
<a name="naming"></a>
## 5. Nomenclatura
La nomenclatura es difícil, pero muy importante. Es una parte crucial del
proceso de desarrollo y mantenimiento del proyecto, y le asegura a usted tener
una relativamente escalable interfaz entre su código HTML y CSS.
* Evite la _sistemática_ utilización de abreviaciones en los nombres de las
clases. No haga las cosas difíciles de entender.
* Utilice nombres claros y meditados para las _clases HTML_.
* Elija un comprensible y consistente patrón de nombres que tengan sentido
tanto para los archivos HTML como para los archivos CSS.
* Los selectores para los componentes deben utilizar nombres de clases; evite
la utilización de etiquetas genéricas e ids únicos.
```css
/* Ejemplo de código con nombres incorrectos */
.s-scr {
overflow: auto;
}
.cb {
background: #000;
}
/* Ejemplo de código con nombres correctos */
.is-scrollable {
overflow: auto;
}
.column-body {
background: #000;
}
```
<a name="example"></a>
## 6. Ejemplos prácticos
Un ejemplo de varias convenciones.
```css
/* ==========================================================================
Grid layout
========================================================================== */
/*
* Ejemplo HTML:
*
* <div class="grid">
* <div class="cell cell-5"></div>
* <div class="cell cell-5"></div>
* </div>
*/
.grid {
overflow: visible;
height: 100%;
/* Prevent inline-block cells wrapping */
white-space: nowrap;
/* Remove inter-cell whitespace */
font-size: 0;
}
.cell {
box-sizing: border-box;
position: relative;
overflow: hidden;
width: 20%;
height: 100%;
/* Set the inter-cell spacing */
padding: 0 10px;
border: 2px solid #333;
vertical-align: top;
/* Reset white-space */
white-space: normal;
/* Reset font-size */
font-size: 16px;
}
/* Estados de las celdas */
.cell.is-animating {
background-color: #fffdec;
}
/* Dimensiones de las celdas
========================================================================== */
.cell-1 { width: 10%; }
.cell-2 { width: 20%; }
.cell-3 { width: 30%; }
.cell-4 { width: 40%; }
.cell-5 { width: 50%; }
/* Modificadores de celdas
========================================================================== */
.cell--detail,
.cell--important {
border-width: 4px;
}
```
<a name="organization"></a>
## 7. Organización
La organización del código es una parte importante en cualquier base de código
CSS, y crucial para grandes bases de código.
* Separe las distintas partes de código de forma lógica.
* Utilice archivos independientes (unidos por un proceso de construcción) para
ayudar a separar código para distintos componentes.
* Si utiliza un preprocesador, abstraiga código común en variables para el
color, la tipografía, etc.
<a name="build-and-deployment"></a>
## 8. Construcción y distribución
Los proyectos deben siempre intentar incluir algunos medios genéricos para que
el código pueda ser verificado, probado, comprimido y versionado para luego ser
utilizado en producción. Para esta tarea,
[grunt](https://github.com/cowboy/grunt), de Ben Alman es una excelente
herramienta.
<a name="acknowledgements"></a>
## Agradecimientos
Gracias a todos los que han contribuido en
[idiomatic.js](https://github.com/rwldrn/idiomatic.js).
Ha sido fuente de inspiración, referencia y guía.
================================================
FILE: translations/fr-FR/README.md
================================================
# Principes d'écriture pour des CSS cohérents et idiomatiques
Le présent document liste des recommandations raisonnables pour le
développement CSS.
Il n'est pas destiné à être normatif et je ne souhaite pas imposer mes
préférences en matière de code à tout le monde. Toutefois, ces lignes
directrices encouragent fortement l'utilisation de conventions existantes,
communes et judicieuses.
Ceci est un document évolutif et les nouvelles idées sont toujours les
bienvenues.
Merci de bien vouloir contribuer.
[Idiomatic CSS en anglais](https://github.com/necolas/idiomatic-css/)
## Table des matières
1. [Principes généraux](#general-principles)
2. [Indentation](#whitespace)
3. [Commentaires](#comments)
4. [Format](#format)
5. [Nommage](#naming)
6. [Exemple pratique](#example)
7. [Organisation](#organization)
8. [Compilation et déploiement](#build-and-deployment)
[Remerciements](#acknowledgements)
<a name="general-principles"></a>
## 1. Principes généraux
> Une des clefs d'une bonne gestion de projet est de réaliser qu'écrire du code
> pour soi-même est une MAUVAISE IDÉE™. Si des milliers de personnes sont
> amenées à utiliser votre code, alors écrivez votre code en visant un maximum
> de clarté, et non en fonction de croyances personnelles comme la lecture de
> spécifications qui rendrait plus intelligent." - Idan Gazit
* Tout code présent dans n'importe quelle base de code doit avoir l'air d'avoir
été écrit par une seule personne, peu importe le nombre de gens qui y ont
contribué ;
* Appliquez les conventions de style de manière stricte ;
* En cas de doute, utilisez des conventions existantes et communes.
<a name="whitespace"></a>
## 2. Indentation
Une seule manière d‘indenter devrait être utilisée sur l'ensemble du code
source de votre projet. Soyez toujours constant dans votre façon d‘indenter.
Utilisez des espaces pour améliorer la lisibilité.
* Ne mélangez _jamais_ les espaces et les tabulations pour l'indentation.
* Choisissez entre des espaces ou de vraies tabulations. Tenez-vous en à votre
choix sans y déroger. (Préference : espaces)
* Si vous utilisez les espaces, choisissez le nombre de caractères utilisé pour
chaque niveau d'indentation. (Préference : 4 espaces)
Astuce : Configurez votre éditeur afin qu'il affiche les "caractères
invisibles". Cela vous permettra de supprimer les espaces en fin de ligne, les
espaces dans les lignes vides et évitera de polluer vos commits.
<a name="comments"></a>
## 3. Commentaires
Bien commenter son code est extrêmement important. Prenez le temps de décrire
les composants, comment ils fonctionnent, leurs limites, et la manière dont ils
sont conçus. Ne laissez pas les autres membres de l'équipe deviner le but d'un
code inhabituel ou non trivial.
La façon de commenter doit être simple et similaire dans toute base de code.
* Placez les commentaires sur une nouvelle ligne au-dessus de leur sujet ;
* Evitez les commentaires en fin de ligne ;
* Gardez une longueur de ligne de taille raisonnable, par exemple 80
caractères ;
* Utilisez les commentaires comme bon vous semble pour diviser le code CSS en
parties distinctes ;
* Rédigez vos commentaires avec des majuscules et des minuscules et gardez une
indentation constante pour le texte.
Astuce: Paramètrez votre éditeur pour qu'il vous fournisse des raccourcis
claviers qui produisent des commentaires conventionnels.
#### Exemple en CSS :
```css
/* ==========================================================================
Bloc de commentaire de section
========================================================================== */
/* Bloc de commentaire de sous-section
========================================================================== */
/*
* Groupe de bloc de commentaires.
* Parfait pour les explications sur plusieurs lignes et la documentation.
*/
/* Commentaire simple */
```
#### SCSS exemple :
```scss
// ==========================================================================
// Bloc de commentaire de section
// ==========================================================================
// Bloc de commentaire de sous-section
// ==========================================================================
//
// Groupe de bloc de commentaires.
// Parfait pour les explications sur plusieurs lignes
// et la documentation
// Commentaire simple
```
<a name="format"></a>
## 4. Format
Le format de code choisi doit assurer: une bonne lisibilité, des commentaires
clairs, une réduction des probabilités d'insertion accidentelle d'erreurs, et
la production de fichiers diff et de résolution des problèmes pratiques.
1. Un seul sélecteur par ligne dans les régles à plusieurs sélecteurs ;
2. Un espace avant l'accolade ouvrante d'une règle ;
3. Une déclaration par ligne dans un bloc de déclarations ;
5. Un espace après les deux points d'une déclaration ;
6. Ajoutez toujours un point-virgule à la fin de la dernière déclaration d’un
bloc ;
7. Fermez l'accolade d'une règle au même niveau que le premier caractère de la
règle ;
8. Sautez une ligne entre chaque règle.
```css
.selecteur-1,
.selecteur-2,
.selecteur-3 {
-webkit-box-sizing: border-box;
-moz-box-sizing: border-box;
box-sizing: border-box;
display: block;
color: #333;
background: #fff;
}
```
#### Ordre des déclarations
L'ordre des déclarations doit toujours obéir à la même règle. Je préfère
regrouper les règles connexes ensemble et déclarer les propriétés importantes
relatives à la structure (c-à-d le positionnement et le modèle de boîte) avant
les règles typographiques, l'arrière-plan et les couleurs.
```css
.selecteur {
position: relative;
display: block;
width: 50%;
height: 100px;
padding: 10px;
border: 0;
margin: 10px;
color: #fff
background: #000;
}
```
L'ordre alphabétique est également très utilisé, mais le problème est qu'il
sépare les propriétés liées. Par exemple, les décalages de positionnement ne
sont plus regroupés ensemble et les propriétés du modèle de boîte se retrouvent
éparpillées dans le bloc de déclaration.
#### Exceptions et légers écarts
De gros blocs de déclarations uniques peuvent utiliser un format légèrement
différent, regroupées sur une seule ligne. Dans ce cas, il faut insérer un
espace après l'accolade ouvrante et avant l'accolade fermante.
```css
.selecteur-1 { width: 10%; }
.selecteur-2 { width: 20%; }
.selecteur-3 { width: 30%; }
```
Les longues valeurs de propriétés, séparées par des virgules - comme des
ensembles de dégradés et d'ombres - peuvent être agencées sur plusieurs lignes
de manière à améliorer la lisibilité et produire des fichiers diff plus utiles.
Divers formats peuvent alors être utilisés comme le montre l'exemple donné
ci-dessous :
```css
.selecteur {
box-shadow:
1px 1px 1px #000,
2px 2px 1px 1px #ccc inset;
background-image:
linear-gradient(#fff, #ccc),
linear-gradient(#f3c, #4ec);
}
```
#### Divers
* Utilisez des minuscules pour les valeurs hexadécimales, exemple : `#aaa` ;
* Utilisez toujours le même type de guillemets. Ma préférence va aux doubles
guillemets, exemple : `content: ""` ;
* Utilisez toujours des guillemets pour les valeurs dans les sélecteurs,
exemple : `input[type="checkbox"]` ;
* _Lorsque c'est autorisé_, évitez de spécifier les unités pour les valeurs
nulles, exemple : `margin: 0`.
### Préprocesseurs: considérations additionnelles pour le formatage
Les différents préprocesseurs CSS offrent des possibilités, des fonctionnalités
et une syntaxe différentes. Vos conventions doivent être étendues pour
s'adapter aux particularités des préprocesseurs que vous utilisez. Les
conventions suivantes font référence à Sass.
* Limiter l'imbrication à un niveau de profondeur. Réexaminez toute imbrication
supérieure à deux niveaux de profondeur. Cela évite des sélecteurs CSS trop
spécifiques.
* Evitez d'imbriquer un trop grand nombre de règles, séparez les lorsque cela
nuit à la lisibilité. Je préfère éviter les imbrications qui dépassent les 20
lignes.
* Placez toujours les déclarations "@extend" en début de bloc.
* Si possible, regroupez toutes les déclarations "@include" en début de bloc
juste après les déclarations "@extend".
* Pensez à préfixer vos propres fonctions avec `x-` ou un autre espace de nom.
Cela permet d'éviter potentiellement de confondre votre fonction avec une
fonction native CSS, ou les conflits avec des fonctions provenant de
bibliothèques.
```scss
.selecteur-1 {
@extend .other-rule;
@include clearfix();
@include box-sizing(border-box);
width: x-grid-unit(1);
// other declarations
}
```
<a name="naming"></a>
## 5. Nommage
Vous n'êtes pas un compilateur/compresseur de code humain, alors ne prétendez
pas en être un.
Utilisez des noms clairs et réfléchis pour les classes HTML. Choisissez un
modèle de nommage cohérent et compréhensif qui a du sens à la fois dans les
fichiers HTML et dans les fichiers CSS.
```css
/* Exemple de code mal nommé */
.s-scr {
overflow: auto;
}
.cb {
background: #000;
}
/* Exemple de code bien nommé */
.is-scrollable {
overflow: auto;
}
.column-body {
background: #000;
}
```
<a name="example"></a>
## 6. Exemple pratique
Un exemple de divers conventions.
```css
/* ==========================================================================
Construction de la grille
========================================================================== */
/*
* Exemple de code HTML:
*
* <div class="grid">
* <div class="cell cell-5"></div>
* <div class="cell cell-5"></div>
* </div>
*/
.grid {
overflow: visible;
height: 100%;
/* Évite d'entourer les cellules avec un inline-block */
white-space: nowrap;
/* Suppression des espaces entre les cellules */
font-size: 0;
}
.cell {
box-sizing: border-box;
position: relative;
overflow: hidden;
width: 20%;
height: 100%;
/* Définition de l'espacement entre les cellules */
padding: 0 10px;
border: 2px solid #333;
vertical-align: top;
/* Réinitialisation de la gestion des espaces */
white-space: normal;
/* Réinitialisation de la taille de police */
font-size: 16px;
}
/* Etats des cellules */
.cell.is-animating {
background-color: #fffdec;
}
/* Dimensions des cellules
========================================================================== */
.cell-1 { width: 10%; }
.cell-2 { width: 20%; }
.cell-3 { width: 30%; }
.cell-4 { width: 40%; }
.cell-5 { width: 50%; }
/* Styles de cellule
========================================================================== */
.cell--detail,
.cell--important {
border-width: 4px;
}
```
<a name="organization"></a>
## 7. Organisation
L'organisation du code est une partie importante de n'importe quelle base de
code CSS et devient cruciale pour les grosses bases de code.
* Séparez de manière logique les différentes parties de code ;
* Utilisez des fichiers distincts (concaténés au cours de l'étape de
compilation) pour aider à découper le code en différents composants ;
* Si vous utilisez un préprocesseur, stockez le code récurrent dans des
variables pour la couleur, la typographie, etc.
<a name="build-and-deployment"></a>
## 8. Compilation et déploiement
Les projets devraient toujours essayer de mentionner des façons génériques
grâce auxquelles le code source peut être validé, testé, compressé et versionné
en préparation à l'utilisation en production. Pour cela,
[grunt](https://github.com/cowboy/grunt) de Ben Alman est un excellent outil.
<a name="acknowledgements"></a>
## Remerciements
Merci à tous ceux qui ont contribué à
[idiomatic.js](https://github.com/rwldrn/idiomatic.js). Cela a été une source
d'inspiration, de citations et de conventions.
================================================
FILE: translations/id-ID/README.md
================================================
# Prinsip Penulisan CSS yang Konsisten, Idiomatic
Dokumen dibawah ini menjelaskan petunjuk umum dalam pengembangan CSS. Petunjuk
ini sangat mengutamakan penggunaan pola umum yang ada. Dan sebaiknya digunakan
dalam Penulisan CSS sesuai kebutuhan anda.
Dokumen ini sedang digunakan oleh banyak orang, dan sangat terbuka dengan saran
yang masuk. Silahkan berpartisipasi.
## Daftar Isi
1. [Prinsip Umum](#general-principles)
2. [Whitespace](#whitespace)
3. [Komentas](#comments)
4. [Format](#format)
5. [Contoh Penggunaan](#example)
[Lisensi](#license)
[Kontribusi & Saran](#contribute)
<a name="general-principles"></a>
## 1. Prinsip Umum
> "Salah satu bagian untuk menjadi staf yang baik dalam Proyek adalah memahami
> bahwa menulis kode untuk diri sendiri adalah hal yang buruk. Jika ribuan
> sedang menggunakan kode anda, maka tulislah kode anda dengan jelas dan
> objektif, jangan menggunakan cara pribadi dalam memahami kode." - Idan
> Gazit
* Jangan mencoba menjadi manusia Compiler.
* Semua kode harus tampak seperti ditulis oleh satu orang, walaupun ada banyak
orang yang berpartisipasi.
* Melaksanakan pola yang disepakati dengan ketat.
* Jika ragu dengan pola tersebut, gunakan pola yang ada dan umum.
<a name="whitespace"></a>
## 2. Whitespace
Anda disarankan menggunakan satu pola dalam seluruh kode. Harap konsisten
dengan penggunaan whitespace pada kode. Gunakan Whitespace untuk memudahkan
pembacaan kode.
* _Hindari_ membaurkan Spasi dan Tab untuk indentasi.
* Pilih salah satu antara _Soft Indents_ (Spasi) atau Tab original. Yakinlah
akan pilihan anda. (Disarankan: Spasi)
* Jika menggunakan Spasi, pilih jumlah karakter yang digunakan ditiap
indentasi. (Disarankan: 4 Spasi)
Tip: Setting Editor anda untuk mengaktifkan "show invisibles". Hal ini
meperbolehkan anda menghapus whitespace yang tidak diinginkan.
Tip: Gunakan File [EditorConfig](http://editorconfig.org) (atau yang sejenis)
untuk membantu pengaturan Whitespace yang anda gunakan pada kode anda.
<a name="comments"></a>
## 3. Komentar
Kode yang dikomentari dengan baik sangatlah penting. Sisihkan waktu untuk
menjelaskan komponen, bagaimana mereka bekerja, dan cara penggunaannya. Jangan
membiarkan staf di Tim anda untuk menduga-duga atau menebak-nebak karena kode
yang kurang jelas.
Pola Komentar harus sederhana dan konsisten di setiap kode anda.
* Tempatkan Komentar di atas subjeknya.
* Tetapkan standar panjang karakter ditiap Komentar. Contoh: 80 Karakter
* Anda bebas untuk menentukan Komentar sebagai pemecah kode CSS menjadi
beberapa bagian.
* Gunakan "Sentence Case" pada Komentar dan penggunaan indentasi yang konsisten
Tip: Buat snippet pada Editor anda sebagai shortcut untuk Komentar yang akan
anda gunakan.
Contoh:
```css
/* ==========================================================================
Blok Bagian
========================================================================== */
/* Blok Sub-Bagian
========================================================================== */
/**
* Deskripsi Singkat menggunakan format Komentar Doxygen-style
*
* Kalimat pertama dari Deskripsi Detail dimulai di sini dan berlanjut di baris
* selanjutnya hingga sampai kepada kesimpulan pada akhir paragraf.
*
* Deskripsi Detail sangat ideal untuk Penjelasan yang lebih lengkap dan
* sebagai Dokumentasi. Disini anda dapat memasukkan contoh HTML, URL, atau
* informas-informasi lain yang berguna untuk penjelasan.
*
* @tag Tag ini dinamakan 'tag'
*
* @todo Ini adalah Statemen Todo yang mendeskripsikan tugas-tugas yang harus
* anda selesaikan di waktu yang akan datang. Bagian ini memilik panjang
* maksimal 80 karakter dan baris dibawahnya di indentasi menggunakan 2 spasi
*/
/* Komentar standar */
```
<a name="format"></a>
## 4. Format
Format kode yang anda gunakan harus memastikan bahwa kode tersebut: mudah
dibaca; mudah di-Komentari; meminimalkan kemungkinan kesalahan penggunaan;
dan menghasil _diff_ dan _blame_ yang berguna.
* Gunakan satu baris per selector, dalam deklarasi rule multi-selector.
* Masukkan satu Spasi sebelum Buka Kurung dalam deklarasi rule.
* Gunakan deklarasi per baris dalam blok deklarasi.
* Gunakan satu level indentasi di tiap blok deklarasi.
* Masukkan satu Spasi setelah tanda Titik Koma dalam deklarasi.
* Gunakan _lowercase_ untuk Short Nilai Hex. Contoh: `#aaa`.
* Gunakan salah satu dari tanda Kutip Satu atau Kutip Dua secara konsisten.
Disarankan Tanda Kutip Dua. Contoh: `content: ""`.
* Gunakan tanda kutip pada Nilai dari Attribute Selector. Contoh:
`input[type="checkbox"]`.
* _Jika Memungkinkan_ hindari memberi satuan unit pada Nilai Nol. Contoh:
`margin: 0`.
* Masukkan satu Spasi setelah Koma dalam Comma-Separated properti atau nilai
function.
* Tetap ikutkan Titik Koma setelah deklarasi properti akhir di dalam blok
deklarasi.
* Tempatkan tanda Tutup Kurung `}` pada blok deklarasi sesuai dengan posisi
kolom tanda Buka Kurung `{`.
* Pisahkan tiap blok deklarasi dengan Baris Kosong.
```css
.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;
}
```
#### Urutan Deklarasi
Jika anda mengurutkan deklarasi properti, maka anda harus menggunakan aturan
sederhana. Saran saya anda harus mendahulukan properti yang lebih penting
seperti Positioning, Box Model.
```css
.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;
}
```
Pengurutan propery berdasarkan Huruf juga cukup populer, tetapi kekurangannya
adalah dia memisahkan properti yang berhubungan. Contoh properti pendukung
dari position tidak lagi dikelompokkan bersama-sama dan akan menyebar di
seluruh blok deklarasi.
#### Pengecualian
Blok panjang dari deklarasi tunggal dapat ditulis secara berbeda, format satu
baris. Dalam kasus ini, satu Spasi dimasukkan setelah tanda Buka Kurung `{` dan
sebelum tanda Tutup Kurung `}`.
```css
.selector-1 { width: 10%; }
.selector-2 { width: 20%; }
.selector-3 { width: 30%; }
```
Nilai yang cukup panjang, Comma-separated seperti Nilai font-family, gradient,
dan box shadow dapat ditulis dengan memisahkan per baris dengan tujuan
memudahkan cara pembacaan dan menghasilkan diff yang berkualitas. Banyak format
yang dapat digunakan, berikut adalah salah satu contoh.
```css
.selector {
background-image:
linear-gradient(#fff, #ccc),
linear-gradient(#f3c, #4ec);
box-shadow:
1px 1px 1px #000,
2px 2px 1px 1px #ccc inset;
}
```
### Preprocessor: Tambahan Pertimbangan Format
CSS Preprocessor Berbeda juga mempunyai fitur, fungsi, dan syntax yang berbeda.
Aturan pola kode anda harus memadai dan cocok di tiap CSS Preprocessor.
Petunjuk di bawah ini di adaptasi dari petunjuk SASS.
* Batasi sarang _(nesting)_ satu level lebih dalam. Deklarasi kan deklarasi
blok yang melebihi dua level sarang. Hal ini mencegah selector menjadi
terlalu spesifik.
* Hindari menggunakan deklarasi rule bersarang yang berlebihan. Pisahkan
secepatnya ketika sudah mulai mengurangi tingkat kemudahan pembacaan kode.
Saran, hindari menggunakan deklarasi rule bersarang jika rulenya melebihi dari
20 baris.
* Selalu tempatkan statemen `@extend` pada baris pertama dari blok deklarasi.
* Jika memungkinkan, tempatkan `@include` statemen pada baris awal setelah
`@extend` statemen.
* Pertimbangkan menggunakan prefix `x-` atau prefix lainnya jika menggunakan
fungsi buatan. Hal ini membantu menghindari kebingungan menggunakan fungsi
asli dari CSS atau konflik dengan fungsi dari librari yang anda gunakan.
```scss
.selector-1 {
@extend .other-rule;
@include clearfix();
@include box-sizing(border-box);
width: x-grid-unit(1);
// other declarations
}
```
<a name="example"></a>
## 5. Contoh Penggunaan
Sebuah contoh dari aturan kode yang beragam.
```css
/* ==========================================================================
Grid layout
========================================================================== */
/**
* Column layout dengan horizontal scroll.
*
* Ini membuat satu baris full-height, non-wrap kolom yang bisa digunakan
* horizontal dengan parent mereka.
*
* Contoh 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
* Harus diisi oleh `.cell`
*/
.grid {
height: 100%;
/* Hilangkan inter-cell whitespace */
font-size: 0;
/* Cegah wrapping inline-block */
white-space: nowrap;
}
/**
* Grid cells
* Tidak ada spesifik width secara default. Extend dengan `.cell-n` class
*/
.cell {
position: relative;
display: inline-block;
overflow: hidden;
box-sizing: border-box;
height: 100%;
/* Set inter-cell spasi */
padding: 0 10px;
border: 2px solid #333;
vertical-align: top;
/* Reset white-space */
white-space: normal;
/* Reset font-size */
font-size: 16px;
}
/* Cell states */
.cell.is-animating {
background-color: #fffdec;
}
/* Dimensi Cell
========================================================================== */
.cell-1 { width: 10%; }
.cell-2 { width: 20%; }
.cell-3 { width: 30%; }
.cell-4 { width: 40%; }
.cell-5 { width: 50%; }
/* Cell Pengubah
========================================================================== */
.cell--detail,
.cell--important {
border-width: 4px;
}
```
<a name="license"></a>
## Lisensi
_Principles of writing consistent, idiomatic CSS_ oleh Nicolas Gallagher
dirilis dengan lisensi [Creative Commons Attribution 3.0 Unported
License](http://creativecommons.org/licenses/by/3.0/). Lisensi ini berlaku
untuk semua dokumen dan terjemahan di repository.
Dibuat berdasarkan proyek di
[github.com/necolas/idiomatic-css](https://github.com/necolas/idiomatic-css).
<a name="contribute"></a>
## Kontribusi & Saran
Jika anda ingin berpartisipasi dalam Proyek Penerjemahan ini, silahkan fork
[Idiomatic](http://github.com/novrian/idiomatic_id-ID).
================================================
FILE: translations/it-IT/README.md
================================================
# Princìpi per la scrittura di CSS consistente ed idiomatico
L'intento di questo documento è quello di esporre una ragionevole guida allo
stile per lo sviluppo del CSS. Queste linee guida incoraggiano al riutilizzo di
pattern già esistenti ed ampiamente testati dalla comunità. Si dovrebbe
cercare, infine, di adattare questi pattern alle proprie necessità in modo da
creare proprie regole ed un proprio stile.
Questo è un documento in continua evoluzione e nuove idee sono sempre bene
accette. Per favore contribuite.
[Leggi la versione originale in inglese](https://github.com/necolas/idiomatic-css)
## Tavola dei contenuti
1. [Princìpi generali](#general-principles)
2. [Spazio vuoto](#whitespace)
3. [Commenti](#comments)
4. [Formato](#format)
5. [Esempio pratico](#example)
[Ringraziamenti](#acknowledgments)
[Licenza](#license)
<a name="general-principles"></a>
## 1. Princìpi generali
> "Parte dell'essere un buon amministratore in un progetto votato al successo è
> capire che la scrittura di codice per sé stessi è una Cattiva Idea™. Se
> migliaia di persone usano il tuo codice, allora scrivi il tuo codice in modo
> che abbia la massima chiarezza, e non seguendo i tuoi gusti personali su come
> renderlo chiaro all'interno delle specifiche" - Idan Gazit
* Non cercare di ottimizzare in anticipo il tuo codice; cerca di mantenerlo
leggibile e comprensibile.
* Tutto il codice, in qualsiasi linguaggio sia, dovrebbe sembrare come scritto
da un'unica persona, anche quando molte persone vi stanno contribuendo.
* Rispettate al massimo lo stile prescelto.
* Nel dubbio, usate pattern comuni già esistenti e collaudati.
<a name="whitespace"></a>
# 2. Spazio vuoto
Dovrebbe esistere solo uno stile in tutto il sorgente del vostro progetto.
Siate sempre consistenti nell'uso dello spazio vuoto. Usate questo spazio per
migliorare la leggibilità.
* _Mai_ mischiare spazi e tabulazioni per i rientri.
* Scegliete tra rientri soft (spazi) o tabulazioni reali. Mantenete quella
scelta (preferenza: spazi).
* Se usate gli spazi, scegliete il numero di caratteri usati per il livello di
rientro (preferenza: 4 spazi).
Suggerimento: configurate il vostro editor in modo da "visualizzare i caratteri
invisibili" o rimuovere automaticamente gli spazio vuoti a fine linea.
Suggerimento: usate un file [EditorConfig](http://editorconfig.org/) (o
equivalente) per aiutarvi a mantenere le convenzioni di base relative allo
spazio vuoto che si è scelto di usare per il vostro codice.
<a name="comments"></a>
## 3. Commenti
Un codice ben commentato è estremamente importante. Prendetevi il tempo
necessario per descrivere i vari componenti, come funzionano, i loro limiti, ed
il modo in cui sono stati costruiti. Non create una situazione nella quale
altri membri del vostro team debbano cercare di immaginare il motivo ed il
funzionamento di codice non comune o poco chiaro.
Lo stile di un commento dovrebbe essere semplice e consistente all'interno di
una singola base di codice.
* Mettete i commenti su di una nuova linea che preceda il relativo soggetto.
* Mantenete una lunghezza massima per le linee, es. 80 colonne.
* Fate libero uso di commenti per spezzare il codice CSS in sezioni logiche più
piccole.
* Fate un uso corretto e consistente della grammatica, delle maiuscole e dei
rientri.
Suggerimento: configurate il vostro editor in modo che vi fornisca delle
scorciatoie per la gestione di pattern predefiniti per i commenti.
Esempio:
```css
/* ==========================================================================
Sezione blocco commento
========================================================================== */
/* Sotto sezione blocco commento
========================================================================== */
/**
* Breve descrizione utilizzando un formato nei commenti in stile Doxygen
*
* La prima frase di una lunga descrizione inizia qui e continua su questa
* linea per un po' fino alla sua conclusione qui alla fine di questo paragrafo.
*
* Una lunga descrizione è ideale per una più dettagliata spiegazione e
* documentazione. Essa può includere esempi in HTML, URL o qualsiasi altra
* informazione che riteniate importante o utile.
*
* @tag Questo è un 'tag'
*
* TODO: Questa è una dichiarazione 'todo' che descrive un'attività necessaria
* che dovrà essere completata in un momento successivo. Essa va a capo dopo
* 80 caratteri e le linee successive vengono rientrare di 2 spazi.
*/
/* Commento base */
```
<a name="format"></a>
## 4. Formato
Il formato scelto deve far sì che il codice: sia facile da leggere; sia facile
da commentare in modo chiaro; minimizzi la possibilità di introdurre
accidentalmente errori; dia risultati utili nei diff e blame.
* Un solo selettore per linea in set di regole con più selettori.
* Un singolo spazio prima della parentesi graffa di apertura di un set di
regole.
* Una dichiarazione per linea in un blocco dichiarativo.
* Un livello di rientro per ogni dichiarazione.
* Un singolo spazio dopo i due-punti di una dichiarazione.
* Usate valori esadecimali in minuscolo ed in forma abbreviata, es. `#aaa`.
* Usate apici e doppi apici in modo uniforme. La preferenza è per i doppi
apici, es. `content: ""`.
* Racchiudete in doppi apici i valori nei selettori, es.
`input[type="checkbox"]`.
* _Dove possibile_, evitate di specificare l'unità di misura per valori uguali
a zero, es. `margin: 0`.
* Includete uno spazio dopo ogni virgola, per le liste di proprietà separate da
virgola o per i valori nelle funzioni.
* Includete un punto-e-virgola alla fine dell'ultima dichiarazione in un blocco
dichiarativo.
* Mettete la parentesi graffa di chiusura di un set di regole, nella stessa
colonna del primo carattere del set di regole.
* Separate ogni set di regole con una linea vuota.
```css
.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;
}
```
#### Ordine di dichiarazione
Se le dichiarazioni devono essere ordinate in modo logico, esse dovrebbero
seguire un semplice ed unico criterio.
I piccoli team potrebbero preferire il raggruppamento delle proprietà (es.
posizionamento e box-model) per categoria.
```css
.selector {
/* Posizionamento */
position: relative;
z-index: 10;
top: 0;
right: 0;
bottom: 0;
left: 0;
/* Visualizzazione e box-model */
display: inline-block;
overflow: hidden;
box-sizing: border-box;
width: 100px;
height: 100px;
padding: 10px;
border: 10px solid #333;
margin: 10px;
/* Altro */
background: #000;
color: #fff;
font-family: sans-serif;
font-size: 16px;
text-align: right;
}
```
I grossi team potrebbero preferire la semplicità e facilità di manutenzione che
deriva dall'ordinamento alfabetico.
#### Eccezioni e piccole deviazioni
Grossi blocchi di dichiarazioni di una sola linea, possono usare un formato
leggermente differente, a linea singola. In questo caso, uno spazio dovrebbe
essere messo dopo la parentesi graffa di apertura e prima di quella di
chiusura.
```css
.selector-1 { width: 10%; }
.selector-2 { width: 20%; }
.selector-3 { width: 30%; }
```
Lunghe liste di valori di proprietà separate da virgole - come una collezione
di sfumature od ombre - possono essere suddivisi su più linee nel tentativo di
migliorarne la leggibilità e produrre diff più utili. Ci sono vari formati che
potrebbero essere usati; di seguito ne viene mostrato un esempio.
```css
.selector {
background-image:
linear-gradient(#fff, #ccc),
linear-gradient(#f3c, #4ec);
box-shadow:
1px 1px 1px #000,
2px 2px 1px 1px #ccc inset;
}
```
### Preprocessori: ulteriori considerazioni sul formato
Ogni preprocessore per CSS ha le sue caratteristiche, funzionalità e sintassi.
Le vostre convenzioni dovrebbero adattarsi per venire in contro alle
particolarità del preprocessore in uso. Quelle che seguono sono le linee guida
prendendo come riferimento Sass.
* Limitate la nidificazione ad 1 livello di profondità. Riarrangiate ogni
nidificazione con 2 o più livelli di profondità. Questo previene la creazione
di selettori CSS inutilmente troppo specifici.
* Evitate un numero elevato di regole nidificate. Spezzatele in blocchi logici
più piccoli quando cominciate a rendervi conto che la leggibilità inizia a
risentirne. Preferite di evitare nidificazioni che siano più lunghe di 20
linee.
* Come prima cosa in un blocco dichiarativo, mettete sempre le dichiarazioni
`@extend`.
* Dove possibile, raggruppate le dichiarazioni `@include` all'inizio di un
blocco dichiarativo, subito dopo le dichiarazioni `@extend`.
* Considerate l'idea di anteporre una `x-` o un altro namespace alle funzioni
personalizzate. Questo vi aiuterà ad evitare ogni potenziale errore dato
dalla confusione della vostra funzione con una funzione nativa del CSS o di
altre librerie.
```scss
.selector-1 {
@extend .other-rule;
@include clearfix();
@include box-sizing(border-box);
width: x-grid-unit(1);
// altre dichiarazioni
}
```
<a name="example"></a>
## 5. Esempio pratico
Un esempio di varie convenzioni.
```css
/* ==========================================================================
Layout a griglia
========================================================================== */
/**
* Layout a griglia con scroll orizzontale.
*
* Questo crea una singola riga di colonne, a piena altezza e che non vanno
* a capo, che può essere navigata orizzontalmente all'interno del suo
* contenitore.
*
* Esempio HTML:
*
* <div class="grid">
* <div class="cell cell-3"></div>
* <div class="cell cell-3"></div>
* <div class="cell cell-3"></div>
* </div>
*/
/**
* Contenitore griglia
*
* Deve contenere solo figli `.cell`.
*
* 1. Rimuove lo spazio tra le celle
* 2. Previene che le celle inline-block vadano a capo
*/
.grid {
height: 100%;
font-size: 0; /* 1 */
white-space: nowrap; /* 2 */
}
/**
* Celle della griglia
*
* Di default, nessuna larghezza esplicita. Estendible con le classi `.cell-n`.
*
* 1. Imposta la spaziatura tra le celle
* 2. Ripristina il white-space ereditato da `.grid`
* 3. Ripristina la dimensione del font ereditata da `.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 */
}
/* Stati delle celle */
.cell.is-animating {
background-color: #fffdec;
}
/* Larghezza delle celle
========================================================================== */
.cell-1 { width: 10%; }
.cell-2 { width: 20%; }
.cell-3 { width: 30%; }
.cell-4 { width: 40%; }
.cell-5 { width: 50%; }
/* Modificatori di cella
========================================================================== */
.cell--detail,
.cell--important {
border-width: 4px;
}
```
<a name="acknowledgments"></a>
## Ringraziamenti
Grazie a tutti coloro che hanno fornito le traduzioni e contribuito a
[idiomatic.js](https://github.com/rwldrn/idiomatic.js). È stato una fonte di
ispirazione, citazioni e linee guida.
<a name="license"></a>
## Licenza
_Princìpi per la scrittura di CSS consistente ed idiomatico_ di Nicolas
Gallagher è rilasciata sotto la [Creative Commons Attribution 3.0 Unported
License](http://creativecommons.org/licenses/by/3.0/), che viene applicata
anche a tutti i documenti e traduzioni contenuti in questo repository.
Lavoro basato su
[github.com/necolas/idiomatic-css](https://github.com/necolas/idiomatic-css).
================================================
FILE: translations/ja-JP/README.md
================================================
# 一貫性のあるCSSらしいCSSを書くための原則
以下の文書はCSS開発のための合理的なスタイルガイドの骨子です。
規範になるべきものではないし、私自身のスタイルの好みを他者のコードに押し付けるつもりは一切ありません。しかし、これらのガイドラインは現存する一般的で分別のあるパターンを利用することを推奨します。
このドキュメントは常に変わっていくものなので、新しいアイデアを常に求めています。ぜひアイデア等を投稿してください。
[一貫性のあるCSSらしいCSSを書くための原則の英語版はこちらから](https://github.com/necolas/idiomatic-css/)
## 目次
1. [一般原則](#general-principles)
2. [ホワイトスペース(余白)](#whitespace)
3. [コメント](#comments)
4. [フォーマット](#format)
5. [命名規則](#naming)
6. [実例](#example)
7. [編成](#organization)
8. [ビルドとデプロイ](#build-and-deployment)
[謝辞](#acknowledgements)
<a name="general-principles"></a>
## 1. 一般原則
> "成功を収めるプロジェクトをうまく管理することの一つが自分でコードを書いて実現する
> ということではない。もし多くの人があなたのコードを利用しているなら、仕様の
> 中にはあなたの好みではなく、最大限に明確なコードを書くべきである。" - Idan Gazit
* どんなに多くの人が貢献したとしても、どのコードも一人で書いたようにする。
* 同意の上のでのスタイルを厳格に守る。
* もし悩むようであれば常に現存する共通のパターンを利用する。
<a name="whitespace"></a>
## 2. ホワイトスペース(余白)
プロジェクト内全てのソースコードで1つのスタイルのみを利用すること。ホワイトスペース(余白)は常に一貫性を保つこと。そしてホワイトスペース(余白)を可読性を向上するために利用すること。
* インデントにはタブ、スペースを**絶対に**混在させないこと
* ソフトインデント(スペース)かタブのどちらかを選び、その選択を途中で変更しないこと(スペースを優先)
* もしスペースを利用する場合にインデントに利用する文字数を決めること (4スペースを優先)
ヒント: 利用しているエディタにて“隠しキャラクターの表示”が出来る様に設定すること。これで行の最後のホワイトスペースを削除し、意図的ではない空行を削除し、無駄なコミットを避ける。
<a name="comments"></a>
## 3. コメント
ソースコード上の詳細なコメントは非常に重要です。コンポーネントがどのように動作するのか、どんな制約があるのか、そしてどんな構成になっているかを説明すること。チーム内の他のメンバーが一般的でなく、明確でもないコードの目的を推測させることがないようにしてください。
コメントのスタイルはシンプルでかつソースコードベースの中で一貫性を保っている必要があります。
* コメントは対象になるコンポーネントの上の行に配置すること。
* コメントを宣言文の後に追加しないこと。
* 折り返し行は分別のある最大行以内におさめること。例: 80文字
* コメントを使ってCSSのコードを別々のセクションに分解すること。
* コメントの文頭を大文字にし、テキストインデントに一貫性を持たせること。
ヒント: エディタの設定でショートカットなどを用いて承諾済みのコメントパターンを出力できるようにしておく。
#### CSSの例:
```css
/* ==========================================================================
セクションコメントブロック
========================================================================== */
/* サブ・セクションコメントブロック
========================================================================== */
/*
* グループコメントブロック
* 複数行になるドキュメントや説明の際に最適
*/
/* 基本コメント */
```
#### SCSSの例:
```scss
// ==========================================================================
// セクションコメントブロック
// ==========================================================================
// サブ・セクションコメントブロック
// ==========================================================================
//
// グループコメントブロック
// 複数行になるドキュメントや説明の際に最適
//
// 基本コメント
```
<a name="format"></a>
## 4. フォーマット
選択したコードフォーマットはコードが: 読みやすく、コメントが明確で、意図しないエラーを最低限に防ぎ、かつdiffやblameなどのコマンドの利点が活かせる形であること。
1. 複数セレクタを持つルールセットの場合、セレクタを1行ずつ記述すること。
2. ルールセットの開き中カッコの前に1スペースを入れること。
3. 宣言ブロックないでは宣言を1行ずつ記述すること。
4. 各宣言で1レベルのインデントを行うこと。
5. 宣言文のコロンの後にに1スペースを入れること。
6. 宣言ブロック内の最後の宣言文には常にセミコロンを追加すること。
7. ルールセットの閉じ中括弧はルールセット内の1番始めの文字の位置に合わせること。
8. ルールセットは空行で分けること。
```css
.selector-1,
.selector-2,
.selector-3 {
-webkit-box-sizing: border-box;
-moz-box-sizing: border-box;
box-sizing: border-box;
display: block;
color: #333;
background: #fff;
}
```
#### 宣言順
宣言の順番は1つの原則に従って並べること。私の場合は関連するプロパティ同士でグループ化し、構造的に重要なプロパティ(例: ポジションやボックスモデル)はタイポグラフィー、バックグランド、カラーのプロパティよりも前に宣言するようにしている。
```css
.selector {
position: relative;
display: block;
width: 50%;
height: 100px;
padding: 10px;
border: 0;
margin: 10px;
color: #fff
background: #000;
}
```
アルファベット順もよく使われるが欠点は関連するプロパティ同士を分断してしまう点。例えば、ポジションのオフセットをグループ化できないし、ボックスモデルのプロパティは宣言ブロック内でバラバラに宣言されることになってしまいます。
#### 例外と少しの偏差
1行の宣言が数多くある場合、これまでと異なる1行フォーマットを利用することも可能です。この場合、中カッコの内側両端に1つのスペースを入れること。
```css
.selector-1 { width: 10%; }
.selector-2 { width: 20%; }
.selector-3 { width: 30%; }
```
グラデーションやシャドウなどの長く、コンマで分割できるプロパティ値を持つ場合、diffをより有効活用するために複数ラインを利用しても構いません。様々なフォーマットが考えられますが、以下はその内の1つです。
```css
.selector {
box-shadow:
1px 1px 1px #000,
2px 2px 1px 1px #ccc inset;
background-image:
linear-gradient(#fff, #ccc),
linear-gradient(#f3c, #4ec);
}
```
#### その他
* hex値は小文字を利用すること。例: `#aaa`
* シングル、ダブルクォートには一貫性を持つこと。推奨はダブルクォートです。例: `content: ""`
* セレクタ内の属性値は常にクォートで囲むこと。例: `input[type="checkbox"]`
* **可能な場合**にはゼロになる値に対して単位指定を行わないこと。例: `margin: 0`
### プリプロセッサ: 追加フォーマット
CSSプリプロセッサの特性、機能、シンタックスはツールによって全く異なります。規則は利用しているプリプロセッサの特性に併せて拡張してください。
以下のガイドラインはSassを対象としたものになります。
* 入れ子は1レベルに止めること。2レベル以上の入れ子構造になる場合は再度コードを見直すこと。これによりCSSのセレクタが必要以上に詳細になるのを防ぎます。
* 入れ子ルールを数多く利用しないこと。読みやすさに影響を与え始めるようであれば分割すること。入れ子ルール内に20以上のルールセットを置かないことを推奨します。
* `@extend`文は宣言ブロック内の1番上に記述すること。
* 可能な限り`@include`を宣言ブロック内、`@extend`の下にグループ化すること
* ネイティブCSSの機能とカスタムした機能との違いの混乱を避け、ライブラリからの関数との衝突を避けるためにカスタム関数に`x-`のようなプリフィックスを利用するか他のネームスペースをつけるようにすること。
```scss
.selector-1 {
@extend .other-rule;
@include clearfix();
@include box-sizing(border-box);
width: x-grid-unit(1);
// other declarations
}
```
<a name="naming"></a>
## 5. 命名規則
我々は人間コードコンパイラ、コンプレッサではないので、そのように振る舞う必要はありません。
HTMLのクラスは明確で熟慮された名前を使用すること。HTMLファイル、CSSファイル内の両方で理解しやすく、一貫性のある命名パターンを選ぶこと。
```css
/* 悪い命名規則の例 */
.s-scr {
overflow: auto;
}
.cb {
background: #000;
}
/* よりよい命名規則の例 */
.is-scrollable {
overflow: auto;
}
.column-body {
background: #000;
}
```
<a name="example"></a>
## 6. 実例
様々な規則の例
```css
/* ==========================================================================
グリッドレイアウト
========================================================================== */
/*
* HTML例:
*
* <div class="grid">
* <div class="cell cell-5"></div>
* <div class="cell cell-5"></div>
* </div>
*/
.grid {
overflow: visible;
height: 100%;
/* Prevent inline-block cells wrapping */
white-space: nowrap;
/* Remove inter-cell whitespace */
font-size: 0;
}
.cell {
box-sizing: border-box;
position: relative;
overflow: hidden;
width: 20%;
height: 100%;
/* Set the inter-cell spacing */
padding: 0 10px;
border: 2px solid #333;
vertical-align: top;
/* Reset white-space */
white-space: normal;
/* Reset font-size */
font-size: 16px;
}
/* Cellの状態 */
.cell.is-animating {
background-color: #fffdec;
}
/* Cellのサイズ
========================================================================== */
.cell-1 { width: 10%; }
.cell-2 { width: 20%; }
.cell-3 { width: 30%; }
.cell-4 { width: 40%; }
.cell-5 { width: 50%; }
/* Cellの修飾因子
========================================================================== */
.cell--detail,
.cell--important {
border-width: 4px;
}
```
<a name="organization"></a>
## 7. 編成
ソースコードの編成はどんなCSSコード内でも重要なパートになり、また巨大なコードベースの場合はさらに重要になります。
* ソースコードは論理的にはっきり異なることがわかるように分割すること
* コンポーネントの明白さを強めるために別ファイルにすること(ビルドステップで連結すること)
* プリプロセッサを利用している場合、共通なコード、タイポグラフィー、色などを変数にしておくこと
<a name="build-and-deployment"></a>
## 8. ビルドとデプロイ
プロジェクトは常にソースコードの文法チェック、テスト、圧縮、プロダクションへの準備のためのバージョンコントロールの手法を持つべきです。
これらのタスクにはBen Alman氏による[grunt](https://github.com/cowboy/grunt)が優れたツールです。
<a name="acknowledgements"></a>
## 謝辞
[idiomatic.js](https://github.com/rwldrn/idiomatic.js)に貢献した皆さんに感謝します。idoomatic.jsはインスピレーションであり、引用もし、ガイドラインとしても活用しました。
================================================
FILE: translations/ko-KR/README.md
================================================
# 일관성있는 CSS다운 CSS를 작성하기 위한 원칙
이하 문서는 CSS개발을 위한 합리적인 스타일가이드의 중요한 내용입니다.
규범이 될만한 것이라 하긴 좀 그렇고 스스로 스타일 작업시 즐겨쓰는 방식을 다른분들께 꼭 이렇게 해야 한다고 말하려는 의도는 전혀 없습니다. 단, 이런 가이드라인은 현존하는 일반적이며 분별력있는 페턴을 이용하는 것을 추천합니다.
이 문서는 계속 변경해 나갈 예정이므로 새로운 아이디어를 계속해서 추가해 나갈 생각입니다. 많은 아이디어들을 주시면 고맙겠습니다.
[일관성있는 CSS다운 CSS를 작성하기 위한 원칙](https://github.com/necolas/idiomatic-css/)
## 목차
1. [일반원칙](#general-principles)
2. [화이트스페이스(여백)](#whitespace)
3. [커맨트(주석)](#comments)
4. [포멧](#format)
5. [명명규칙](#naming)
6. [실례](#example)
7. [편성](#organization)
8. [빌드와 디플로이](#build-and-deployment)
[감사의 말](#acknowledgements)
<a name="general-principles"></a>
## 1. 일반규칙
> "성공을 거둔 프로젝트를 잘 관리하는 한 방법은 스스로 코드를 작성하여 실행해 보는것이다.
> 라고 말하는건 아니다. 혹시 많은 사람들이 당신의 코드를 이용하고 있다면, 사양은
> 당신의 취향이 아닌, 최대한 명확한 코드를 사용해야 한다." - Idan Gazit
* 아무리 많은 사람들이 참여했다고 하더라도, 코드는 한사람이 작성한 것처럼 보여야 한다.
* 동의하에 스타일을 엄격하게 지킨다.
* 혹시 고민하게 될 경우에는 현존하는 공통의 페턴을 이용한다.
<a name="whitespace"></a>
## 2. 화이트스페이스(여백)
프로젝트의 모든 소스코드에 한개의 스타일만을 사용할것. 화이트스페이스(여백)은 늘 일관성을 갖어야 한다. 그리고 화이트스페이스(여백)을 가독성을 향상시키기 위해서 이용해야 한다.
* 들여쓰기는 텝, 스페이스를 **절대로** 섞어서 사용해서는 안된다.
* 들여쓰기는 스페이스로 할지 아니면 텝으로 할지를 결정하고, 도중에 변경해서는 안된다.(스페이스 선호)
* 만약 스페이스를 이용하는 경우에 들여쓰기에 이용하는 문자수를 결정할 것.(4 스페이스 선호)
힌트: 이용하고 있는 에디터에 숨김문자표시기능을 활성화 해두자. 이걸로 행의 마지막에 스페이스를 삭제한다던가 불필요한 공백을 삭제하여 불필요한 커밋을 피할 수 있다.
<a name="comments"></a>
## 3. 커맨트(주석)
소스코드에 상세한 주석은 비상시에 중요하다. 컴포넌트가 어떤식으로 동작하는 건지, 어떤 제약이 있는지, 어떤 구성을 갖고 있는지를 설명할 수 있기 때문이다. 팀 내에서 다른 맴버가 일반적이지 않고 명확하지도 않은 코드를 추측하게끔 하는 일은 만들어서는 안된다.
주석의 스타일은 간단하고 소스코드안에서 일관성을 갖고 있을 필요가 있다.
* 주석은 대상이 되는 컴포넌트의 상단에 배치한다.
* 주석은 선언문의 뒤에 추가하지 않도록 한다.
* 행바꿈 折り返し行は分別のある最大行以内におさめること。例: 80文字
* 주석을 사용해서 CSS 코드를 따로따로 구분하기.
* 주석의 맨 앞자는 대문자로 하고 텍스트의 들여넣기는 일관성을 갖도록 한다.
힌트: 에디터의 설정에 스닙펫기능을 활용해서 정해진 주석페턴을 등록해놓고 사용하도록 한자.
#### CSS의 예:
```css
/* ==========================================================================
섹션 블럭
========================================================================== */
/* 서브 섹션 블럭
========================================================================== */
/*
* 그룹 블럭
* 여러행을 포함하고 있는 문서나 설명을 적을때 사용한다.
*/
/* 기본 주석 */
```
#### SCSS의 예:
```scss
// ==========================================================================
// 색션 블럭
// ==========================================================================
// 서브 섹션 블럭
// ==========================================================================
//
// 그룹 블럭
// 여러행을 포함하고 있는 문서나 설명을 적을때 사용한다.
//
// 기본 주석
```
<a name="format"></a>
## 4. 포멧
선택한 코드 포멧은 코드가 해독이 쉬운지, 주석이 명확한지, 예상치 못한 에러를 최대한 방지하고 있는지, 그리고 diff,blame과 같은 커멘드의 이점을 잘 활용하는 형태여야 한다.
1. 복수셀렉터를 갖고있는 룰셋의 경우, 셀러터를 한줄씩 기술할것.
2. 룰셋에서 맨 처음 괄호의 앞에 스페이스 한개를 둘것.
3. 선언 블럭 안에서는 선언을 한줄씩 기술할것.
4. 각 선언에 1레벨의 들여쓰기를 할것.
5. 선언문의 콜론뒤에 스페이스 한개를 둘것.
6. 선언 블럭안의 맨 마지막의 선언문에는 늘 세미콜론을 추가할 것.
7. 룰셋의 닫기괄호는 룰셋안의 첫번째 문자의 위치와 맞춘다.
8. 룰셋은 빈줄로 구분을 짓는다.
```css
.selector-1,
.selector-2,
.selector-3 {
-webkit-box-sizing: border-box;
-moz-box-sizing: border-box;
box-sizing: border-box;
display: block;
color: #333;
background: #fff;
}
```
#### 선언
선언 순서는 단 하나의 원칙에 따라서만 작성할 것. 저와 같은 경우엔 관련하는 프로퍼티끼리 그룹화하였고, 구조적으로 중요한 프로퍼티(예:포지션이나 박스모델)는 타이포그래피, 백그라운드, 컬러의 프로퍼티보다 먼저 선언하도록 하고 있습니다.
```css
.selector {
position: relative;
display: block;
width: 50%;
height: 100px;
padding: 10px;
border: 0;
margin: 10px;
color: #fff
background: #000;
}
```
알파벳순도 자주 사용되고 있지만 결점은 관련하는 프로퍼티끼리 떨어져있다는 점입니다. 예를 들어서 포지션의 옵셋을 그룹화할수가 없고, 박스모델의 프로퍼티는 선언블럭안에서 서로서로 떨어져서 선언 됩니다.
#### 예외와 작은 편차
한줄 선언의 수가 많아지게 되는 경우, 지금까지와는 다른 한줄포멧을 사용할 수 있습니다. 이 경우에는 중괄호 안쪽의 양쪽 끝에 스페이스를 한자 넣는 것입니다.
```css
.selector-1 { width: 10%; }
.selector-2 { width: 20%; }
.selector-3 { width: 30%; }
```
그라데이션이나 쉐도우같이 길고, 컴마로 구분하여 사용하는 프로퍼티값을 갖고있는 경우에는 diff를 좀 더 유용하게 활용하기 위해 여러줄을 사용해도 괜찮습니다. 여러가지의 포맷이 있을 것으로 생각되지만 밑에 적은것과 비슷한 형태일 것입니다.
```css
.selector {
box-shadow:
1px 1px 1px #000,
2px 2px 1px 1px #ccc inset;
background-image:
linear-gradient(#fff, #ccc),
linear-gradient(#f3c, #4ec);
}
```
#### 그 외...
* hex값은 소문자를 이용할 것. 예: `#aaa`
* 싱글따옴표, 더블따옴표에는 일관성을 둘 것. 추천하는 것은 더블따옴표입니다. 예: `content: ""`
* 셀렉터안의 속성치는 늘 따옴표로 감쌀 것. 예: `input[type="checkbox"]`
* **가능한 경우**에는 0이 되는 값에는 단위지정을 하지 않는다. 例: `margin: 0`
### 프리프로세서:추가 포멧
CSS프리프로세서의 특성, 기능, 신텍스는 툴에 의해서 전혀 틀립니다. 규칙은 이용하고 있는 프리프로세서의 특성에 맞춰서 확장하세요.
이후의 가이드라인은 SASS를 대상으로 하고 있습니다.
* 코드블럭(nesting)은 한단계만 들여쓰도록 한다. 2단계이상 들어간 중첩요소들이 있는 구조라면 다시한번 코드를 고쳐야 한다. 이렇게 함으로써 CSS셀렉터가 필요이상 상세해 지는걸 막을 수 있다.
* 코드블럭 작성룰은 여러가지를 사용하지 않도록 한다. 읽기 어려워 질것 같다면 나눠서 작성한다. 코드블럭에는 20개 이상의 룰셋을 두지 않도록 한는걸 추천한다.
* `@extend`문은 선언 블럭의 최상단에 기술한다.
* 가능한한 `@include`는 선언블럭안의 `@extend`의 밑에 그룹화 한다.
* 네이티브 CSS함수와 커스텀화한 함수의 차이를 알기 쉽게 하고, 라이브러리에서 함수의 충돌을 피하기 위해 커스텀화한 함수의 접두어로 'x-'를 사용한다던가 아니면 다른 네임스페이스를 지정하여 사용하도록 한다.
```scss
.selector-1 {
@extend .other-rule;
@include clearfix();
@include box-sizing(border-box);
width: x-grid-unit(1);
// other declarations
}
```
<a name="naming"></a>
## 5. 명명규칙
우리 인간은 코드컴파일러, 콤프레셔가 아니기 때문에 그렇게 행동할 필요는 없다.
HTML 클래스는 명확하고 심사숙고하여 만든 이름을 사용하여야 한다. HTML화일, CSS화일 안에서 서로가 알기 쉽도록, 일관성있는 명명 페턴을 선택해야 한다.
```css
/* 안좋은 명명규칙의 예 */
.s-scr {
overflow: auto;
}
.cb {
background: #000;
}
/* 좀 더 낳은 명명규칙의 예 */
.is-scrollable {
overflow: auto;
}
.column-body {
background: #000;
}
```
<a name="example"></a>
## 6. 실례
여러가지 규칙의 예
```css
/* ==========================================================================
그리드 레이아웃
========================================================================== */
/*
* HTML예:
*
* <div class="grid">
* <div class="cell cell-5"></div>
* <div class="cell cell-5"></div>
* </div>
*/
.grid {
overflow: visible;
height: 100%;
/* Prevent inline-block cells wrapping */
white-space: nowrap;
/* Remove inter-cell whitespace */
font-size: 0;
}
.cell {
box-sizing: border-box;
position: relative;
overflow: hidden;
width: 20%;
height: 100%;
/* Set the inter-cell spacing */
padding: 0 10px;
border: 2px solid #333;
vertical-align: top;
/* Reset white-space */
white-space: normal;
/* Reset font-size */
font-size: 16px;
}
/* Cell 상태 */
.cell.is-animating {
background-color: #fffdec;
}
/* Cell 사이즈
========================================================================== */
.cell-1 { width: 10%; }
.cell-2 { width: 20%; }
.cell-3 { width: 30%; }
.cell-4 { width: 40%; }
.cell-5 { width: 50%; }
/* Cell 수식 인자
========================================================================== */
.cell--detail,
.cell--important {
border-width: 4px;
}
```
<a name="organization"></a>
## 7. 편성
소스코드의 편성은 어떤 CSS코드안에서도 중요한 부분이며 또한 거대한 코드베이스의 경우에는 더더욱 중요해진다.
* 소스코드는 논리적으로 확실하게 틀린부분을 이해할 수 있도록 잘 나눠놔야 한다.
* 컴포넌트의 명백함을 강화시키기 위해서 별도의 화일로 만든다.(빌드스텝에서 연결한다.)
* 프리프로세서를 이용하는 경우에는 공통의 코드, 타이포그래피, 색등을 변수로 정의 해둔다.
<a name="build-and-deployment"></a>
## 8. 빌드와 디플로이
프로젝트는 늘 소스코드의 문법체크, 테스트, 압축과 실제 사용에 앞서 버젼관리의 수단들을 갖추어야 합니다.
이런 테스크들은 Ben Alman씨에 의해서 만들어진 [grunt](https://github.com/cowboy/grunt)가 괜찮은 툴입니다.
<a name="acknowledgements"></a>
## 감사의 말
[idiomatic.js](https://github.com/rwldrn/idiomatic.js)에 참여해주신 여러분들께 감사드립니다. idiomatic.js는 기발한 생각이며、인용과 가이드라인의 원본입니다.
================================================
FILE: translations/nl-NL/README.md
================================================
# Principes voor het schrijven van consistente, idiomatische CSS
Het volgende document schetst een logische stijlgids voor het schrijven van
CSS. Het is niet normatief bedoeld en ik wens niet mijn stijlvoorkeuren op te
dringen aan andermans code. Deze richtlijnen zijn echter een sterke
aanmoediging voor het gebruik van bestaande, algemene, verstandige patronen.
Dit is een document in ontwikkeling en nieuwe ideeën zijn altijd welkom. Draag
alstublieft bij!
Andere vertalingen zijn te vinden in het [originele Engelse Idiomatic CSS
document](https://github.com/necolas/idiomatic-css).
## Inhoudsopgave
1. [Algemene principes](#general-principles)
2. [Witruimte](#whitespace)
3. [Commentaar](#comments)
4. [Opmaak](#format)
5. [Naamgeving](#naming)
6. [Praktisch voorbeeld](#example)
7. [Ordening](#organization)
8. [Build en deployment](#build-and-deployment)
[Dank](#acknowledgements)
<a name="general-principles"></a>
## 1. Algemene principes
> "Het zijn van een goed rentmeester van een succesvol project is deels het
> realiseren dat het schrijven van code voor jezelf een Slecht Idee™ is. Als
> duizenden mensen je code gebruiken schrijf je code dan voor maximale
> duidelijkheid, niet je persoonlijke voorkeur slim om te gaan binnen de
> specificatie." - Idan Gazit
* Alle code in elke codebase zou getypt moeten lijken door een enkel persoon,
ongeacht hoeveel personen een bijdrage leverden.
* Dwing de afgesproken stijl streng af.
* Gebruik bij twijfel bestaande, algemene patronen.
<a name="whitespace"></a>
## 2. Witruimte
In de hele broncode van uw project zou slechts één stijl moeten bestaan. Wees
altijd consistent in het gebruik van witruimte. Gebruik witruimte om de
leesbaarheid te bevorderen.
* Wissel _nooit_ het gebruik van tabs en spaties voor het inspringen van tekst
af.
* Kies tussen zacht inspringen (spaties) of echte tabs. En blijf daarbij
(voorkeur: spaties).
* Als u spaties gebruikt, kies het aantal karakters per niveau van inspringen
(voorkeur: 4 spaties)
Tip: Stel uw tekstverwerker in om "onzichtbare tekens te tonen". Dit stelt u in
staat witruimte aan regeleinden en onbedoelde witregels te verwijderen en
voorkomt vervuilde commits.
<a name="comments"></a>
## 3. Commentaar
Goed becommentarieerde code is extreem belangrijk. Neem de tijd om componenten
te beschrijven. Hoe deze werken, de beperkingen en de manier waarom deze zijn
samengesteld. Laat anderen in het team niet raden naar het doel van ongewone of
onduidelijke code.
De stijl van commentaar binnen broncode zou simpel en consistent moeten zijn.
* Plaats commentaar op een nieuwe regel boven het onderwerp.
* Vermijd commentaar aan het einde van een regel.
* Houdt regellengte tot een verstandig maximum: b.v. 80 kolommen.
* Maak ruim gebruik van commentaar om CSS-code op te breken in aparte
secties.
* Gebruik "standaard kapitalen"-commentaar en het consistent inspringen van
tekst.
Tip: Stel uw tekstverwerker in met toetscombinaties om de afgesproken algemene
patronen te genereren.
#### CSS-voorbeeld:
```css
/* ==========================================================================
Sectie commentaarblok
========================================================================== */
/* Subsectie commentaarblok
========================================================================== */
/*
* Groep commentaarblok.
* Ideaal voor uitleg over meerdere regels en documentatie.
*/
/* Standaard commentaar */
```
#### SCSS-voorbeeld:
```scss
// ==========================================================================
// Sectie commentaarblok
// ==========================================================================
// Subsectie commentaarblok
// ==========================================================================
//
// Groep commentaarblok
// Ideaal voor uitleg over meerdere regels en documentatie.
//
// Standaard commentaar
```
<a name="format"></a>
## 4. Opmaak
De gekozen code-opmaak moet verzekeren dat de code: makkelijk te lezen en te
becommentariëren is. Dit vermindert de kans op de onbedoelde introductie van
fouten en resulteert in bruikbare diffs en blames.
1. Eén aparte selector per regel en in multi-selector rulesets.
2. Eén afzonderlijke spatie voor de openings-accolade van een ruleset.
3. Eén declaratie per regel in een declaratieblok.
4. Eén inspringniveau voor elke declaratie.
5. Eén afzonderlijke spatie na de dubbele punt van een declaratie.
6. Voeg altijd een puntkomma aan het eind van de laatste declaratie in een
declaratieblok.
7. Plaats de afsluitende accolade van een ruleset in dezelfde kolom als het
eerste karakter van de ruleset.
8. Scheidt elke ruleset door een witregel.
```css
.selector-1,
.selector-2,
.selector-3 {
-webkit-box-sizing: border-box;
-moz-box-sizing: border-box;
box-sizing: border-box;
display: blok;
color: #333;
background: #fff;
}
```
#### Volgorde van declaraties
Declaraties dienen geordend te worden overeenkomstig een enkel principe. Mijn
voorkeur is dat gerelateerde eigenschappen gegroepeerd worden en dat
structureel belangrijke eigenschappen (b.v. positionering en box-model) voor
typografische-, achtergronds- en kleureigenschappen gedeclareerd worden.
```css
.selector {
position: relative;
display: blok;
width: 50%;
height: 100px;
padding: 10px;
border: 0;
margin: 10px;
color: #fff
background: #000;
}
```
Alfabetische volgorde is ook populair, maar het nadeel is dat dit gerelateerde
eigenschappen afzondert. Bijvoorbeeld: positie-afstanden zijn niet langer
gegroepeerd en box-modeleigenschappen kunnen door het hele declaratieblok
verspreid worden.
#### Uitzonderingen en kleine afwijkingen
Grote blokken alleenstaande declaraties kunnen een enigszins andere,
enkele-regel-opmaak gebruiken. In dit geval zou een spatie toegevoegd kunnen
worden na de openingsaccolade en voor de sluitende accolade.
```css
.selector-1 { width: 10%; }
.selector-2 { width: 20%; }
.selector-3 { width: 30%; }
```
Lange, kommagescheiden eigenschapwaarden - zoals sets aan verlopen of schaduwen
- kunnen gerangschikt kunnen worden over meerdere regels om de leesbaarheid en
beter bruikbare diffs te bevorderen. Er zijn verschillende opmaakstijlen die
gebruikt zouden kunnen worden; een voorbeeld is hieronder getoond.
```css
.selector {
box-shadow:
1px 1px 1px #000,
2px 2px 1px 1px #ccc inset;
background-image:
linear-gradient(#fff, #ccc),
linear-gradient(#f3c, #4ec);
}
```
#### Diversen
* Gebruik onderkast hex waarden, b.v., `#aaa`.
* Gebruik consistent enkele of dubbele aanhalingstekens. Dubbele
aanhalingstekens hebben de voorkeur, b.v. `content: ""`.
* Gebruik altijd aanhalingstekens bij attribuutwaarden in selectors, b.v.
`input[type="checkbox"]`.
* Vermijd, _indien toegestaan_, specifieke eenheden voor nulwaarden b.v.
`margin: 0`.
### Preprocessors: extra opmaakoverwegingen
Verschillende CSS preprocessors hebben verschillende kenmerken, functionaliteit
en syntaxis. Uw conventies zullen moeten worden afgestemd op de unieke
kenmerken van de gebruikte preprocessors. De volgende richtlijnen hebben
betrekking op Sass.
* Beperk geneste regels tot 1 niveau diep. Bekijk sets dieper dan 2 niveaus
opnieuw. Dit voorkomt te specifieke CSS-selectors.
* Voorkom grote aantallen geneste regels. Splits ze wanneer de leesbaarheid
verminderd. De voorkeur is om geneste regels van meer dan 20 regels te
vermijden.
* Plaats `@extend`-statements altijd op de eerste regel van een
declaratieblok.
* Groepeer `@include`-statements waar mogelijk bovenaan een declaratieblok, na
mogelijke `@extend`-statements.
* Overweeg een voorvoegsel van `x-` of een andere namespace voor eigen
functies. Dit voorkomt mogelijke verwarring van uw functies met een CSS-eigen
functie of een conflict met functies van andere libraries.
```scss
.selector-1 {
@extend .other-rule;
@include clearfix();
@include box-sizing(border-box);
width: x-grid-unit(1);
// andere declaraties
}
```
<a name="naming"></a>
## 5. Naamgeving
U bent geen menselijke codecompiler/compressor; probeer dit dan ook niet te
zijn.
Gebruik duidelijke en doordachte namen voor HTML classes. Kies een begrijpelijk
en consistent patroon voor naamgeving dat zowel in de HTML- als CSS-bestanden
voor zich spreekt.
```css
/* voorbeeld van code met slechte naamgeving */
.s-scr {
overflow: auto;
}
.cb {
background: #000;
}
/* Voorbeeld van code met betere naamgeving */
.is-scrollable {
overflow: auto;
}
.column-body {
background: #000;
}
```
<a name="example"></a>
## 6. Praktisch voorbeeld
Een voorbeeld van verschillende conventies.
```css
/* ==========================================================================
Grid lay-out
========================================================================== */
/*
* Voorbeeld HTML:
*
* <div class="grid">
* <div class="cell cell-5"></div>
* <div class="cell cell-5"></div>
* </div>
*/
.grid {
overflow: visible;
height: 100%;
/* Voorkom het omslaan van inline-block cellen */
white-space: nowrap;
/* Verwijder witruimte tussen cellen */
font-size: 0;
}
.cell {
box-sizing: border-box;
position: relative;
overflow: hidden;
width: 20%;
height: 100%;
/* Bepaal de ruimte tussen cellen */
padding: 0 10px;
border: 2px solid #333;
vertical-align: top;
/* Herstel witruimte */
white-space: normal;
/* Herstel font-size */
font-size: 16px;
}
/* Cel states */
.cell.is-animating {
background-color: #fffdec;
}
/* Celafmetingen
========================================================================== */
.cell-1 { width: 10%; }
.cell-2 { width: 20%; }
.cell-3 { width: 30%; }
.cell-4 { width: 40%; }
.cell-5 { width: 50%; }
/* Celaanpassingen
========================================================================== */
.cell--detail,
.cell--important {
border-width: 4px;
}
```
<a name="organization"></a>
## 7. Ordening
Code-organisatie is een belangrijk onderdeel van elke CSS codebase en cruciaal
voor grotere codebases.
* Verdeel logisch afzonderlijke codeonderdelen.
* Gebruik afzonderlijke bestanden (samengevoegd door een buildproces) om code
voor aparte componenten op te breken.
* Abstraheer algemene code in variabelen voor kleur, typografie enz. als
gebruik gemaakt wordt van een preprocessor.
<a name="build-and-deployment"></a>
## 8. Build en deployment
Projecten dienen altijd een generieke manier te bevatten om broncode te linten,
testen, comprimeren en van versienummer te voorzien in voorbereiding op gebruik
in productie. [grunt](https://github.com/cowboy/grunt) door Ben Alman is
hiervoor een uitstekende oplossing.
<a name="acknowledgements"></a> ## Dank
Dank voor iedereen die bijgedragen heeft aan
[idiomatic.js](https://github.com/rwldrn/idiomatic.js). Het was een bron van
inspiratie, citaties en richtlijnen.
================================================
FILE: translations/pl-PL/README.md
================================================
# Zasady tworzenia spójnych, zgodnych z regułami języka deklaracji CSS
Poniżej opisane zostały podstawowe zasady tworzenia arkuszy stylów. Nie jest
to uniwersalne czy wyczerpujące temat zestawienie. Intencją autora nie było
bowiem narzucanie jedynie słusznych rozwiązań, a raczej zachęta do stosowania
istniejących, wypróbowanych i uznanych wzorców.
Z tego samego powodu mile widziana będzie wszelka pomoc w dalszym rozwijaniu i
wzbogacaniu niniejszego dokumentu.
[Artykuł Idiomatic CSS w oryginale](https://github.com/necolas/idiomatic-css/)
## Spis treści
1. [Główne zasady](#general-principles)
2. [Wcięcia](#whitespace)
3. [Komentarze](#comments)
4. [Format](#format)
5. [Nazewnictwo](#naming)
6. [Przykłady praktyczne](#example)
7. [Organizacja](#organization)
8. [Przygotowanie i wdrożenie](#build-and-deployment)
[Podziękowania](#acknowledgements)
<a name="general-principles"></a>
## 1. Główne zasady
> „Pierwszym krokiem do stworzenia projektu, który odniesie sukces, jest
> zrozumienie, że pisanie kodu dla samego siebie to Bardzo Zły Pomysł®. Jeśli
> z twoich rozwiązań mają korzystać tysiące innych osób, nie pisz tak, jak
> lubisz, ale tak, by osiągnąć maksymalną przejrzystość.” - Idan Gazit
* Nie jesteś maszyną do kompilowania czy kompresowania kodu i nie staraj się
nią zostać.
* Kod powinien zawsze wyglądać tak, jakby napisał go jeden człowiek -
niezależnie od liczby osób współpracujących przy tym zadaniu.
* Trzymaj się ściśle ustalonych na wstępie reguł.
* Jeśli masz wątpliwości, korzystaj z istniejących, sprawdzonych rozwiązań.
<a name="whitespace"></a>
## 2. Wcięcia
W całym projekcie stosuj konsekwentnie tylko jeden styl wcięć. Nie zapominaj,
że wcięcia służą przede wszystkim czytelności kodu.
* _Nigdy_ nie stosuj równolegle spacji i tabulatorów.
* Wybierz jedną z powyższych metod do tworzenia wcięć (najlepiej spacje) i
trzymaj się jej.
* Jeśli używasz spacji, wybierz stałą liczbę znaków dla jednego poziomu wcięcia
(najlepiej cztery).
Wskazówka: włącz w swoim edytorze kodu opcję pokazywania znaków
niedrukowalnych. To pozwoli ci wyeliminować spacje na końcu linii i w pustych
wierszach.
Wskazówka: używaj pliku [EditorConfig](http://editorconfig.org/) albo innego
rozwiązania, które pomoże ci trzymać się ustalonych zasad tworzenia wcięć.
<a name="comments"></a>
## 3. Komentarze
Dokładne dokumentowanie kodu jest niezwykle istotne. Poświęć czas na opisanie
komponentów, ich działania i ograniczeń oraz sposobu ich tworzenia. Nie pozwól,
żeby inni członkowie zespołu musieli domyślać się znaczenia kodu.
Styl tworzenia komentarzy powinien być prosty i spójny w obrębie całego
projektu.
* Umieszczaj komentarze w nowej linii, nad elementem, który opisują.
* Unikaj tworzenia komentarzy na końcu linii.
* Utrzymuj sensowne maksimum długości linii, np. 80 znaków.
* Używaj komentarzy do dzielenia kodu CSS na osobne sekcje.
* Komentuj, używając standardowych zdań i wcięć akapitów.
Wskazówka: skonfiguruj swój edytor tak, byś mógł stosować skróty klawiszowe do
wstawiania komentarzy w ustalonej wcześniej postaci.
#### Przykład:
```css
/* ==========================================================================
Blok komentarzy sekcji
========================================================================== */
/* Blok komentarzy podsekcji
========================================================================== */
/**
* Krótki opis z zastosowaniem formatowania w stylu Doxygen
*
* Długi opis - pierwsze zdanie rozpoczyna się tutaj i biegnie jeszcze przez
* chwilę, zajmując cały wiersz, aby wreszcie zakończyć się konkluzją w tym
* miejscu, u dołu akapitu.
*
* Dłuższy opis jest najlepszym miejscem do umieszczenia szczegółowych
* objaśnień i dokumentacji. Może zawierać przykładowy kod HTML, adresy
* internetowe oraz inne przydatne informacje.
*
* @tag To jest znacznik o nazwie 'tag'
*
* @todo To jest opis todo, wskazujący istotne zadanie, które należy wykonać
* później. Zawija się po około 80 znakach a kolejne linie są wcięte za
* pomocą 2 spacji.
*/
/* Podstawowy komentarz */
```
<a name="format"></a>
## 4. Format
Wybrany format kodu musi gwarantować, że kod ten będzie łatwy do przeczytania i
skomentowania, co w efekcie zminimalizuje szanse przypadkowego popełnienia
błędu. W ten sposób także tworzenie przejrzystych zestawień zmian w plikach i
wskazywanie osób odpowiedzialnych za określone poprawki stanie się znacznie
łatwiejszym zadaniem.
* W deklaracjach z wieloma selektorami używaj jednego selektora w linii.
* Wstawiaj jedną spację przed nawiasem otwierającym zestaw reguł.
* W bloku reguł umieszczaj jedną deklarację w wierszu.
* Stosuj jeden poziom wcięcia dla każdej deklaracji.
* Wstawiaj jedną spację po dwukropku w deklaracji.
* Używaj wartości pisanych małymi literami i skrótów, np. `#aaa`.
* Stosuj pojedyncze i podwójne cudzysłowy w sposób spójny. Preferuj jednak
podwójne, jak na przykład `content: ""`.
* Wyodrędbniaj cudzysłowami wartości atrybutów w selektorach, na przykład
`input[type="checkbox"]`.
* _Tam gdzie to możliwe_ unikaj podawania jednostek dla wartości zerowych, na
przykład `margin: 0`.
* W oddzielonych przecinkami właściwościach wstawiaj spację po każdym
przecinku.
* Pamiętaj o średniku na końcu ostatniej deklaracji w bloku.
* Nawias zamykający zestaw reguł umieszczaj w tej samej kolumnie (z tym samym
wcięciem), co otwierający.
* Bloki deklaracji oddzielaj pustą linią.
```css
.selektor-1,
.selektor-2,
.selektor-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));
}
```
#### Kolejność deklaracji
Deklaracje powinny być uporządkowane zgodnie z jedną, przyjętą na wstępie
regułą. Preferowanym przeze mnie sposobem jest umieszczanie na początku
właściwości określających strukturę elementu - czyli np. jego pozycję i
wymiary.
```css
.selektor {
/* Pozycja */
position: absolute;
z-index: 10;
top: 0;
right: 0;
bottom: 0;
left: 0;
/* Wyświetlanie i wymiary */
display: inline-block;
overflow: hidden;
box-sizing: border-box;
width: 100px;
height: 100px;
padding: 10px;
border: 10px solid #333;
margin: 10px;
/* Inne */
background: #000;
color: #fff
font-family: sans-serif;
font-size: 16px;
text-align: right;
}
```
Stosunkowo popularne jest także porządkowanie deklaracji alfabetycznie. Metoda
ta ma jednak taką wadę, że oddziela od siebie powiązane właściwości. W takim
wypadku np. definicje marginesów, odstępów, wysokości i szerokości elementu
będą rozrzucone po całym bloku.
#### Wyjątki i drobne odstępstwa
Duże fragmenty arkusza zawierające pojedyncze deklaracje można formatować nieco
inaczej, ujmując całość w jednym wierszu. W takim wypadku po nawiasie
otwierającym oraz przed zamykającym należy wstawić spację.
```css
.selektor-1 { width: 10%; }
.selektor-2 { width: 20%; }
.selektor-3 { width: 30%; }
```
Dłuższe, oddzielone przecinkami właściwości, np. zestawy gradientów albo cieni,
można rozbijać na kilka linii, by poprawić czytelność i ułatwić generowanie
przejrzystych zestawień zmian. Poniższy przykład obrazuje jedno z możliwych
rozwiązań:
```css
.selektor {
background-image:
linear-gradient(#fff, #ccc),
linear-gradient(#f3c, #4ec);
box-shadow:
1px 1px 1px #000,
2px 2px 1px 1px #ccc inset;
}
```
### Preprocesory: dodatkowe uwagi dotyczące formatu
Różne narzędzia do wstępnego przetwarzania kodu CSS mają zróżnicowane
możliwości i składnię. W związku z tym zasady postępowania należy ustalać
zawsze w odniesieniu do unikalnych właściwości danego preprocesora. Te wskazane
niżej odnoszą się do jednego z nich - Sass.
* Ogranicz zagnieżdżanie do jednego poziomu. To pozwoli ci uniknąć tworzenia
nazbyt szczegółowych selektorów.
* Unikaj stosowania dużej liczby zagnieżdżonych reguł. 20 wierszy wydaje się
być rozsądną granicą. Podziel kod na mniejsze fragmenty, gdy tylko zauważysz,
że traci na czytelności.
* Pamiętaj o umieszczaniu `@extend` w pierwszych liniach bloku deklaracji.
* Gdy to możliwe, grupuj `@include` na początku bloku deklaracji, zaraz za
`@extend`.
* Nazwy tworzonych przez siebie funkcji poprzedzaj `x-` lub innym prefiksem.
Pomoże ci to odróżnić je w trakcie pracy od domyślnych funkcji CSS i uniknąć
konfliktów z funkcjami zawartymi w innych bibliotekach.
```scss
.selektor-1 {
@extend .inna-regula;
@include clearfix();
@include box-sizing(border-box);
width: x-jednostka-siatki(1);
// pozostałe deklaracje
}
```
<a name="naming"></a>
## 5. Nazewnictwo
Wybór odpowiedniego nazewnictwa jest trudny, ale bardzo istotny. To kluczowy
element w procesie tworzenia łatwej w aktualizacji i elastycznej bazy kodu
CSS.
* Unikaj _zbyt częstego_ wykorzystywania skróconych nazw klas. Nie komplikuj
kodu ponad potrzebę.
* Używaj jasnych, kojarzących się, dobrze przemyślanych nazw klas.
* Wybierz zrozumiały i spójny wzorzec tworzenia nazw, który będzie zrozumiały
zarówno w trakcie lektury kodu HTML, jak i CSS.
* Selektory dla komponentów strony powinny wykorzystywać nazwy klas - unikaj
używania nazw tagów i identyfikatorów (id).
```css
/* Przykład kodu z kiepskimi nazwami klas */
.m-prz {
overflow: auto;
}
.tk {
background: #000;
}
/* Przykład kodu z lepszymi nazwami */
.mozna-przewijac {
overflow: auto;
}
.tekst-kolumny {
background: #000;
}
```
<a name="example"></a>
## 6. Przykłady praktyczne
Propozycje zastosowania opisanych wcześniej konwencji.
```css
/* ==========================================================================
Siatka
========================================================================== */
/**
* Przykładowy kod HTML:
*
* <div class="siatka">
* <div class="komorka komorka-5"></div>
* <div class="komorka komorka-5"></div>
* </div>
*/
.siatka {
overflow: visible;
height: 100%;
/* Zapobiegaj zawijaniu tekstu w komórkach z inline-block */
white-space: nowrap;
/* Usuń spacje między komórkami */
font-size: 0;
}
.komorka {
position: relative;
display: inline-block;
overflow: hidden;
box-sizing: border-box;
width: 20%;
height: 100%;
/* Ustaw odstępy między komórkami */
padding: 0 10px;
border: 2px solid #333;
vertical-align: top;
/* Resetuj spacje */
white-space: normal;
/* Resetuj rozmiar czcionki */
font-size: 16px;
}
/* Stany komórek */
.komorka.jest-animowana {
background-color: #fffdec;
}
/* Wymiary komorek
========================================================================== */
.komorka-1 { width: 10%; }
.komorka-2 { width: 20%; }
.komorka-3 { width: 30%; }
.komorka-4 { width: 40%; }
.komorka-5 { width: 50%; }
/* Modyfikacje komorek
========================================================================== */
.komorka--szczegoly,
.komorka--istotne {
border-width: 4px;
}
```
<a name="organization"></a>
## 7. Organizacja
Odpowiednia organizacja jest istotnym elementem tworzenia każdej bazy kodu CSS.
W przypadku dużych baz to wręcz kwestia kluczowa.
* Pamiętaj o logicznym wyodrębnianiu samodzielnych fragmentów kodu.
* Używaj osobnych plików (łączonych podczas budowania kodu) aby w prosty sposób
dzielić kod na mniejsze komponenty.
* Jeśli używasz preprocesora, powtarzające się definicje kolorów, typografii
itp. przypisuj do zmiennych.
<a name="build-and-deployment"></a>
## 8. Przygotowanie i wdrożenie
W projektach powinno się zawsze wdrażać pewne ogólne zasady, według których kod
źródłowy może być analizowany, testowany, kompresowany i wersjonowany przed
wdrożeniem. Doskonałym narzędziem służącym do tego celu jest
[grunt](https://github.com/cowboy/grunt) autorstwa Bena Almana.
<a name="acknowledgements"></a>
## Podziękowania
Dziękuję wszystkim, którzy współtworzyli
[idiomatic.js](https://github.com/rwldrn/idiomatic.js). Projekt ten był dla
mnie źródłem inspiracji, cytatów i wskazówek.
================================================
FILE: translations/pt-BR/README.md
================================================
# Princípios para escrever CSS de forma consistente e idiomática
O documento a seguir descreve um sensato guia de estilo para desenvolvimento
CSS. Não pretendo ser prescritivo e não quero impor as minhas preferências de
estilo no código de outras pessoas. Entretanto, estas orientações incentivam
fortemente o uso de existentes, comuns e sensatos padrões.
Esse é um documento vivo e novas ideias são sempre bem-vindas. Por favor
contribua.
[Idiomatic CSS em Inglês (Original)](https://github.com/necolas/idiomatic-css)
## Índice
1. [Princípios gerais](#general-principles)
2. [Espaços em branco](#whitespace)
3. [Comentários](#comments)
4. [Formatação](#format)
5. [Nomeando](#naming)
6. [Exemplo prático](#example)
7. [Organização](#organization)
8. [Build e deploy](#build-and-deployment)
[Agradecimentos](#acknowledgements)
<a name="general-principles"></a>
## 1. Princípios gerais
> "Parte de ser um bom gestor de um projeto bem sucedido é perceber que
> escrever código para si mesmo é uma Má Ideia™. Se milhares de pessoas estão
> usando o seu código, então escreva-o com máxima clareza, não sob a sua
> preferência pessoal de como ser esperto com a especificação." - Idan Gazit
* Todo código em qualquer aplicação deve parecer como se tivesse sido escrito
por uma única pessoa, independentemente de quantas pessoas tenham contribuído.
* Faça cumprir rigorosamente o estilo acordado.
* Em caso de dúvida, utilizar padrões existentes e comuns.
<a name="whitespace"></a>
## 2. Espaços em branco
Apenas um estilo deve existir em todo o projeto. Seja sempre consistente na
utilização de espaços em branco. Use espaços em branco para melhorar a
legibilidade.
* _Nunca_ misture espaços e tabs para indentação.
* Escolha entre indentação suave (espaços) ou tabulação. Atenha-se à sua
escolha sem falhar. (Preferência: espaços)
* Se usar espaços, escolha o número de caracteres usados por nível de
indentação. (Preferência: 4 espaços)
Dica: configure seu editor para "mostrar invisíveis". Isso irá permitir que
você elimine espaços em branco da quebra de linha, elimine espaços em branco de
linhas vazias sem indentação e evite commits poluídos.
Dica: use um [EditorConfig](http://editorconfig.org/) arquivo (ou equivalente) para ajudar a menter a convenção básica de espaços em branco que você aceitou para sua base de código.
<a name="comments"></a>
## 3. Comentários
Código bem comentado é extremamente importante. Tire tempo para descrever
componentes, como eles funcionam, suas limitações, e o modo como são
construídos. Não deixe outros no time adivinharem o propósito de códigos
incomuns ou não óbvios.
Estilo de comentário deve ser simples e consistente dentro de uma única base de
código.
* Coloque comentários em uma nova linha acima do seu assunto.
* Evite comentários no fim da linha.
* Mantenha o comprimento da linha a um máximo sensível, por exemplo, 80
colunas.
* Faça o uso liberal de comentários para quebrar o código CSS em seções
distintas.
* Use comentários com iniciais maiúsculas e indentação de texto consistente.
Dica: configure seu editor para lhe prover com atalhos a geração do padrão de
comentários acordado.
#### exemplo com CSS:
```css
/* ==========================================================================
Bloco de comentário de seção
========================================================================== */
/* Bloco de comentário de sub-seção
========================================================================== */
/*
* Bloco de comentário de grupo
* Ideal para explicações em múltiplas linhas e documentação.
*/
/**
* Breve descrição usando o estilo de formato de comentário Doxygen
*
* A primeira frase da descrição longa começa aqui e continua
* nesta linha por um tempo finalmente concluindo aqui no final deste parágrafo.
*
* A descrição longa é ideal para explicações mais detalhadas e documentação.
* Ele pode incluir HTML exemplo, URLs, ou qualquer outra informação
* que seja considerada necessária ou útil.
*
* @tag Esta é uma tag chamada 'tag'
*
* @todo Esta é uma declaração de tarefas que descreve uma tarefa atômica para ser
* concluída numa data posterior. Ela envolve depois de 80 caracteres e as linhas a
* seguir são Recuado por dois espaços.
*/
/* Comentário básico */
```
#### exemplo com SCSS:
```scss
// ==========================================================================
// Bloco de comentário de seção
// ==========================================================================
// Bloco de comentário de sub-seção
// ==========================================================================
//
// Bloco de comentário de grupo
// Ideal para explicações em múltiplas linhas e documentação.
//
// Comentário básico
```
<a name="format"></a>
## 4. Formatação
O formato de código escolhido deve garantir que o código seja: fácil de ler;
fácil de comentar claramente; minimize a chance de introduzir erros
acidentalmente; e resulte em úteis visualizações de diferença.
* Um seletor discreto por linha em um conjunto de regras com multi-seletores.
* Um único espaço antes da abertura das chaves em um conjunto de regras.
* Uma única declaração por linha em um bloco de declarativo.
* Um nível de indentação para cada declaração.
* Um único espaço depois dos dois pontos de uma declaração.
* Use valores minúsculos e abreviações hexadecimais, por exemplo, `#aaa`.
* Use aspas simples ou duplas de forma consistente. Preferência é por aspas duplas,
por exemplo, `conteúdo:" "`.
* Citação valores de atributos em seletores, por exemplo, `input [type="checkbox"]`.
* _Onde for permitido_, evitar especificar unidades para zero valores, por exemplo, `margin: 0`.
* Inclua um espaço após cada vírgula em propriedades separadas por vírgula ou valores de funções.
* Sempre inclua um ponto-e-vírgula no fim da última declaração em um bloco
declarativo.
* Coloque o fechamento das chaves na mesma coluna que o primeiro caracter do
conjunto de regras.
* Separe cada conjunto de regras por uma linha em branco.
```css
.selector-1,
.selector-2,
.selector-3 {
-webkit-box-sizing: border-box;
-moz-box-sizing: border-box;
box-sizing: border-box;
display: block;
color: #333;
background: #fff;
}
```
#### Ordem de declaração
Declarações devem ser ordenadas segundo um único princípio. Minha preferência é
por propriedades relacionadas para serem agrupadas e por propriedades
estruturalmente importantes (por exemplo, posicionamento e box-model) para
serem declaradas antes de propriedades tipográficas, fundo ou cor.
```css
.selector {
/* Posicionamento */
position: absolute;
z-index: 10;
top: 0;
right: 0;
bottom: 0;
left: 0;
/* Display & Modelo de Caixa */
display: inline-block;
overflow: hidden;
box-sizing: border-box;
width: 100px;
height: 100px;
padding: 10px;
border: 10px solid #333;
margin: 10px;
/* Outros */
background: #000;
color: #fff;
font-family: sans-serif;
font-size: 16px;
text-align: right;
}
```
Ordenação alfabética também é popular, mas a desvantagem é que ela separa as
propriedades relacionadas. Por exemplo, deslocamentos de posição não são mais
agrupados e propriedades do box-model podem acabar propagando ao longo de um
bloco de declaração.
#### Exceções e ligeiros desvios
Grandes blocos de declarações individuais podem atuar de forma diferente,
através da formatação de linha única. Nesse caso, um espaço deve ser
considerado depois da abertura das chaves e antes do fechamento das chaves.
```css
.selector-1 { width: 10%; }
.selector-2 { width: 20%; }
.selector-3 { width: 30%; }
```
Longos valores de propriedades separados por vírgula - como coleções de
degradês ou sombras - podem ser organizados em várias linhas em um esforço para
melhorar a legibilidade e produz visualizações de diferença mais úteis. Existem
vários formatos que poderiam ser usados; um exemplo é mostrado abaixo.
```css
.selector {
background-image:
linear-gradient(#fff, #ccc),
linear-gradient(#f3c, #4ec);
box-shadow:
1px 1px 1px #000,
2px 2px 1px 1px #ccc inset;
}
```
#### Miscelânea
* Use valores hexadecimais em letras minúsculas, por exemplo: `#aaa`.
* Use aspas simples ou duplas de forma consistente. Preferência por aspas
duplas, por exemplo: `content: ""`.
* Sempre coloque aspas em valores de atributos nos seletores, por exemplo:
`input[type="checkbox"]`.
* _Onde permitido_, evite especificar unidades para valores-zero, por exemplo:
`margin: 0`.
### Pré-processadores: considerações de formatação adicionais
Diferentes pré-processadores de CSS possuem diferentes características,
funcionalidades e sintaxe. Suas convenções devem ser extendidas para acomodar
as particularidades de qualquer pré-processador em uso. As seguintes diretrizes
são em referência ao Sass.
* Limite o aninhamento a 1 nível de profundidade. Reavalie qualquer aninhamento
que tenha mais de 2 níveis de profundidade. Isso impede que existam seletores
CSS muito específicos.
* Evite um grande número de regras aninhadas. Quebre-os para quando a
legibilidade começar a ser afetada. Preferência por evitar aninhamentos que
se espalhem por mais de 20 linhas.
* Sempre coloque as declarações `@extend` nas primeiras linhas de um bloco
declarativo.
* Quando possível, agrupe declarações `@include` no topo de blocos
declarativos, depois de qualquer declaração `@extend`.
* Considere funções customizadas para prefixos com `x-` ou qualquer namespace.
Isso ajuda a evitar qualquer potencial confusão na sua função com a função de
CSS nativo ou de colidir com funções de bibliotecas.
```scss
.selector-1 {
@extend .other-rule;
@include clearfix();
@include box-sizing(border-box);
width: x-grid-unit(1);
// other declarations
}
```
<a name="naming"></a>
## 5. Nomeando
Você não é um compilador/compressor de código humano, então não tente ser.
Use nomes claros e previdentes para classes HTML. Escolha um padrão de nomes
compreensível e consistente que faça sentido para arquivos HTML e arquivos
CSS.
```css
/* Exemplo de código com nomes ruins */
.s-scr {
overflow: auto;
}
.cb {
background: #000;
}
/* Exemplo de código com bons nomes */
.is-scrollable {
overflow: auto;
}
.column-body {
background: #000;
}
```
<a name="example"></a>
## 6. Exemplo prático
Um exemplo de várias convenções.
```css
/* ==========================================================================
Grid layout
========================================================================== */
/*
* Layout da coluna com scroll horizontal.
*
* Isso cria uma única linha de altura completa, não-envolvendo colunas que podem
* ser navegadas na horizontal dentro de seu pai.
*
* Exemplo de HTML:
*
* <div class="grid">
* <div class="cell cell-5"></div>
* <div class="cell cell-5"></div>
* </div>
*/
/**
* Grid container
* Deve conter apenas filhos de `.cell`
*/
.grid {
overflow: visible;
height: 100%;
/* Prevent inline-block cells wrapping */
white-space: nowrap;
/* Remove inter-cell whitespace */
font-size: 0;
}
/**
* Grid cells
* Largura não-explícita por padrão. Extenda com classes `.cell-n`.
*/
.cell {
box-sizing: border-box;
position: relative;
overflow: hidden;
width: 20%;
height: 100%;
/* Set the inter-cell spacing */
padding: 0 10px;
border: 2px solid #333;
vertical-align: top;
/* Reset white-space */
white-space: normal;
/* Reset font-size */
font-size: 16px;
}
/* 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="organization"></a>
## 7. Organização
Organização de código é uma importante parte de qualquer base de código CSS, e
crucial para grandes bases de código.
* Separar logicamente distintas partes do código.
* Usar arquivos separados (concatenados por um processo de build) para ajudar a
dividir código para componentes distintos.
* Se estiver usando um pré-processador, abstrair partes comuns de código em
variáveis para cor, tipografia, etc.
<a name="build-and-deployment"></a>
## 8. Build e deploy
Os projetos devem sempre tentar incluir alguns meios genéricos pelos quais sua
fonte possa ser avaliada, testada, comprimida e versionada em preparação para
uso em produção. Para essa tarefa, o [grunt](https://github.com/cowboy/grunt)
por Ben Alman é uma excelente ferramenta.
<a name="acknowledgements"></a>
## Agradecimentos
Obrigado a todos que contribuiram para
[idiomatic.js](https://github.com/rwldrn/idiomatic.js). Foi uma fonte de
inspiração, citações e diretrizes.
================================================
FILE: translations/ru-RU/README.md
================================================
# Принципы написания однородного CSS-кода
Этот документ представляет собой общие рекомендации по стилю написания CSS. Он
не был задуман как набор жёстких правил, и мне бы не хотелось навязывать
собственные предпочтения другим людям. Тем не менее, данное руководство
призывает к использованию общепринятых и устоявшихся подходов к написанию
кода.
Этот документ не закончен, и новые идеи всегда приветствуются. Пожалуйста,
внесите свой вклад.
[«Принципы написания однородного CSS» на английском языке
(Original)](https://github.com/necolas/idiomatic-css)
## Содержание
1. [Общие принципы](#general-principles)
2. [Отступы](#whitespace)
3. [Комментарии](#comments)
4. [Форматирование](#format)
5. [Именование](#naming)
6. [Практический пример](#example)
7. [Организация кода](#organization)
8. [Сборка и развёртывание](#build-and-deployment)
[Благодарности](#acknowledgements)
<a name="general-principles"></a>
## 1. Общие принципы
> «Вы сослужите проекту хорошую службу, если будете осознавать, что написание
> кода только для себя — Плохая Идея™. Если тысячи людей используют ваш код, то
> пишите его максимально ясным и не делайте что-то только потому, что
> спецификация языка допускает это». — Idan Gazit
* Весь код в любом проекте должен выглядеть так, будто его создал один человек,
вне зависимости от того, сколько людей на самом деле принимали участие.
* Строго соблюдайте соглашения.
* В сомнительных случаях используйте общепринятый подход.
<a name="whitespace"></a>
## 2. Отступы
Для всего проекта должен применяться единый стиль отступов. Всегда будьте
последовательны в использовании отступов и применяйте их для повышения
читабельности кода.
* _Никогда_ не смешивайте пробелы и табуляцию.
* Между табуляцией и мягкими отступами (пробелы вместо табуляции) выберите
что-то одно. Придерживайтесь своего выбора, не делая исключений.
(Предпочтение: пробелы)
* Если вы используете пробелы, определитесь с количеством символов,
соответствующим одному уровню отступа. (Предпочтение: 4 пробела)
Совет: настройте редактор кода так, чтобы он отображал невидимые символы. Это
позволит избегать случайных пробелов в конце строк или в пустых строках и легче
отслеживать изменения в коде.
<a name="comments"></a>
## 3. Комментарии
Хорошо откомментированный код очень важен. Потратьте время на то, чтобы описать
компоненты, особенности их работы, ограничения и то, как они были созданы. Не
заставляйте других членов команды гадать над назначением неочевидного кода.
Стиль комментариев должен быть простым и однородным для всего проекта.
* Помещайте комментарий на строке перед комментируемым фрагментом кода.
* Избегайте добавления комментариев в конец строки.
* Установите обоснованную максимальную длину строки, например, 80 символов.
* Свободно используйте комментарии для оформления разделов внутри CSS-файла.
* Начинайте предложения с заглавной буквы, в конце ставьте точку, а также
используйте однородные отступы.
Совет: настройте в редакторе кода горячие клавиши для быстрого набора шаблонов
комментирования.
#### Пример для CSS:
```css
/* ==========================================================================
Блок комментариев для раздела
========================================================================== */
/* Блок комментариев для подраздела
========================================================================== */
/*
* Блок комментариев для группы правил.
* Хорошо подходит для подробных пояснений и документации.
*/
/* Обычный комментарий */
```
#### Пример для SCSS:
```scss
// ==========================================================================
// Блок комментариев для раздела
// ==========================================================================
// Блок комментариев для подраздела
// ==========================================================================
//
// Блок комментариев для группы правил.
// Хорошо подходит для подробных пояснений и документации.
//
// Обычный комментарий
```
<a name="format"></a>
## 4. Форматирование
Выбранный формат записи кода должен гарантировать, что код легко читается; что
его легко комментировать; должен минимизировать шанс случайного внесения
ошибки; и в результате обеспечивать удобство чтения сообщений внутри системы
управления версиями.
1. При создании правила для нескольких селекторов помещайте каждый селектор на
отдельной строке.
2. Перед открывающей скобкой ставьте один пробел.
3. Внутри блока объявлений помещайте каждое объявление на отдельной строке.
4. Добавляйте один уровень отступов перед каждым объявлением.
5. Ставьте пробел после двоеточия внутри объявления.
6. Всегда ставьте точку с запятой после последнего объявления в блоке.
7. Ставьте закрывающую скобку на одной вертикальной линии с первым символом в
селекторе.
8. Разделяйте правила пустой строкой.
```css
.selector-1,
.selector-2,
.selector-3 {
-webkit-box-sizing: border-box;
-moz-box-sizing: border-box;
box-sizing: border-box;
display: block;
color: #333;
background: #fff;
}
```
#### Порядок объявлений
Объявления должны быть упорядочены по единому принципу. Я предпочитаю
объединять их по смыслу и помещать структурно важные свойства (например, те,
что отвечают за позиционирование и блочную модель) перед свойствами, связанными
с типографикой, фоном и цветом.
```css
.selector {
position: relative;
display: block;
width: 50%;
height: 100px;
padding: 10px;
border: 0;
margin: 10px;
color: #fff
background: #000;
}
```
Упорядочение по алфавиту тоже популярно, но его минус в том, что связанные по
смыслу свойства оказываются разделены. К примеру, свойства, связанные с
отступами, могут встречаться как в начале, так и в конце одного и того же
блока определений.
#### Исключения и небольшие отклонения
К большим группам правил, состоящих из одного свойства, может применяться
запись в одну строку. В таком случае следует ставить пробел после открывающей и
перед закрывающей скобками.
```css
.selector-1 { width: 10%; }
.selector-2 { width: 20%; }
.selector-3 { width: 30%; }
```
Длинные значения свойств, разделяемые запятыми — как, например, набор
градиентов или теней — могут быть помещены на отдельной строке каждое, чтобы
повысить читабельность кода и сообщений в системе управления версиями. Формат
записи может слегка различаться, один из вариантов приведён ниже.
```css
.selector {
box-shadow:
1px 1px 1px #000,
2px 2px 1px 1px #ccc inset;
background-image:
linear-gradient(#fff, #ccc),
linear-gradient(#f3c, #4ec);
}
```
#### Прочее
* Пишите шестнадцатеричные значения в нижнем регистре, например, `#aaa`.
* Последовательно используйте либо одинарные, либо двойные кавычки. Я
предпочитаю двойные, к примеру, `content: ""`.
* Всегда берите в кавычки значения атрибутов внутри селектора, например,
`input[type="checkbox"]`.
* _Везде, где возможно_, опускайте единицы измерения при нулевом значении,
например, `margin: 0`.
### Препроцессоры: дополнительные соглашения
Разные препроцессоры CSS имеют разный набор возможностей и различный
синтаксис. Ваши соглашения должны быть дополнены, чтобы отражать особенности
использования конкретного препроцессора. Следующий набор правил относится
к Sass.
* Ограничивайте вложенность одним уровнем. Пересмотрите все правила, в которых
больше двух уровней вложенности. Это позволит избегать чрезмерной
специфичности правил.
* Избегайте большого числа вложенных правил. Оформляйте их отдельно,
когда их становится трудно читать. Предпочтительно ограничивать длину
вложенных правил 20 строками.
* Всегда помещайте оператор `@extend` в первой строке блока объявлений.
* По возможности группируйте операторы `@include` в начале блока объявлений,
сразу после `@extend`.
* Подумайте над добавлением префикса вида `x-` перед своими функциями. Это
позволит избежать возможной путаницы между вашими функциями и стандартными
функциями CSS, а также функциями из сторонних библиотек.
```scss
.selector-1 {
@extend .other-rule;
@include clearfix();
@include box-sizing(border-box);
width: x-grid-unit(1);
// прочие объявления
}
```
<a name="naming"></a>
## 5. Именование
Вы не компилятор и не компрессор кода, поэтому ведите себя соответственно.
Используйте понятные и осмысленные имена для классов в HTML. Выберите ясный и
последовательный шаблон именования, который будет удобен как для HTML, так и
для CSS.
```css
/* Пример кода с плохими именами */
.s-scr {
overflow: auto;
}
.cb {
background: #000;
}
/* Пример лучшего подхода к именованию */
.is-scrollable {
overflow: auto;
}
.column-body {
background: #000;
}
```
<a name="example"></a>
## 6. Практический пример
Пример использования нескольких соглашений.
```css
/* ==========================================================================
Макет сетки
========================================================================== */
/*
* HTML для примера:
*
* <div class="grid">
* <div class="cell cell-5"></div>
* <div class="cell cell-5"></div>
* </div>
*/
.grid {
overflow: visible;
height: 100%;
/* Предотвращаем перенос строчных блоков на новую строку */
white-space: nowrap;
/* Убираем пробелы между ячейками сетки */
font-size: 0;
}
.cell {
box-sizing: border-box;
position: relative;
overflow: hidden;
width: 20%;
height: 100%;
/* Задаём отступы внутри ячеек */
padding: 0 10px;
border: 2px solid #333;
vertical-align: top;
/* Восстанавливаем поведение по умолчанию */
white-space: normal;
/* Восстанавливаем размер шрифта */
font-size: 16px;
}
/* Состояния ячеек */
.cell.is-animating {
background-color: #fffdec;
}
/* Размеры ячеек
========================================================================== */
.cell-1 { width: 10%; }
.cell-2 { width: 20%; }
.cell-3 { width: 30%; }
.cell-4 { width: 40%; }
.cell-5 { width: 50%; }
/* Модификаторы для ячеек
========================================================================== */
.cell--detail,
.cell--important {
border-width: 4px;
}
```
<a name="organization"></a>
## 7. Организация кода
Организация кода — важная часть любого проекта на CSS и ключевой элемент в
большом проекте.
* Логически отделяйте различные части кода.
* Используйте отдельные файлы (объединяемые на этапе сборки), чтобы разделить
код обособленных компонентов.
* При использовании препроцессора оформляйте часто используемый код в
переменные, например, для типографики, цветов и т.д.
<a name="build-and-deployment"></a>
## 8. Сборка и развёртывание
В любом проекте по возможности должны использоваться средства для проверки,
тестирования, сжатия и управления версиями кода при подготовке к развёртыванию.
Хороший инструмент для этих задач —
[grunt](https://github.com/cowboy/grunt), написанный Ben Alman.
<a name="acknowledgements"></a>
## Благодарности
Спасибо всем, кто внёс вклад в проект
[idiomatic.js](https://github.com/rwldrn/idiomatic.js). Это мой источник
вдохновения, цитат и общих рекомендаций.
================================================
FILE: translations/sr-SR/README.md
================================================
# Principi pisanja konzistentnog, idiomatskog CSS-a
Sledeći dokument ocrtava razumne stilove za CSS razvoj. Nije namenjen da bude
perskriptivan i ja ne želim da namećem svoje preferencije stilova na kod drugih
ljudi. Međutim, ove smernice snažno ohrabruju korišćenje postojećih,
zajedničkih, razumnih šema.
Ovo je "živi" dokument i nove ideje su uvek dobrodošle. Molimo Vas da
doprinesete.
[Idiomatski CSS na Engleskom (Original)](https://github.com/necolas/idiomatic-css)
## Sadržaj
1. [Generalni principi](#general-principles)
2. [Znaci za razmake](#whitespace)
3. [Komentari](#comments)
4. [Formatiranje](#format)
5. [Imenovanje](#naming)
6. [Praktični primeri](#example)
7. [Organizovanje](#organization)
8. [Izrada i razvoj](#build-and-deployment)
[Priznanja](#acknowledgements)
<a name="general-principles"></a>
## 1. Generalni principi
> "Deo zaduženja dobrog stjuarda za uspešan projekat je shvatanje da pisanje
> koda za samog sebe je loša ideja™. Ako hiljade ljudi koristi tvoj kod, onda
> piši tvoj kod sa maksimalnom jasnoćom, a ne sa svojim personalnim
> preferencijama o tome kako da se napraviš pametan u okviru specifikacije." -
> Idan Gazit
* Sav kod u bilo kom projektu bi trebao da izgleda kao da ga je pisala jedna
osoba, bez obzira koliko je ljudi doprinelo razvoju projekta.
* Striktno primenjujte dogovoreni stil.
* Ako ste u sumnji, koristite postojeće, zajedničke šablone.
<a name="whitespace"></a>
## 2. Znaci za razmake
Samo jedan stil bi trebao da postoji u celom vašem projektu. Uvek budite
konzistentni u upotrebi razmaka. Koristite razmake da poboljšate čitljivost.
* _Nikada_ nemojte mešati space karakter i tab za indentaciju.
* Izaberite između mekih indentacija(space karakteri) i pravih tabova. Držite se
vašeg izbora bez obzira na sve. (Preferencija: space karakteri)
* Ako koristite space karaktere, izaberite broj karaktera za indentacioni nivo.
(Preferencija: 4 space karaktera)
Savet: konfigurišite vaš editor da prikazuje "nevidljive karaktere". Ovo će vam
omogućiti da eliminišete prazne karaktere na kraju linije, da eliminišete space
karaktere praznim linijama i da izbegnete "zagađivanje" komitova.
<a name="comments"></a>
## 3. Komentari
Dobro komentarisan kod je ekstremno bitan. Uzmite vremena da opišete komponente,
kako rade, njihove limite, i način na koji su konstruisani. Nemojte ostavljati
drugim članovima tima da nagađaju svrhu neuobičajenih i ne očiglednih delova
koda.
Stil komentara treba da bude jednostavan i konzistentan u celom projektu.
* Postavljajte komentare na novu liniju iznad dela koda koji hoćete da
iskomentarišete.
* Izbegavajte komentare na kraju linije koda.
* Držite dužinu linije na razumnom maksimumu, npr 80 kolona.
* Slobodno koristite komentare da "razbijete" CSS kod na diskretne sekcije.
* Koristite komentare dužine jedne rečenice i konzistentno indentovanje teksta.
Savet: konfigurišite vaš editor da vam omogući prečice za ispisivanje unapred
dogovorenog šablona za komentare.
#### CSS primer:
```css
/* ==========================================================================
Blok komentar za odeljak
========================================================================== */
/* Blok komentar za pododeljak
========================================================================== */
/*
* Blok komentar za grupu.
* Idealan za objašnjavanja koja se protežu u više redova i dokumentaciju.
*/
/* Običan komentar */
```
#### SCSS primer:
```scss
// ==========================================================================
// Blok komentar za odeljak
// ==========================================================================
// Blok komentar za pododeljak
// ==========================================================================
//
// Blok komentar za grupu.
// Idealan za objašnjavanja koja se protežu u više redova i dokumentaciju.
//
// Običan komentar
```
<a name="format"></a>
## 4. Formatiranje
Izabrani tip formatiranja koda mora da obezbedi da je kod: lak za čitanje; lak
da se jasno komentariše; minimizuje šanse da se slučajno uvedu greške; i
rezultira korisnim `diff` i `blame` komandama u vašem sistemu za kontrolu
verzija.
1. Jedan selektor na jednu liniju kada koristite više selektora u jednom setu
pravila.
2. Jedan space karakter pre otvarajuće zagrade za set pravila.
3. Jedna deklaracija na jednu liniju unutar seta pravila.
4. Jedan nivo indentacije za svaku deklaraciju.
5. Jedan space karakter nakon dve tačke u deklaraciju.
6. Uvek stavite tačku-zarez na kraju poslednje deklaracije u deklarativnom
bloku.
7. Stavite zatvarajuću zagradu seta pravila u istu kolonu gde se nalazi prvi
karakter selektora tog seta pravila.
8. Razdvojite svaki set pravila praznom linijom.
```css
.selektor-1,
.selektor-2,
.selektor-3 {
-webkit-box-sizing: border-box;
-moz-box-sizing: border-box;
box-sizing: border-box;
display: block;
color: #333;
background: #fff;
}
```
#### Redosled deklaracija
Deklaracije bi trebale biti poređane u skladu sa jednim principom. Moje
preferencije su da slična svojstva budu grupisana zajedno i da strukturno bitna
svojstva (npr pozicioniranje i box-model) budu deklarisana pre svojstava
za tipografiju, pozadine i boje.
```css
.selektor {
position: relative;
display: block;
width: 50%;
height: 100px;
padding: 10px;
border: 0;
margin: 10px;
color: #fff
background: #000;
}
```
Alfabetni redosled je isto popularan, ali mana mu je da razdvaja slična
svojstva. Na primer, svojstva za pomeranja pozicija više nisu grupisana zajedno
i box-model svojstva mogu da završe raširena kroz ceo deklarativni blok.
#### Izuzeci i mala odstupanja
Veliki blokovi gde se nalaze deklaracije u samo jednoj liniji mogu koristiti
malo izmenjen format na jednoj liniji. U ovom slučaju space karakter se
postavlja posle otvarajuće i pre zatvarajuće zagrade.
```css
.selektor-1 { width: 10%; }
.selektor-2 { width: 20%; }
.selektor-3 { width: 30%; }
```
Dugačka svojstva koja su razdvojena zarezom, kao što su na primer kolekcija
gradijenta ili senka, mogu biti raspoređena preko više linija sve sa ciljem
poboljšanja čitljivosti, a takođe da može da proizvede bolji `diff`. Postoje
razni formati koji bi mogli biti korišćeni, jedan primer je prikazan ispod.
```css
.selector {
box-shadow:
1px 1px 1px #000,
2px 2px 1px 1px #ccc inset;
background-image:
linear-gradient(#fff, #ccc),
linear-gradient(#f3c, #4ec);
}
```
#### Razno
* Koristite heksadecimalne vrednosti sa malim slovim, npr `#aaa`.
* Koristite jedan ili dupli apostrof konzistentno. Preferencija je da se
koriste dupli apostrofi, npr `content: ""`.
* Vrednosti atributa u selektorima uvek stavljajte između apostrofa, npr
`input[type="checkbox"]`.
* _Gde je moguće_ izbegavajte specifiranje jedinica za nula vrednosti, npr
`margin: 0`.
### Preprocesori: dodatna razmatranja za formatiranje
Različiti CSS preprocesori imaju drugačije karakteristike, funkcionalnosti i
sintaksu. Vaše konvencije bi trebale biti proširene da prime specifičnosti
preprocesora u upotrebi. Sledeće smernice su napomene za Sass.
* Limitirajte ugnežđenja na 1 nivo dubine. Preispitajte sva gneždenja koja su
dublja od 2 nivoa. Ovo sprečava previše specifične CSS selektore.
* Izbegavajte preveliki boj ugneždenih pravila. Razbijte ih na manje delove
kada to počne da utiče na čitljivost. Preferencije su da izbegavate gnežđenja
koja se rasprostiru na više od 20 linija.
* Uvek postavite `@extend` izjave na prvu liniju deklarativnog bloka.
* Gde je moguće, grupišite `@include` izjave na vrhu deklarativnog bloka, nakon
svih `@extend` izjava.
* Razmotrite upotrebu prefiksa kod custom funkcija sa `x-` ili drugim
namespace-om. Ovo pomaže da se izbegne bilo kakav potencijal da se pobrkaju
vaše funkcije sa nativnim CSS funkcijama, ili da dođe do "sukoba" sa
funkcijama iz drugih biblioteka.
```scss
.selektor-1 {
@extend .other-rule;
@include clearfix();
@include box-sizing(border-box);
width: x-grid-unit(1);
// druge deklaracije
}
```
<a name="naming"></a>
## 5. Imenovanje
Ti nisi ljudski kompajler/kompresor za kod, tako da ne pokušavaj da budeš to.
Koristi jasna i pažljivo izabrana imena za HTML klase. Izaberi razumljive i
konzistentne šeme za imenovanje koje imaju smisla za korišćenje i u HTML
fajlovima i u CSS fajlovima.
```css
/* Primer koda sa lošim imenovanjem */
.s-scr {
overflow: auto;
}
.cb {
background: #000;
}
/* Primer koda sa boljim imenovanjem */
.is-scrollable {
overflow: auto;
}
.column-body {
background: #000;
}
```
<a name="practical-example"></a>
## 6. Praktični primeri
Primeri raznih konvencija.
```css
/* ==========================================================================
Grid layout
========================================================================== */
/*
* HTML example:
*
* <div class="grid">
* <div class="cell cell-5"></div>
* <div class="cell cell-5"></div>
* </div>
*/
.grid {
overflow: visible;
height: 100%;
/* Prevent inline-block cells wrapping */
white-space: nowrap;
/* Remove inter-cell whitespace */
font-size: 0;
}
.cell {
box-sizing: border-box;
position: relative;
overflow: hidden;
width: 20%;
height: 100%;
/* Set the inter-cell spacing */
padding: 0 10px;
border: 2px solid #333;
vertical-align: top;
/* Reset white-space */
white-space: normal;
/* Reset font-size */
font-size: 16px;
}
/* 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="organization"></a>
## 7. Organizacija
Organizacija koda je važan deo za svaku bazu CSS koda i krucijalan za velike
baze koda.
* Logična separacija posebnih delova koda.
* Koristite odvojene fajlove(spojene u delu izgradnje za produkciju) da vam
pomogne da razbijete kod u više posebnih komponenti.
* Ako koristite preprocesor, abstraktujte uobičajene delove koda u promenljive,
npr boje, tipografiju, itd.
<a name="build-and-deployment"></a>
## 8. Izgradnja i razvoj
Projekti bi uvek trebalo da uključe neki generički način da se izvorni kod
"lintuje", testira i kompresuje u pripremi za upotrebu u produkciji. Za ovaj
zadatak, [grunt](https://github.com/cowboy/grunt) od strane Ben Alman-a je
odlična alatka.
## Priznanja
Hvala svima koji su doprineli
[idiomatic.js](https://github.com/rwldrn/idiomatic.js) projektu. Taj projekat
je bio izvor inspiracije, citata i smernica.
================================================
FILE: translations/tr-TR/README.md
================================================
# Tutarlı, İdiomatic CSS yazma prensipleri
Aşağıdaki döküman CSS geliştirme konusunda makul bir stil rehberini içerir.
Kuralcı olması ve düşünülmedi ve kendi stil seçimlerini diğer kişilerin koduna
empose etmek istemiyorum. Ama bu yönergeler varolan yaygın ve mantıklı
kalıpların kullanımını teşvik etmektedir.
Bu yaşayan bir dökümandır ve yeni fikirler daima hoş karşılanacak. Lütfen
katkıda bulunun.
[İngilizce İdiomatik CSS (Orijinal)](https://github.com/necolas/idiomatic-css)
## İçindekiler
1. [Genel Prensipler](#general-principles)
2. [Beyaz Alanlar](#whitespace)
3. [Açıklamalar](#comments)
4. [Format](#format)
5. [İsimlendirme](#naming)
6. [Uygulanabilir Örnek](#example)
7. [Organizasyon](#organization)
8. [Yapı ve Dağıtma](#build-and-deployment)
[Acknowledgements](#acknowledgements)
<a name="general-principles"></a>
## 1. Genel Prensipler
> "Başarılı bir projenin iyi bir temsilci olmanın bir bölümü kendin için kod
> yazmanın kötü bir fikir olduğunun farkına varmaktır. Eğer binlerce insan
> senin kodunun kullanıyorlarsa, o zaman kodunu, şartnameler dahilinde nasıl
> akıllılık yapacağın kişisel seçimlere göre değil maksimum açıklık için yaz."
> - Idan Gazit
* Herhangi bir kod tababındaki tüm kod, kaç kişi katkıda bulunumuş olursa olsun
sanki tek bir kişi tarafından yazılmış gibi görünmelidir.
* Strictly enforce the agreed upon style.
* Karar verilen stili katı bir şekilde uygula.
* Eğer şüphen varsa yaygın olarak kullanılan yönergeleri uygula.
<a name="whitespace"></a>
## 2. Beyaz Alanlar
Projenin tüm kaynağında sadece tek bir stil hüküm sürmelidir. Beyaz alan
kullanımında her zaman tutarlı ol. Beyaz alanları okunabilirliği artırmak için
kullan.
* _Asla_ girintiler için boşluk ve tabları karıştırma.
* Yumuşak girintiler (boşluklar) veya gerçek tablar arasında bir seçim yap.
Seçimine sadık kal. (Tercih: boşluklar)
* Eğer boşluk kullanıyorsan girinti bölümü için kullanılan karakter saysını
seç. (Tercih: 4 boşluk)
İpucu: Editörünü "görünmezleri göster" şeklinde ayarla. Bu, satır sonu
boşluklarının ve kasıtsız boş satırların önüne geçmeni ve "commit"lerin
kirlenmemesini sağlayacaktır.
<a name="comments"></a>
## 3. Açıklamalar
İyi açıklanmış kod son derece önemlidir. Bileşenleri tanımlamak, nasıl
çalıştıklarını, sınırlamalarını ve nasıl yapıldıklarını açıklamakk için zaman
ayır. Takımdaki diğer kişileri yaygın veya açık olmayan kodu tahmin etmek
zorunda bırakma.
Açıklama stili basit ve tek bir kod tabanı içinde tutarlı olmalıdır.
* Açıklamaları iligili öznelerinin üzerinde yeni satıra koy.
* Satır sonu açıklamalarından kaçın.
* Satır uzunluğunu makul bir uzunlukta tut. Ör: 80 sütun.
* CSS kodu farklı aralıklarda kısımlara bölmek için açıklamaları özgürce
kullan.
* Cümle yapısında açıklamalar yap ve tutarlı girintileme kullan.
İpucu: Editörünü karar vediğin açıklama bloklarının çıktısını verecek şekilde
ayarla.
#### CSS örneği:
```css
/* ==========================================================================
Kısım açıklama bloğu
========================================================================== */
/* Alt-kısım açıklama bloğu
========================================================================== */
/*
* Grup açıklama bloğu
* Birden fazla satır açıklamalar ve dökümantasyon için ideal.
*/
/* Basit açıklama / yorum */
```
#### SCSS örneği:
```scss
// ==========================================================================
// Kısım açıklama bloğu
// ==========================================================================
// Alt-kısım açıklama bloğu
// ==========================================================================
//
// Grup açıklama bloğu
// Birden fazla satır açıklamalar ve dökümantasyon için ideal.
//
// Basit açıklama / yorum
```
<a name="format"></a>
## 4. Format (Biçem)
Seçilen kod formatı (biçemi) kodun; kolay okunabildiğinden, kolay açıklanabilir
(yorumlamanabilir) olduğundan, kazara hataların oluşmasını minimuma
indirdiğinden ve faydalı "diff" ve hatalar ürettiğinden emin olmalıdır.
1. Çoklu seçicilerin olduğu kural setlerinde her satırda tek bir seçici.
2. Kural setinin açış parantezi önünde tek bir boşluk.
3. Her deklarasyon bloğunda her satırda tek bir deklarasyon.
4. Her bir deklarasyon için bir girinti seviyesi.
5. Deklarasyondaki iki noktadan sonra tek bir boşluk.
6. Her deklarayon bloğundaki son deklarasyondan sonra mutlaka bir noktalı
virgül kullan
7. Bir kural setinin sonundaki parantezi o kural setindeki ilk karakter ile
aynı sütuna koy.
8. Her kural setini boş bir satır ile ayır.
```css
.selector-1,
.selector-2,
.selector-3 {
-webkit-box-sizing: border-box;
-moz-box-sizing: border-box;
box-sizing: border-box;
display: block;
color: #333;
background: #fff;
}
```
#### Deklarasyon sırası
Deklarasyonlar tek bir prensibe göre sıralandırılmalıdırlar. Benim seçimim
ilişkili özellikleri beraber gruplamak ve yapısal önemi olan özellikleri (ör:
posizyonlama ve box-model) tipografik, arka plan ve renk özelliklerinden önce
yapmak şeklinde.
```css
.selector {
position: relative;
display: block;
width: 50%;
height: 100px;
padding: 10px;
border: 0;
margin: 10px;
color: #fff
background: #000;
}
```
Alfabetik sıralama da oldukça popüler ama bunun kusuru ise ilişkili özellikleri
birbirinden ayırması. Örneğin posizyon offsetleri artık beraber gruplanmış
değil ce box-model özellikleri deklarasyon bloğu içinde yayılmış olacaklar.
#### İstisnalar ve ufak sapmalar
Tek deklarasyonlu büüyük bloklar biraz daha farklı tek-satır bir biçem
kullanabilirler. Bu açılış parantezinden sonra ve kapanış parantezinden önce
bir boşluk olmalıdır.
```css
.selector-1 { width: 10%; }
.selector-2 { width: 20%; }
.selector-3 { width: 30%; }
```
Virgülle ayrılmış uzun özellik değerleri - gradient ve gölgeler gibi -
okunabilirliği arttırmak ve daha faydalı "diff"ler yaratmak için birden fazla
satıra yayılabilirler. Bunun için kullanılabilecek çeşitli biçemler var. Bir
örnek aşağıda.
```css
.selector {
box-shadow:
1px 1px 1px #000,
2px 2px 1px 1px #ccc inset;
background-image:
linear-gradient(#fff, #ccc),
linear-gradient(#f3c, #4ec);
}
```
#### Diğer
* Hex değerlerinde küçük harf kullan, ör., `#aaa`.
* Tek veya çift tırnağı tutarlı kullanın. Tercih çift tırnaktan yana, ör.,
`content: ""`.
* Seçicilerdeki özellik değerlerini her zaman tırnak içine alın, ör.,
`input[type="checkbox"]`.
* _Mümkün olduğu durumlarda_, sıfır değerler için ünite kullanmayın, ör.,
`margin: 0`.
### Preprocessors (Önderleyiciler) : dikkate alınacak ek formatlar (biçem)
Farklı CSS önderleyicileri farklı özelliklere, işlevselliğe ve sözdizimine
(syntax) sahipler. Kurallarınız kullanılmakta olan önderleyecinin özellikleri
ile uyum sağlayacak şekilde olmalıdır. Aşağıdaki yönergeler Sass'ı referans
alarak verilmiştir.
* Gömmeyi (nesting) sadece 1 bölüm olacak şekilde sınırla. İki seviyeden fazla
olan bütün gömmeleri gözden geçir. Bu aşırı spesifik CSS seçicilerini
engeller.
* Yüksek sayıdaki gömme kurallarını engellemeye çalış. Okunabilirlik
etkilenmeye başladıkça bunları küçük parçalara böl. Tercih 20 satırı aşan
gömmelerin önüne geçmek.
* `@extend` ifadelerini deklarasyon bloğunun ilk satırına koy.
* Mümkün oldukça `@include` ifadelerini deklarasyon bloğunun tepesine `@extend`
ifadelerinden sonrasına koy.
* özel fonksiyonları `x-` veya başka bir isim alanı ile başlat. Bu özel
fonsiyonların CSS fonksiyonları ile karşımasına veya başka kütüphaneler ile
çakışmasına engel olur.
```scss
.selector-1 {
@extend .other-rule;
@include clearfix();
@include box-sizing(border-box);
width: x-grid-unit(1);
// other declarations
}
```
<a name="naming"></a>
## 5. İsimlendirme
Sen bir insan kod derleyicisi/sıkıştırıcı değilsin, dolayısı ile olmaya da
çalışma.
HTML sınıfları için açık ve iyi düşünülmüş isimler kullan. He HTML hem de CSS
dosyalarında anlamı olan tutarlı bir isimlendirme şekli seç.
```css
/* Kötü isim örnekleri kodu */
.s-scr {
overflow: auto;
}
.cb {
background: #000;
}
/* Daha iyi isimli örneklerin kodu */
.is-scrollable {
overflow: auto;
}
.column-body {
background: #000;
}
```
<a name="example"></a>
## 6. Uygulanabilir örnek
Çeşitli teammüllerin örnekleri.
```css
/* ==========================================================================
Grid layout
========================================================================== */
/*
* Örnek HTML:
*
* <div class="grid">
* <div class="cell cell-5"></div>
* <div class="cell cell-5"></div>
* </div>
*/
.grid {
overflow: visible;
height: 100%;
/* inline-block hücrelerin fazla satıra yayılmasını engelle */
white-space: nowrap;
/* Hücre içindeki beyaz alanları kaldır */
font-size: 0;
}
.cell {
box-sizing: border-box;
position: relative;
overflow: hidden;
width: 20%;
height: 100%;
/* Hücre arası boşluğu ayarla */
padding: 0 10px;
border: 2px solid #333;
vertical-align: top;
/* Beyaz alanları sıfırla */
white-space: normal;
/* Font büyüklüğünü sıfırla */
font-size: 16px;
}
/* Hücre durumları */
.cell.is-animating {
background-color: #fffdec;
}
/* Hücre boyutları
========================================================================== */
.cell-1 { width: 10%; }
.cell-2 { width: 20%; }
.cell-3 { width: 30%; }
.cell-4 { width: 40%; }
.cell-5 { width: 50%; }
/* Hücre değişiklikleri
========================================================================== */
.cell--detail,
.cell--important {
border-width: 4px;
}
```
<a name="organization"></a>
## 7. Organizasyon
Kod organizsayonu bütün CSS kod tabanları için önemlidir ve büyük kod tabanları
içinse kritik önem taşır.
* Kodun farklı bölümlerini mantıksal bir şekilde ayır.
* Farklı bileşenleri ayırmak için ayrı dosyalar (inşa sırasında birleştirilen)
kullan.
* Eğer bir önderleyici kullanıyorsan, renk, tipografi gibi genel kodları
değişkenlerle soyutla.
<a name="build-and-deployment"></a>
## 8. Yapı ve Dağıtma (Build and deployment)
Projeler, kaynağın bir şekilde lint edilebileceği, sıkıştırılabileceği, test
edilebileceği, ve üretim için sürümlendirilebileceği soysal (jenerik) bir
yöntem içermelidir. Bunun için Ben Alman'ın
[grunt](https://github.com/cowboy/grunt)'ı mükemmel bir araç.
<a name="acknowledgements"></a>
## Teşekkürler
İlham, alıntı ve kılavuz bir kaynak olan
[idiomatic.js](https://github.com/rwldrn/idiomatic.js)'ye katkıda bulunan
herkese teşekkürler.
================================================
FILE: translations/zh-CN/README.md
================================================
# 编写如一、符合习惯的CSS的原则
以下文档将概述一个合理的CSS开发风格指导。本指导文件强烈鼓励开发者使用已经存在了的、常见的、合力的文风。您应该有选择地吸纳一些内容来创造您自己的风格指南。
这个文档将持续更新，欢迎提出新的想法。还请多多贡献。
[Principles of writing consistent, idiomatic CSS（原版）](https://github.com/necolas/idiomatic-css)
## 目录
1. [通用原则](#general-principles)
2. [空格](#whitespace)
3. [注释](#comments)
4. [格式](#format)
5. [命名](#naming)
6. [实例](#example)
7. [代码组织](#organization)
8. [构建及部署](#build-and-deployment)
[致谢](#acknowledgements)
<a name="general-principles"></a>
## 1. 通用原则
> “作为成功的项目的一员，很重要的一点是意识到只为自己写代码是很糟糕的行为。如果将有成千上万人使用你的代码，
> 那么你需要编写最具明确性的代码，而不是以自我的喜好来彰显自己的智商。” - Idan Gazit
* 别想着过早地优化代码。先得保证它们可读又可理解才行。
* 在任何代码库中，无论有多少人参与及贡献，所有代码都应该如同一个人编写的一样。
* 严格执行一致认可的风格。
* 如果有疑议，则使用现有的、通用的模式。
<a name="whitespace"></a>
## 2. 空格
在项目的所有代码中，应该只有一个风格。在空格的使用上，必须始终保持一致。使用空格来提高可读性。
* *永远不要*在缩进时混用空格和制表符（又称TAB符号）。
* 在软缩进（使用空格）和真正的制表符间选择其一，并始终坚持这一选择。（推荐使用空格）
* 如果使用空格进行缩进，选择每个缩进所使用的空格数。（推荐：4个空格）
提示：将编辑器配置为“显示不可见内容”。这使你可以清除行尾的空格和不需要缩进的空行里的空格，同时可以避免对注释的污染。
提示：确定好一种空格格式后，您可以用一个[EditorConfig](http://editorconfig.org/)文件（或者其他相同的东西）来帮助在代码库之间维持这种基本的空格约定。
<a name="comments"></a>
## 3. 注释
良好的注释是非常重要的。请留出时间来描述组件（component）的工作方式、局限性和构建它们的方法。不要让你的团队其它成员
来猜测一段不通用或不明显的代码的目的。
注释的风格应当简洁，并在代码库中保持统一。
* 将注释放在主题上方并独占一行。
* 控制每行长度在合理的范围内，比如80个字符。
* 使用注释从字面上将CSS代码分隔为独立的部分。
* 注释的大小写应当与普通句子相同，并且使用一致的文本缩进。
提示：通过配置编辑器，可以提供快捷键来输出一致认可的注释模式。
#### CSS示例：
```css
/* ==========================================================================
区块代码注释
========================================================================== */
/* 次级区块代码注释
========================================================================== */
/**
* “Doxygen式注释格式”的简短介绍
*
* 较长的说明文本从这里开始，这是这段文字的第一句话，而且这句话还
* 没结束，过了好一会儿，我了个去终于结束了，烦不烦啊。
*
* 当需要进行更细致的解释说明、提供文档文本时，较长的说明文本就很
* 有用了。这种长长的说明文本，可以包括示例HTML啦、链接啦等等其
* 他你认为重要或者有用的东西。
*
* @tag 这是一个叫做“tag”的标签。
*
* TODO: 这个“‘需做’陈述”描述了一个接下来要去做的小工作。这种文本，
* 如果超长了的话，应该在80个半角字符（如英文）或40个全角字符（
* 如中文）后便换行，并（在“ * ”的基础上）再在后面缩进两个空格。
*/
/* 一般的注释 */
```
<a name="format"></a>
## 4. 格式
最终选择的代码风格必须保证：易于阅读，易于清晰地注释，最小化无意中引入错误的可能性，可生成有用的diff和blame。
1. 在多个选择器的规则集中，每个单独的选择器独占一行。
2. 在规则集的左大括号前保留一个空格。
3. 在声明块中，每个声明独占一行。
4. 每个声明前保留一级缩进。
5. 每个声明的冒号后保留一个空格。
6. 对于声明块的最后一个声明，始终保留结束的分号。
7. 规则集的右大括号保持与该规则集的第一个字符在同一列。
8. 每个规则集之间保留一个空行。
```css
.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;
}
```
#### 声明顺序
样式声明的顺序应当遵守一个单一的原则。我的倾向是将相关的属性组合在一起，并且将对结构来说比较重要的属性（如定位或者盒模型）
放在前面，先于排版、背景及颜色等属性。
小型的开发团体，可能会想要把相关的属性声明（比如说定位和箱模型）摆在一起。
```css
.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;
}
```
大型团队，则可能更喜欢按字母排序，因为这样做起来很方便，而且维护起来很容易。
#### 例外及细微偏移原则的情况
对于大量仅包含单条声明的声明块，可以使用一种略微不同的单行格式。在这种情况下，在左大括号之后及右大括号之前都应该保留一个空格。
```css
.selector-1 { width: 10%; }
.selector-2 { width: 20%; }
.selector-3 { width: 30%; }
```
对于以逗号分隔并且非常长的属性值 -- 例如一堆渐变或者阴影的声明 -- 可以放在多行中，这有助于提高可读性，并易于生成有效的diff。这种情况下有多
种格式可以选择，以下展示了一种格式。
```css
.selector {
box-shadow:
1px 1px 1px #000,
2px 2px 1px 1px #ccc inset;
background-image:
linear-gradient(#fff, #ccc),
linear-gradient(#f3c, #4ec);
}
```
#### 杂项
* 在十六进制值中，使用小写，如`#aaa`。
* 单引号或双引号的选择保持一致。推荐使用双引号，如`content: ""`。
* 对于选择器中的属性值也加上引号，如`input[type="checkbox"]`。
* *如果可以的话*，不要给0加上单位, 如`margin: 0`。
### 预处理：格式方面额外的考虑
不同的CSS预处理有着不同的特性、功能以及语法。编码习惯应当根据使用的预处理程序进行扩展，以适应其特有的功能。推荐在使用SCSS时遵守以下指导。
* 将嵌套深度限制在1级。对于超过2级的嵌套，给予重新评估。这可以避免出现过于详实的CSS选择器。
* 避免大量的嵌套规则。当可读性受到影响时，将之打断。推荐避免出现多于20行的嵌套规则出现。
* 始终将`@extend`语句放在声明块的第一行。
* 如果可以的话，将`@include`语句放在声明块的顶部，紧接着`@extend`语句的位置。
* 考虑在自定义函数的名字前加上`x-`或其它形式的前缀。这有助于避免将自己的函数和CSS的原生函数混淆，或函数命名与库函数冲突。
```scss
.selector-1 {
@extend .other-rule;
@include clearfix();
@include box-sizing(border-box);
width: x-grid-unit(1);
// other declarations
}
```
<a name="naming"></a>
## 5. 命名
不要试着把自己当作编译器或者预处理器，因此命名的时候尽量采用清晰的、有意义的名字。另外，对于
html文件和css文件中的代码，尽量采用一致的命名规则。
```css
/* 没有意义的命名 */
.s-scr {
overflow: auto;
}
.cb {
background: #000;
}
/* 比较有意义的命名方式 */
.is-scrollable {
overflow: auto;
}
.column-body {
background: #000;
}
```
<a name="example"></a>
## 6. 实例
下面是含有上述约定的示例代码：
```css
/* ==========================================================================
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="organization"></a>
## 7. 代码组织
对于css代码库来说，如何组织代码文件是很重要的，尤其对于那些很大的代码库显得更加重要。这里介绍
几个组织代码的建议：
* 逻辑上对不同的代码进行分离。
* 不同的组件(component)的css尽量用不同的css文件（可以在build阶段用工具合并到一起）
* 如果用到了预处理器（比如less），把一些公共的样式代码抽象成变量，例如颜色，字体等等。
<a name="build-and-deployment"></a>
## 8. 构建及部署
任何一个项目，都应该有一个build的过程，在这个阶段我们可以通过工具对代码进行检测，测试，压缩等等，还
可以为生产环境准备好带有版本号的代码。在这里我推荐一下[grunt](https://github.com/cowboy/grunt)这个工具，我感觉它很不错。
<a name="acknowledgements"></a>
## 致谢
感谢所有对[idiomatic.js](https://github.com/rwldrn/idiomatic.js)作出贡献的网友。
##许可
_Principles of writing consistent, idiomatic CSS_ 是Nicolas Gallagher发布在[Creative Commons Attribution 3.0 Unported License](http://creativecommons.org/licenses/by/3.0/)许可证下的作品。该许可证适用于本代码栈中的所有文档，包括翻译文本。
本作品基于[github.com/necolas/idiomatic-css](https://github.com/necolas/idiomatic-css)著就。
================================================
FILE: translations/zh-TW/README.md
================================================
# 通順一致的CSS編寫原則
以下的文件描述了一個合理的CSS開發風格規範。
這些守則特別著重於使用現有那些普遍且合理的形式。你可以採用它們來創造你自己的風格規範。
這是一份持續更新的文件，而且永遠歡迎新的想法，別吝於貢獻。
## 目錄
1. [通用原則](#general-principles)
2. [空格](#whitespace)
3. [註解](#comments)
4. [格式](#format)
5. [實例](#example)
[Acknowledgements](#acknowledgements)
[License](#license)
<a name="general-principles"></a>
## 1. 通用原則
> 「良好管理成功專案的其中一點是能夠了解到
> 只為自己寫代碼是很糟糕的行為。如果有很多人正在使用你寫的代碼，
> 那麼盡可能保持你的代碼明確可讀，而不是在規格中隨個人喜好取巧。」- Idan Gazit
* 不要嘗試過早地優化你的代碼。讓它保持易讀且容易理解。
* 不論有多少人參與，專案內任何項目的代碼都應該要看起來像是同一人的手筆。
* 嚴格實行被一致認同的風格。
* 當對風格有疑義時應採行現有而普遍的形式。
<a name="whitespace"></a>
## 2. 空格
在全部的項目原始碼中只能有唯一的風格，在使用空白時應永遠保持一致性。
使用空白來提升可讀性。
* _絕對_ 不要在縮排時混用空格和跳格。
* 在偽縮排（空格）或是真正的跳格中擇一。並且堅持你的選擇不要漏失。（建議使用：空格）
* 如果使用空格，指定每個縮進等級使用的字元長度。（建議使用：4個空格）
提示: 設定你的編輯器「顯示不可見字元」或是自動移除行尾空白。
提示: 使用 [EditorConfig](http://editorconfig.org/) 設定檔 （或是類似的工具） 來協助維護項目中已被接受的基本空白慣例。
<a name="comments"></a>
## 3. 註解
代碼有良好註解是非常重要的。留些時間去描述元件是如何作用，有哪些侷限，以及是如何組成的。
別讓團隊裡的其他人去猜測那些不尋常的或是意圖不明顯的代碼。
註解的風格在同一專案項目中應該力求簡明一致。
* 將註解放在解釋的對象上方並獨立成行。
* 保持單行長度在一個合理的最大值，例如：80個字元。
* 使用字面上的註解把 CSS 代碼分隔成不同的部分。
* 使用與一般文句相同的大小寫以及一致的段落縮排。
提示: 設定你的編輯器以提供快捷鍵來輸出被一致接受的註解形式。
範例:
```css
/* ==========================================================================
註解章節區塊
========================================================================== */
/* 註解子章節區塊
========================================================================== */
/**
* 使用Doxygen風格註解格式的簡短描述
*
* 這一長段敘述的第一個句子從這裡開始，在這行持續一下子，
* 最後收尾在這段的結尾。
*
* 這一長段敘述對於更仔細的解釋以及說明是很合適的。它可以包含一些範例 HTML、URL，
* 或是任何其他有用或必要的資訊。
*
* @tag 這是一個命名為'tag'的標籤
*
* TODO: 這是描述一個要在稍後完成的簡單任務的待辦事項。
* 它在80個字元長度後斷行（譯註：翻成中文後在這裡並非如此）且以下每行
* 都使用兩個空白縮進。
*/
/* 基本註解 */
```
<a name="format"></a>
## 4. 格式
指定的代碼格式必須要確保的是：易於閱讀；易於清晰地註解；減少意外引入錯誤的機會；
而且可以產生實用的 diff 以及 blame 。
* 在有許多選擇器的樣式集中，讓每個單獨的選擇器單獨成行。
* 在樣式集的開始括號前保留一個空格。
* 在樣式區塊中保持每個樣式至少一行。
* 在每個樣式前使用一個段落的縮進。
* 在每個樣式的冒號後保留一個空格。
* 使用小寫以及縮略的 HEX 數值，例如：`#aaa`。
* 一致地使用單引號或是雙引號。推薦使用雙引號，例如：`content: ""`。
* 在選擇器中以引號夾注屬性值，例如： `input[type="checkbox"]`。
* _可以的話_，避免在值為零時指定單位，例如：`margin: 0`。
* 在每一個以逗號分隔的屬性的逗號或是函式值後面保留一個空格。
* 在樣式區塊的最後一個樣式結尾保留分號。
* 樣式集的結束括號應該擺放在與樣式集的第一個字元同樣位置。
* 以一個空白行分隔每個樣式集。
```css
.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;
}
```
#### 宣告順序
如果宣告按照順序一貫地排列下來，應當要符合一個簡單的原則。
比較小的團隊們也許會偏好將有關聯的屬性（例如位置和容器模型）群組在一起。
```css
.selector {
/* 位置 */
position: absolute;
z-index: 10;
top: 0;
right: 0;
bottom: 0;
left: 0;
/* 顯示 & 區塊模型 */
display: inline-block;
overflow: hidden;
box-sizing: border-box;
width: 100px;
height: 100px;
padding: 10px;
border: 10px solid #333;
margin: 10px;
/* 其它 */
background: #000;
color: #fff;
font-family: sans-serif;
font-size: 16px;
text-align: right;
}
```
比較大的團隊們也許會偏好以字母排序所帶來的簡潔性以及易於維護。
#### 例外與細微偏差
對於大量只包含逐一樣式宣告的區塊，可以採用一種稍微不同的單行格式。
在這種情況下，應在開始括號之後以及結束括號之前都保留一個空格。
```css
.selector-1 { width: 10%; }
.selector-2 { width: 20%; }
.selector-3 { width: 30%; }
```
對於很長且以逗號分隔的屬性值——例如漸層或是陰影的集合——可以整理成多行達到改善可讀性以及產生更有用 diff 的效果，這時有許多種格式可以使用。
底下有個例子。
```css
.selector {
background-image:
linear-gradient(#fff, #ccc),
linear-gradient(#f3c, #4ec);
box-shadow:
1px 1px 1px #000,
2px 2px 1px 1px #ccc inset;
}
```
### 預處理器: 額外的格式考量
不同的 CSS 預處理器有不同的特色、功能、以及語法。
應該要考慮到隨著所採用的不同預處理器的特點而去擴充你們的慣例。以下是關於 Sass 的守則。
* 將嵌套深度限制在一個階層。對於任何兩階以上的深度重新評估。這將避免寫出過於針對性的 CSS 選擇器。
* 避免大量的嵌套規則。當可讀性開始受到影響時將它們打散。盡量避免超過20行的嵌套。
* 永遠將 `@extend` 宣告擺在樣式區塊的第一行。
* 可能的話，將 `@include` 宣告群組置於樣式區塊的頂部，緊接著任何 `@extend` 宣告之後。
* 考慮在自訂函式的前面加上`x-`或是其他的命名空間。這有助於避免與原生的 CSS 函式混淆，或是與其它函式庫衝突。
```scss
.selector-1 {
@extend .other-rule;
@include clearfix();
@include box-sizing(border-box);
width: x-grid-unit(1);
// other declarations
}
```
<a name="example"></a>
## 5. 實例
這是遵循上述那些規範的範例。
```css
/* ==========================================================================
格線佈局
========================================================================== */
/**
* 帶有橫向捲軸的欄位佈局。
*
* 這會產生一個由全高且不斷開的多欄區塊組成的單列，可以在它的上層容器中橫向瀏覽。
*
* 範例 HTML:
*
* <div class="grid">
* <div class="cell cell-3"></div>
* <div class="cell cell-3"></div>
* <div class="cell cell-3"></div>
* </div>
*/
/**
* 格線容器
*
* 必須只包含 `.cell` 子元素.
*
* 1. 移除網格間的空白
* 2. 避免 inline-block 網格斷開
*/
.grid {
height: 100%;
font-size: 0; /* 1 */
white-space: nowrap; /* 2 */
}
/**
* 系統網格
*
* 不預設固定的寬度. 用 `.cell-n` 類別來變化。
*
* 1. 設定網格內間距
* 2. 重設自 `.grid` 串接來的 white-space 屬性
* 3. 重設自 `.grid` 串接來的 font-size 屬性
*/
.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.is-animating {
background-color: #fffdec;
}
/* 網格維度
========================================================================== */
.cell-1 { width: 10%; }
.cell-2 { width: 20%; }
.cell-3 { width: 30%; }
.cell-4 { width: 40%; }
.cell-5 { width: 50%; }
/* 網格修飾
========================================================================== */
.cell--detail,
.cell--important {
border-width: 4px;
}
```
<a name="acknowledgements"></a>
## Acknowledgements
Thanks to everyone who has provided translations and to all those who
contributed to [idiomatic.js](https://github.com/rwldrn/idiomatic.js). It was a
source of inspiration, quotations, and guidelines.
<a name="license"></a>
## License
_Principles of writing consistent, idiomatic CSS_ by Nicolas Gallagher is
licensed under the [Creative Commons Attribution 3.0 Unported
License](http://creativecommons.org/licenses/by/3.0/). This applies to all
documents and translations in this repository.
Based on a work at
[github.com/necolas/idiomatic-css](https://github.com/necolas/idiomatic-css).
gitextract_7ezio74a/
├── README.md
└── translations/
├── cs-CZ/
│ └── README.md
├── da-DK/
│ └── README.md
├── de-DE/
│ └── README.md
├── es-ES/
│ └── README.md
├── fr-FR/
│ └── README.md
├── id-ID/
│ └── README.md
├── it-IT/
│ └── README.md
├── ja-JP/
│ └── README.md
├── ko-KR/
│ └── README.md
├── nl-NL/
│ └── README.md
├── pl-PL/
│ └── README.md
├── pt-BR/
│ └── README.md
├── ru-RU/
│ └── README.md
├── sr-SR/
│ └── README.md
├── tr-TR/
│ └── README.md
├── zh-CN/
│ └── README.md
└── zh-TW/
└── README.md
Condensed preview — 18 files, each showing path, character count, and a content snippet. Download the .json file or copy for the full structured content (199K chars).
[
{
"path": "README.md",
"chars": 11910,
"preview": "# Principles of writing consistent, idiomatic CSS\n\nThe following document outlines a reasonable style guide for CSS deve"
},
{
"path": "translations/cs-CZ/README.md",
"chars": 11741,
"preview": "# Zásady psaní konzistentního, idiomatického CSS\n\nTohle je příručka stylu (_style guide_) pro psaní CSS. Neberte ji jako"
},
{
"path": "translations/da-DK/README.md",
"chars": 11568,
"preview": "# Principper for at skrive konsistent, idiomatisk CSS\n\nDette dokument skitserer en række fornuftige og logiske retningsl"
},
{
"path": "translations/de-DE/README.md",
"chars": 11723,
"preview": "# Grundlagen zum Schreiben von einheitlichem, idiomatischem CSS\n\nDas folgende Dokument legt eine vernünftige Gestaltungs"
},
{
"path": "translations/es-ES/README.md",
"chars": 12828,
"preview": "# Principios para escribir CSS idiomático y consistente\n\nEl siguiente documento ofrece una guía razonable de estilo para"
},
{
"path": "translations/fr-FR/README.md",
"chars": 11815,
"preview": "# Principes d'écriture pour des CSS cohérents et idiomatiques\n\nLe présent document liste des recommandations raisonnable"
},
{
"path": "translations/id-ID/README.md",
"chars": 10660,
"preview": "# Prinsip Penulisan CSS yang Konsisten, Idiomatic\n\nDokumen dibawah ini menjelaskan petunjuk umum dalam pengembangan CSS."
},
{
"path": "translations/it-IT/README.md",
"chars": 11976,
"preview": "# Princìpi per la scrittura di CSS consistente ed idiomatico\n\nL'intento di questo documento è quello di esporre una ragi"
},
{
"path": "translations/ja-JP/README.md",
"chars": 6915,
"preview": "# 一貫性のあるCSSらしいCSSを書くための原則\n\n以下の文書はCSS開発のための合理的なスタイルガイドの骨子です。\n規範になるべきものではないし、私自身のスタイルの好みを他者のコードに押し付けるつもりは一切ありません。しかし、これらのガ"
},
{
"path": "translations/ko-KR/README.md",
"chars": 7213,
"preview": "# 일관성있는 CSS다운 CSS를 작성하기 위한 원칙\n\n이하 문서는 CSS개발을 위한 합리적인 스타일가이드의 중요한 내용입니다.\n규범이 될만한 것이라 하긴 좀 그렇고 스스로 스타일 작업시 즐겨쓰는 방식을 다른분들께 "
},
{
"path": "translations/nl-NL/README.md",
"chars": 10993,
"preview": "# Principes voor het schrijven van consistente, idiomatische CSS\n\nHet volgende document schetst een logische stijlgids v"
},
{
"path": "translations/pl-PL/README.md",
"chars": 12152,
"preview": "# Zasady tworzenia spójnych, zgodnych z regułami języka deklaracji CSS\n\nPoniżej opisane zostały podstawowe zasady tworze"
},
{
"path": "translations/pt-BR/README.md",
"chars": 13095,
"preview": "# Princípios para escrever CSS de forma consistente e idiomática\n\nO documento a seguir descreve um sensato guia de estil"
},
{
"path": "translations/ru-RU/README.md",
"chars": 11088,
"preview": "# Принципы написания однородного CSS-кода\n\nЭтот документ представляет собой общие рекомендации по стилю написания CSS. "
},
{
"path": "translations/sr-SR/README.md",
"chars": 10922,
"preview": "# Principi pisanja konzistentnog, idiomatskog CSS-a\n\nSledeći dokument ocrtava razumne stilove za CSS razvoj. Nije namenj"
},
{
"path": "translations/tr-TR/README.md",
"chars": 10590,
"preview": "# Tutarlı, İdiomatic CSS yazma prensipleri\n\nAşağıdaki döküman CSS geliştirme konusunda makul bir stil rehberini içerir.\n"
},
{
"path": "translations/zh-CN/README.md",
"chars": 7290,
"preview": "# 编写如一、符合习惯的CSS的原则\n\n以下文档将概述一个合理的CSS开发风格指导。本指导文件强烈鼓励开发者使用已经存在了的、常见的、合力的文风。您应该有选择地吸纳一些内容来创造您自己的风格指南。\n\n这个文档将持续更新，欢迎提出新的想法。还"
},
{
"path": "translations/zh-TW/README.md",
"chars": 6211,
"preview": "# 通順一致的CSS編寫原則\n\n以下的文件描述了一個合理的CSS開發風格規範。\n這些守則特別著重於使用現有那些普遍且合理的形式。你可以採用它們來創造你自己的風格規範。\n\n這是一份持續更新的文件，而且永遠歡迎新的想法，別吝於貢獻。\n\n\n## "
}
]
About this extraction
This page contains the full source code of the necolas/idiomatic-css GitHub repository, extracted and formatted as plain text for AI agents and large language models (LLMs). The extraction includes 18 files (186.2 KB), approximately 56.2k tokens. Use this with OpenClaw, Claude, ChatGPT, Cursor, Windsurf, or any other AI tool that accepts text input. You can copy the full output to your clipboard or download it as a .txt file.
Extracted by GitExtract — free GitHub repo to text converter for AI. Built by Nikandr Surkov.