თანმიმდევრული, იდიომატური CSS-ის წერის პრინციპები

დედანი: necolas/idiomatic-css

წინამდებარე დოკუმენტი წარმოადგენს CSS-ის სტილისტიკის ზოგად სახელმძღვანელოს. მოცემული მითითებები ძლიერ წაახალისებს არსებული, ფართოდ გავრცელებული, გონივრული მიდგომების გამოყენებას. საჭიროებისამებრ, თქვენ მიერ უნდა მოხდეს მათი გადაკეთება, რათა შექმნათ თქვენი საკუთარი სტილისტიკური მიდგომები.

წინამდებარე დოკუმენტი მუდმივი განვითარების პროცესშია და ახალი იდეები ყოველთვის მისასალმებელია. გთხოვთ, შეიტანეთ თქვენი წვლილი მისი განვითარების პროცესში.

სარჩევი

1. ზოგადი პრინციპები
2. ინტერვალი
3. კომენტარები
4. ფორმატი
5. პრაქტიკული მაგალითი

მადლობა

1. ზოგადი პრინციპები

„იმის გაცნობიერება, რომ კოდის მხოლოდ საკუთარი თავისთვის წერა ცუდი იდეაა™, წარმატებული პროექტის კარგ ხელმძღვანელად ყოფნის განუყოფელი ნაწილია. თუკი ათასობით ადამიანი იყენებს თქვენს კოდს, დაწერეთ იგი რაც შეიძლება ნათლად და ნუ გააკეთებთ რამეს მხოლოდ იმიტომ, რომ ენის სპეციფიკაცია ამის საშუალებას იძლევა.“ — აიდან გაზიტი

• ნუ ეცდებით თქვენი კოდის წინასწარ ოპტიმიზირებას; შუუნარჩუნეთ მას წაკითხვადი და გასაგები სახე.
• ნებისმიერ პროექტში არსებული მთლიანი კოდი ისე უნდა გამოიყურებოდეს, თითქოს ერთმა ადამიანმა დაწერა, მაშინაც კი, როცა მის შექმნაში მრავალი ადამიანი იღებს მონაწილეობას.
• მკაცრად დაიცავით შეთანხმებული სტილი.
• თუ ეჭვი გეპარებათ შერჩეული სტილის სისწორეში, გამოიყენეთ უკვე არსებული, ფართოდ გავრცელებული მიდგომები.

2. ინტერვალი

მთელი კოდის მასშტაბით მხოლოდ ერთი სტილი უნდა ვრცელდებოდეს. მუდამ იყავით თანმიმდევრული ინტერვალის გამოყენებისას. გამოიყენეთ ინტერვალი წაკითხვადობის გასაუმჯობესებლად.

• არასოდეს აურიოთ ერთმანეთში ინტერვალები და ტაბულაცია.
• გააკეთეთ არჩევანი რბილ აბზაცებსა (ინტერვალები) და ნამდვილ ტაბულაციას შორის (სასურველია არჩევანი შეაჩეროთ ინტერვალებზე) და დაიცავით თქვენი არჩევანი უშეცდომოდ.
• თუ ინტერვალებს იყენებთ, შეარჩიეთ სიმბოლოთა ფიქსირებული რაოდენობა ყოველი აბზაცისათვის (სასურველია 4 ინტერვალი).

რჩევა: მოახდინეთ თქვენი რედაქტორის კონფიგურირება ისე, რომ „გიჩვენოთ უხილავი სიმბოლოები“ ან ავტომატურად წაშალოს არასაჭირო ინტერვალი ხაზის ბოლოში.

რჩევა: გამოიყენეთ EditorConfig ფაილი (ან მისი ეკვივალენტი), რომელიც დაგეხმარებათ შეინარჩუნოთ ინტერვალის ის ძირითადი კანონზომიერებები, რომლებიც თქვენი კოდისთვის შეარჩიეთ.

3. კომენტარები

კოდის სწორად კომენტირება უაღრესად მნიშვნელოვანია. დაუთმეთ დრო კომპონენტების აღწერას: როგორ მუშაობენ ისინი, რა შეზღუდვები აქვთ და როგორ არიან აგებული.
ნუ ჩააგდებთ გუნდის სხვა წევრებს საგონებელში, დაადგინონ, რა არის უჩვეულო ან ბუნდოვანი კოდის დანიშნულება.

კომენტარების ჩაწერის სტილი უნდა იყოს მარტივი და ურთიერთშეთანხმებული მთელი პროექტის მასშტაბით.

• განათავსეთ კომენტარები ახალ ხაზზე, აღსაწერი კოდის ფრაგმენტის ზემოთ.
• ეცადეთ ხაზის სიგრძე არ აღემატებოდეს გონივრულ მაქსიმუმს, მაგალითად, 80 სიმბოლოს.
• ნუ შეიზღუდავთ თავს კომენტარების გამოყენებისგან CSS-კოდის ცალკეულ განყოფილებებად დანაწევრებისთვის.
• კომენტარები ჩაწერეთ ჩვეულებრივი გრამატიკული წინადადებების სახით. წინადადების ჩაწერა დაიწყეთ დიდი ასოთი და საჭიროებისამებრ გამოყავით აბზაცები.

რჩევა: მოახდინეთ თქვენი რედაქტორის კონფიგურირება ისე, რომ თავად რედაქტორმა შემოგთავაზოთ უმოკლესი გზა წინასწარ შეთანხმებული მიდგომების გათვალისწინებით კომენტარების ჩასაწერად.

მაგალითი:

/* ==========================================================================
   კომენტარის ბლოკი განყოფილებისათვის
   ========================================================================== */

/* კომენტარის ბლოკი ქვეგანყოფილებისათვის
   ========================================================================== */

/**
 * მოკლე აღწერა Doxygen სტილის კომენტარის ფორმატით
 *
 * ვრცელი აღწერის პირველი წინადადება იწყება აქ და გრძელდება
 * ამ ხაზზე, საბოლოოდ კი მთავრდება აქ, — პარაგრაფის ბოლოში.
 *
 * ვრცელი აღწერა იდეალური ვარიანტია იფრო დეტალური აღწერისა და
 * დოკუმენტაციის უზრუნველსაყოფად. ის შეიძლება შეიცავდეს HTML-ის ფრაგმენტს, URL-ებს ან ნებისმიერ
 * სხვა ინფორმაციას, რომელიც საჭიროდ ან გამოსადეგად იქნება მიჩნეული.
 *
 * @tag ეს არის ტეგი სახელად „tag“
 *
 * TODO: ეს არის „todo“ განცხადება, რომელიც აღწერს მოგვიანებით აუცილებლად
 *   შესასრულებელ ამოცანას. მისი ყოველი ხაზი შედგება არაუმეტეს 80 სიმბოლოსგან
 *   და 2 ინტერვალიანი აბზაცისგან.
 */

/* მინიმალისტური კომენტარი */

4. ფორმატი

თქვენ მიერ შერჩეული კოდის ჩაწერის ფორმატი უნდა იძლეოდეს გარანტიას, რომ კოდი არის მარტივად წაკითხვადი, შედგება მარტივად გასაგები კომენტარებისგან, მინიმუმამდე დაჰყავს შეცდომების დაშვების შანსი და იძლევა გამოსადეგ შეტყობინებებს ვერსიების კონტროლის კონტექსტში.

• რამდენიმე სელექტორისგან შემდგარი წესების ნაკრების ჩაწერისას, ყოველი ცალკეული სელექტორი განათავსეთ ცალკე ხაზზე.
• წესების ნაკრების გამხსნელი ფიგურული ფრჩხილის წინ განათავსეთ ერთი ინტერვალი.
• დეკლარაციათა ბლოკში შემავალი ყოველი დეკლარაცია განათავსეთ ცალკე ხაზზე.
• თითოეული დეკლარაციისთვის გამოიყენეთ ერთდონიანი აბზაცი (ერთი ტაბულაცია).
• დეკლარაციაში, ორწერტილის შემდეგ განათავსეთ ერთი ინტერვალი.
• გამოიყენეთ პატარა ასოებით ჩაწერილი შემოკლებული თექვსმეტობითი მნიშვნელობები. მაგალითად: #aaa.
• მუდმივად გამოიყენეთ ერთმაგი ან ორმაგი ბრჭყალები (ნუ მოახდენთ მათ შერევას). სასურველია ორმაგი ბრჭყალების გამოყენება, მაგალითად: content: "".
• სელექტორებში, ატრიბუტების მნიშვნელობები ჩასვით ბრჭყალებში. მაგალითად: input[type="checkbox"].
• დასაშვებ შემთხვევებში, მოერიდეთ ნულოვანი მნიშვნელობებისათვის ერთეულების განსაზღვრას. მაგალითად: margin: 0.
• მძიმით გამოყოფილ თვისებათა ან ფუნქციათა მნიშვნელობებში, ყოველი მძიმის შემდეგ განათავსეთ ერთი ინტერვალი.
• დეკლარაციათა ბლოკის უკანასკნელი დეკლარაციის ბოლოში(ც) განათავსეთ წერტილ-მძიმე.
• წესების ნაკრების დამხურავი ფრჩხილი განათავსეთ იმავე სვეტზე, რომელზედაც წესების ნაკრების პირველი სიმბოლოა განთავსებული.
• წესების თითოეული ნაკრები (ერთმანეთისაგან) გამოყავით ცარიელი ხაზით.

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

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

დეკლარაციათა თანმიმდევრობა

თუ დეკლარაციების თანმიმდევრობით დალაგებაა საჭირო, ეს უნდა მოხდეს ერთი, მარტივი პრინციპის შესაბამისად.

შედარებით პატარა გუნდებმა (იგულისხმება დეველოპერთა გუნდები) შესაძლოა უპირატესობა მიანიჭონ ურთიერთდაკავშირებულ თვისებათა (მაგ. პოზიციონირება და ბლოკის მოდელი (box-model)) ერთად თავმოყრას.

.selector {
    /* პოზიციონირება */
    position: absolute;
    z-index: 10;
    top: 0;
    right: 0;
    bottom: 0;
    left: 0;

    /* ვიზუალიზაცია (Display) და ბლოკის მოდელი */
    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;
}

უფრო დიდმა გუნდებმა კი შესაძლოა სიმარტივესა და მოხერხებულად მოვლის შესაძლებლობაზე გააკეთონ არჩევანი, რაც ანბანური თანმიმდევრობით დალაგების პრინციპისთვის არის დამახასიათებელი.

გამონაკლისები და მცირედი გადახვევები

ერთი დეკლარაციისგან შემდგარი დიდი ბლოკებისთვის შეიძლება გამოყენებულ იქნეს ოდნავ განსხვავებული, ერთხაზიანი ფორმატი. ამ შემთხვევაში, ინტერვალი გამხსნელი ფრჩხილის შემდეგ და დამხურავი ფრჩხილის წინ უნდა განთავსდეს.

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

გრძელი, მძიმით გამოყოფილი თვისებათა მნიშვნელობები — როგორიცაა გრადიენტთა ან ჩრდილთა კრებული — შეიძლება განლაგებულ იქნეს მრავალ სტრიქონზე, რათა გაუმჯობესდეს წაკითხვადობა და წარმოიქმნას მეტად გამოსადეგი diff-ები. არსებობს ჩაწერის სხვადასხვა ფორმატები; ერთ-ერთი ვარიანტი მოცემულია ქვემოთ.

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

პრეპროცესორები: დამატებითი მოსაზრებები ფორმატის თაობაზე

სხვადასხვა CSS-პრეპროცესორს განსხვავებული ფუნქციონალი და სინტაქსი აქვს. თქვენი მიდგომები უნდა მოერგოს თქენ მიერ გამოყენებული ამა თუ იმ პრეპროცესორის თავისებურებებს. ქვემოთ მოცემული მითითებები Sass-ზე ვრცელდება.

• შეზღუდეთ (დეკლარაციათა) ჩადგმის სიღრმე ერთამდე. მოახდინეთ კოდის ნებისმიერი ფრაგმენტის გადაფასება, სადაც ჩადგმის სიღრმე ერთს აღემატება. ეს ზედმეტად სპეციფიკური CSS-სელექტორების აღმოფხვრას შეუწყობს ხელს.
• მოერიდეთ ჩადგმული წესის დეკლარაციების დიდი რაოდენობით გამოყენებას. როგორც კი შეატყობთ, რომ ისინი წაკითხვადობაზე ცუდად ზემოქმედებენ, დაყავით ისინი პატარა, ლოგიკურ ფრაგმენტებად. უმჯობესია, ჩადგმული კოდი ვრცელდებოდეს არაუმეტეს 20 ხაზის მასშტაბით.
• @extend განცხადებები ყოველთვის განათავსეთ დეკლარაციის ბლოკის პირველ ხაზებში.
• სადაც ამის შესაძლებლობა გექნებათ, @include განცხადებებს თავი მოუყარეთ დეკლარაციის ბლოკის პირველ ხაზებში, @extend განცხადებების შემდეგ.
• განიხილეთ თქვენ მიერ შექმნილი (custom) ფუნქციებისათვის x- ან სხვა namespace-ის დამატება თავსართის სახით. ეს დაგეხმარებათ თავიდან აირიდოთ ყველანაირი შესაძლებლობა იმისა, რომ თქვენ მიერ შექმნილ და CSS-ში ჩაშენებულ ფუნქციებს შორის, — ასევე თქვენ მიერ შექმნილ და ბიბლიოთეკების მიერ უზრუნველყოფილ ფუნქციებს შორის, — მოხდება კონფლიქტი.

.selector-1 {
    @extend .other-rule;
    @include clearfix();
    @include box-sizing(border-box);
    width: x-grid-unit(1);
    // სხვა დეკლარაციები
}

5. პრაქტიკული მაგალითი

რამდენიმე კანონზომიერების მაგალითი.

/* ==========================================================================
   Grid-აგებულება
   ========================================================================== */

/**
 * ჰორიზონტალური სქროლის მქონე სვეტის აგებულება.
 *
 * იქმნება სრული სიმაღლის მქონე, შეუფუთავი სვეტების ერთი რიგი,
 * რომელთა დათვალიერებაც შესაძლებელია ჰორიზონტალურად, კონტეინერის
 * (ანუ მშობელი ელემენტის) შიგნით.
 *
 * HTML-ის ნიმუში:
 *
 * <div class="grid">
 *     <div class="cell cell-3"></div>
 *     <div class="cell cell-3"></div>
 *     <div class="cell cell-3"></div>
 * </div>
 */

/**
 * Grid-კონტეინერი:
 *
 * უნდა შეიცავდეს მხოლოდ `.cell` შვილობილ ელემენტებს.
 *
 * 1. უჯრედთაშორისი სივრცის მოცილება
 * 2. მწკრივულ უჯრედთა ბლოკის შეფუთვის აღმოფხვრა
 */

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

/**
 * Grid-უჯრედები
 *
 * ნაგულისხმევად, ზუსტი სიგანე არ არის განსაზღვრული. გავრცობილია `.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;
}

მადლობა

მადლობა ყველას, ვინც მონაწილეობა მიიღო თარგმანების შემუშავების პროცესში, ასევე ყველა იმ ადამიანს, ვინც წვლილი შეიტანა idiomatic.js-ის შედგენაში, რამეთუ სწორედ იგი გახდა შთაგონების წყარო ამ სახელმძღვანელოს შესაქმნელად.