Unlimited Wordpress themes, plugins, graphics & courses! Unlimited asset downloads! From $16.50/m
Advertisement
  1. Web Design
  2. Documentation
Webdesign

8 Praktik Terbaik untuk Dokumentasi CSS yang Sempurna

Length:LongLanguages:

Indonesian (Bahasa Indonesia) translation by Hasannudin Amin (you can also view the original English article)

Di dunia CSS, dokumentasi kurang dimanfaatkan. Karena dokumentasi tidak terlihat oleh pengguna akhir, nilainya sering diabaikan oleh klien. Juga, jika ini adalah kode pendokumentasian pertama kali, sulit menentukan apa yang harus didokumentasikan dan cara melakukannya dengan sangat efektif.

Namun mendokumentasikan CSS dapat menawarkan banyak hal untuk proyek Anda: mulai dari mendorong praktik kode yang lebih baik untuk mengurangi onboard anggota tim baru. Pada artikel ini saya akan menjelaskan kelebihan mendokumentasikan CSS dan membagikan apa yang tim dan saya di Bitovi anggap sebagai praktik terbaik untuk membuat dokumentasi bekerja untuk Anda-bukan sebaliknya. Mari selami itu.

1. Setel Aturan Dasar

Sulit untuk mengikuti pelatihan dokumentasi jika tidak jelas bagi Anda dan tim Anda apa yang harus didokumentasikan atau bagaimana Anda menginginkannya bekerja. Jadi, langkah pertama adalah menyetujui konvensi mana yang akan Anda gunakan dan bagaimana Anda harus menerapkannya. Anda bisa melakukan ini dalam dokumen live sehingga semua orang di tim dapat berkontribusi. Dengan cara ini, saat pendekatan Anda berubah atau menjadi lebih komprehensif, Anda dapat selalu memperbaruinya. Google doc bersama, halaman wiki di repo kode Anda, atau (bahkan lebih baik) halaman di "panduan gaya hidup" Anda adalah tempat yang bagus untuk ini.

Sekarang mari kita lihat "aturan dasar" sebenarnya yang bisa Anda sertakan.

2. Jelaskan Struktur Dasar Kode Anda

Memahami bagaimana kode Anda diatur memungkinkan seseorang untuk langsung terjun ke aksi dari hari pertama. Cara sederhana untuk melakukan ini adalah membuat peta struktur file Anda di mana Anda dapat menjelaskan apa yang ada di dalamnya dan apa yang harus pergi ke mana. Saat melakukan ini, perhatikan secara khusus tempat-tempat di mana mungkin ada ambiguitas. Misalnya, menunjukkan bahwa file "buttons.css" berisi gaya untuk tombol tidak terlalu membantu, namun menunjukkan bahwa direktori "custom" adalah tempat gaya kustom untuk tema berada dapat menghemat waktu.

Inilah contohnya:

Sebagai aturan praktis, dokumentasikan tempat-tempat klarifikasi yang diperlukan. Tidak setiap direktori dan file memerlukan dokumentasi (seperti contoh "font" di atas cukup jelas). Letakkan diri Anda pada posisi seseorang yang baru mengenal proyek ini (atau ingat saat-saat di mana Anda adalah orang itu) dan berikan panduan yang Anda harapkan akan diberikan. Idenya adalah melakukan ini dengan cara yang tidak memakan waktu untuk Anda tetapi cukup membantu untuk menghindari pertanyaan berulang.

Elemen penting lainnya untuk ditunjukkan di sini adalah di mana gaya baru harus ditambahkan dan setiap langkah yang harus diikuti. Contoh di atas menunjukkan hal ini, namun mengingat sifat pewarisan CSS, dapat bermanfaat untuk menyatakannya secara rinci.

Misalnya, dalam proyek di mana kami menggunakan Bootstrap sebagai kerangka dasar, kami biasanya memiliki tiga tempat di mana peraturan baru harus diterapkan, bergantung pada apa yang sedang coba dicapai pengembang. Jadi kami menambahkan panduan untuk dokumentasi yang terdiri dari tiga skenario:

Skenario #1

Jika Anda ingin menimpa gaya yang didefinisikan oleh Bootstrap, maka:

  1. Cari tahu di mana stylesheet dari kerangka bootstrap aturan didefinisikan.
  2. Buka "src/styles/bootstrap-custom".
  3. Carilah stylesheet yang sama.
  4. Jika tidak ada, buat yang baru di direktori itu, dengan nama yang sama.
  5. Tambahkan dan tunjukkan sesuatu yang penting.
  6. Terakhir, impor stylesheet baru di "src/style/style.less".

Skenario #2

Jika Anda ingin menambahkan definisi gaya baru yang tidak menimpa Bootstrap dan itu harus tersedia di manapun dalam aplikasi, maka:

  1. Buka “src/styles/custom”.
  2. Temukan stylesheet di mana gaya baru bisa ditambahkan (pikirkan: apakah ini gaya untuk menentukan sebuah tombol, atau apakah itu gaya yang bisa digunakan kembali seperti mixin?) Dan letakkan di tempat yang paling masuk akal.
  3. Jika tidak ada stylesheet yang masuk akal untuk menempatkan gaya baru ini, maka buat yang baru.
  4. Namai itu mengikuti konvensi penamaan kami.
  5. Tambahkan gaya baru Anda dan tunjukkan sesuatu yang penting.
  6. Terakhir, impor stylesheet baru di "src/style/style.less".

Skenario #3

Jika Anda ingin menambahkan definisi gaya baru untuk komponen (ini berarti hanya tersedia untuk komponen itu, dimanapun komponennya digunakan dalam aplikasi), maka:

  1. Buka “src/components”.
  2. Temukan komponen yang ingin Anda gaya.
  3. Temukan stylesheet untuk komponen, di dalam direktori komponen.
  4. Terakhir, tambahkan gaya baru dan tunjukkan sesuatu yang penting.

Panduan ini:

  • Dilayani agar gaya kita tetap teratur.
  • Terus gaya bekerja sesuai dengan warisan yang telah kami bangun karena overwrites dilakukan di tempat yang tepat.
  • Hindari pengembang menulis aturan overcomplicated.
  • Mencegah gaya bocor ke elemen yang tidak dimaksudkan.

3. Tetapkan Standar Coding Anda

Standar pengkodean atau panduan gaya CSS Anda mengacu pada cara tim Anda sepakat untuk menulis CSS. Ini termasuk praktik terbaik dalam menulis kode, seperti format, penamaan, dan konvensi sintaksis. Banyak perusahaan telah membagikan cara mereka melakukannya (artikel dari CSS-Tricks ini memiliki kompilasi hebat: Panduan Gaya CSS). Berikut adalah beberapa cara yang saya anggap berguna untuk berbagi jenis informasi ini:

Larangan vs Daftar yang Harus Dilakukan

Gunakan format ini untuk menunjukkan hal-hal yang ingin Anda hindari, sambil memberikan alternatif yang layak. Ini menghilangkan ambiguitas dan mendorong orang untuk melakukan hal yang spesifik. Sebagai contoh:

Jangan
Lakukan
Jangan gunakan tab untuk indentasi.
Gunakan (4) ruang untuk indentasi.
Jangan gunakan under_scores atau "camelCase" untuk memberi nama kelas atau ID.
Gunakan tanda hubung untuk memisahkan kata-kata.
Jangan gunakan nama Class dan ID untuk mencerminkan struktur markup yang mendasarinya. .container-span dan .small-header-div adalah nama buruk.

Apakah berpikir tentang CSS dalam hal objek dan menggunakan kata benda sederhana sebagai nama. .global-alert dan .badge adalah nama yang bagus.

Jangan gunakan ID dan pemilih yang terlalu spesifik untuk bergaya. Gunakan ini hanya bila benar-benar diperlukan (misalnya kontrol bentuk atau jangkar halaman).
Gunakan kelas untuk memfasilitasi kegunaan dan mengurangi konflik spesifisitas pemilih CSS.

Daftar Praktik Terbaik

Ringkaskan pedoman Anda ke dalam praktik terbaik dan sertakan contoh. Ini akan membuat masing-masing lebih mudah dibaca dan dimengerti. Sebagai contoh:

Praktik terbaik Contoh
Tuliskan beberapa penyeleksi pada baris yang terpisah. .btn,
.btn-link {
}
Sertakan satu spasi antara pemilih dan penjepit pembuka. .selector {
}
Gunakan shorthand untuk nilai hex bila memungkinkan. #fff vs #ffffff
Tuliskan nilai hex dalam huruf kecil. #3d3d3d vs #3D3D3D
Lampirkan URL dalam tanda kutip tunggal. Umumnya, tanda petik tunggal lebih disukai daripada tanda petik ganda, karena lebih mudah mengetik. url ('/image.png') vs url ("/image.png")
Jangan gunakan unit untuk nilai nol (0), kecuali untuk sudut (deg) dan waktu (s atau ms).
margin-right: 0; vs margin-right: 0px;

Cara seorang pengembang menulis kode bisa sangat berbeda dari yang lain. Inilah sebabnya mengapa penting bagi tim Anda untuk menetapkan standar pengkodean. Ini memastikan kode tersebut konsisten di seluruh proyek, yang mempermudah membaca, menulis dan meninjau ulang. Tapi pastikan bahwa apa pun yang Anda sertakan dalam standar pengkodean Anda adalah praktik yang telah disetujui oleh tim Anda.

Saya mengerjakan sebuah proyek di mana kami memasukkan ini ke dalam panduan gaya hidup kami. Sebagai bagian dari kode, kami berkomitmen dan mendorong praktik terbaik ini ke repo. Kemudian untuk memastikan semua orang ada di kapal, semua orang di tim harus menyetujui permintaan tarik sebelum kami bisa menggabungkannya. Ini menjamin bahwa setiap orang harus meluangkan waktu untuk meninjau dan mendiskusikannya.

4. Hindari Stylesheets Panjang

Saat Anda memecah gaya menjadi stylesheet yang lebih kecil dan lebih terfokus, lebih mudah mendokumentasikannya. Anda juga bisa menghemat waktu dengan tidak harus mendokumentasikan apa yang menjadi cukup jelas.

Sebagai contoh, daripada memiliki satu 800 stylesheet garis dengan semua variabel yang dapat Anda gunakan dalam sebuah tema, Anda dapat memiliki file untuk masing-masing jenis variabel. Ini akan menghemat waktu dengan tidak harus menggulir ke atas dan ke bawah dalam file mencoba menemukan sesuatu! Pikirkan juga waktu yang dapat Anda hemat dengan tidak harus memperbarui indeks setiap kali Anda menambahkan atau mengganti nama bagian baru.

Dalam file yang panjang, sebuah indeks panjang ...

Memecah file, tidak ada indeks yang diperlukan:

Contoh lain yang perlu diperhatikan saat mengerjakan aplikasi besar adalah alur kerja modlet. Ini menjelaskan mengapa bekerja dengan file yang lebih kecil yang diatur oleh komponen memungkinkan pengujian dan perakitannya di aplikasi Anda dengan lebih mudah.

5. Dokumen CSS dengan Style Guide in Mind

Sebagian besar mendokumentasikan CSS benar ada hubungannya dengan penulisan CSS yang bagus dan sebaliknya. Ini berarti bahwa walaupun status kode dasar CSS Anda mungkin bukan yang terbaik, menerapkan peraturan dokumentasi dapat membuat Anda beralih ke sistem yang lebih baik.

Di sinilah mendokumentasikan CSS dengan panduan gaya dalam pikiran muncul pada tempatnya. Ide dibalik itu adalah bahwa panduan gaya dapat membantu Anda menentukan struktur yang baik untuk CSS Anda karena untuk membuatnya Anda perlu membedakan antara:

  • gaya dasar yang menentukan tampilan dan nuansa aplikasi Anda (termasuk kerangka CSS yang Anda gunakan)
  • penyesuaian yang dilakukan pada komponen tertentu, dan
  • penyesuaian yang dilakukan ke halaman tertentu.

Sebagian besar CSS Anda harus terdiri dari gaya dasar, karena tersedia di manapun dalam aplikasi dan mempengaruhi semua elemen dalam keadaan default mereka. Gaya khusus harus dilakukan saat Anda menambahkan komponen dengan tampilan dan perilaku tertentu, atau dalam kasus di mana tata letak elemen atau komponen dalam halaman memerlukannya.

Cara yang bagus untuk mengetahui bagaimana penyiapan spesifik ini dapat bekerja di aplikasi Anda adalah dengan membuat sitemap panduan gaya. Begitu Anda tahu bagaimana panduan gaya terlihat seperti di aplikasi Anda, Anda dapat mendokumentasikan elemen dengan pemikiran itu. Misalnya, jika Anda telah menentukan panduan gaya bagaimana tampilan tombol dan navigasi, maka jelaslah di mana Anda harus menambahkan gaya dan dokumentasi baru untuk mereka (di "buttons.css" dan "navs.css"). Tapi bagaimana dengan navigasi yang terbuat dari tombol?

Memiliki panduan gaya dapat membantu Anda membuat keputusan ini, karena Anda dapat membandingkan bagaimana tampilan tombol dan navigasi, dari tampilan dan perspektif markup. Mari kita lihat contoh ini:

Dalam kasus ini, ada dua lokasi yang mungkin untuk CSS yang akan menentukan navigasi yang dibuat dari tombol:

  1. Jika markup mengikuti struktur navigasi lainnya, gunakan daftar tautan, atau <nav> dengan tautan yang terlihat seperti tombol, lalu tambahkan gaya nav ke "navs.css".
  2. Jika markup yang akan Anda gunakan adalah <button>, tambahkan style ke "buttons.css". Anda bahkan bisa menambahkannya sebagai stylesheet terpisah (seperti "buttons-group.css"). Dalam hal ini, istilah "navigasi" tidak akan sesuai lagi karena tombol HTML kurang dapat diakses sebagai item navigasi.

6. Perincian Stylesheets Anda Ke Bagian

Setelah Anda memecah stylesheet Anda menjadi file yang lebih mudah dikelola, Anda dapat melanjutkan latihan ini dengan memecah setiap gaya menjadi bagian individual.

Untuk mulai dengan, masing-masing stylesheet setidaknya harus menyertakan judul dan (bila berguna) deskripsi singkat. Judulnya bisa sesederhana nama file, dikapitalisasi untuk terlihat lebih seperti judul (misal: "Buttons" untuk stylesheet "buttons.css"), atau bisa juga sama dengan nama file, seperti ini:

Saya menemukan menggunakan nama file sangat berguna saat melakukan debug pada kode di browser, dan kebanyakan saat file tersebut telah dikompilasi dengan file lain, karena saya bisa mendapatkan referensi ke file tempat gaya tinggal.

Juga, perhatikan bahwa gaya komentar yang saya gunakan terbuka dengan / ** vs. hanya / *. Ini adalah konvensi yang digunakan di JSDoc untuk mengurai komentar yang harus disertakan dalam dokumentasi yang dibuat secara otomatis. Sebaiknya gunakan gaya ini, karena banyak generator pembimbing gaya hidup menggunakan format JSDoc, jadi saat Anda siap menggunakan generator, kode Anda hanya perlu sedikit kerja tambahan.

Bagaimanapun, Anda dapat menggunakan gaya lain untuk menunjukkan bagian seperti:

Sampai batas tertentu, ini tergantung pada apa yang tim Anda setujui adalah cara terbaik untuk membuat bagian menonjol. Satu-satunya persyaratan adalah menggunakan /* di awal dan */ di akhir. Yang benar-benar penting adalah pendekatan mana pun yang Anda gunakan, Anda mematuhinya dan menggunakannya di seluruh kode CSS Anda secara konsisten.

Jika menurut Anda deskripsi mungkin berguna dalam stylesheet tertentu, tambahkan itu sebagai bagian dari komentar pertama ini. Sebagai contoh:

Melakukan hal ini akan memperkuat gagasan untuk menjadi bagian. Juga, cobalah untuk memecah deskripsi menjadi beberapa baris (Harry Roberts merekomendasikan hingga 80 karakter) sehingga lebih mudah dibaca saat memiliki beberapa file yang terbuka atau saat membacanya di Github.

Setelah menambahkan judul dan deskripsi, Anda bisa melangkah lebih jauh dengan memecah gaya di dalam stylesheet menjadi beberapa bagian. Untuk melakukan ini, pikirkan bagaimana menjelaskan isi dari stylesheet secara logis. Misalnya, stylesheet "buttons.css" biasanya akan memiliki bagian di mana gaya default tombol ditentukan hanya dengan menerapkan kelas .btn. Kemudian akan ada gaya tambahan yang menentukan warna, ukuran, dan konfigurasi yang berbeda yang dapat diterapkan bersamaan untuk menyesuaikan tampilan dan tingkah lakunya lebih lanjut. Membuat bagian untuk masing-masing gaya akan memudahkan untuk memahami dan menemukan di mana kelas baru atau penimpaan akan muncul. Membuat bagian untuk masing-masing gaya akan memudahkan untuk memahami dan menemukan di mana kelas baru atau penimpaan akan muncul.

Mari kita lihat contoh komparatif ini. Pertama, blok kode LESS tanpa bagian:

Dan blok kode yang sama dengan bagian:

7. Indeks Isi Stylesheets Anda

Ini adalah cara yang bagus untuk memberikan gambaran tentang apa yang ada dalam stylesheet dan sebuah keharusan dalam proyek-proyek di mana, untuk alasan apapun, stylesheet lama ada di sana untuk tinggal (bukan penggemar proyek-proyek itu, tapi itu memang terjadi!).

Indeks stylesheet biasanya terlihat seperti ini:

Dan walaupun saya suka betapa rapi dan bermanfaatnya, saya harus mengakui bahwa mereka dapat dengan mudah dilupakan, dan karena itu ketinggalan jaman. Mereka juga lelah untuk memperbarui saat mereka panjang dan Anda menggunakan angka (jadi hindarilah!)

Cara alternatif untuk menggunakan indeks adalah dengan membiarkan generator panduan gaya melakukan pekerjaan untuk Anda dengan melihat stylesheet Anda, menemukan bagian yang telah Anda tentukan dan menghasilkan sebuah indeks untuk Anda. Saya akan memperluas lebih banyak topik ini di akhir artikel ini.

8. Temukan Tempat Documenting yang Cantik

Di sinilah rahasia kebohongan mendokumentasikan. Sangat mudah untuk terbawa dan mengalami kegilaan dokumentasi sekali, untuk kemudian melupakannya dan berakhir dengan hanya sebagian basis kode Anda yang terdokumentasi dan sisanya tidak berdokumen. Seperti segala sesuatu dalam hidup, rahasianya menemukan keseimbangan. Dokumentasikan daerah-daerah di mana perhatian diperlukan karena ada dependensi tak terduga, sumber tambahan, atau catatan penting yang ada dalam pikiran. Artinya, tidak semua kode harus didokumentasikan, namun sangat berguna untuk memecahnya menjadi potongan dan menjelaskan apa itu potongan bila diperlukan. Dengan cara ini, dokumentasi menjadi alat yang berguna yang merupakan bagian dari alur kerja Anda dan bukan renungan yang harus Anda hindari. Tapi bagaimana Anda melakukannya? Inilah contohnya:

Katakanlah Anda akan menerapkan markup dan CSS untuk komponen kartu berikut:

card base design

Melihat disain Anda bisa mengenali pola gaya berikut ini:

  • Card base design
  • Cards grid
  • Cards list
  • Card dark version

Anda kemudian dapat memecah implementasi CSS dengan pola-pola itu dalam pikiran dan menggunakan dokumentasi untuk membimbing Anda. Untuk mulai dengan, stylesheet "cards.css" Anda dapat menyertakan intro sederhana sebagai berikut:

Anda dapat menyertakan informasi yang lebih berguna dalam pendahuluan, namun karena Anda baru memulai sesuatu yang sederhana, dapat membantu meletakkan kerangka dokumentasi.

Lalu, mari tambahkan bagian di mana Anda akan mengerjakan gaya Anda:

Dengan mengingat bagian ini, Anda dapat memvisualisasikan bagaimana kode tersebut harus terstruktur. Anda tahu bahwa Anda harus membuat definisi dasar kartu secara fleksibel dan mandiri sehingga Anda dapat dengan mudah membuat kartu bekerja dalam daftar grid, daftar atau versi gelap.

Kemudian saat Anda menulis kode, Anda bisa lebih spesifik dengan komentar Anda:

Saya menganggap ini sebagai tingkat dasar dokumentasi yang harus Anda sertakan karena ini berfungsi sebagai panduan untuk menyusun kode dan dengan cepat menginformasikan bagaimana segala sesuatunya diatur untuk orang berikutnya yang mengerjakannya.

Tingkat berikutnya adalah menambahkan komentar yang spesifik untuk sebuah peraturan, dan itu bisa digunakan untuk menjelaskan peraturan yang sedang dilakukan ini karena tidak jelas sekilas. Sebagai contoh:

Keindahan dari pendekatan ini adalah dokumentasi ada untuk mendukung dan menginformasikan implementasinya saat Anda pergi, versus sesuatu yang ditambahkan di lain waktu.

Berikut adalah beberapa contoh kerangka Bootstrap yang ditampilkan saat komentar berguna dan bila layak membahas lebih detail.

Contoh #1

Komentar ini menjelaskan mengapa gaya ini ada dan apa yang mereka lakukan. Ini juga singkat dan langsung, mengkomunikasikan gagasan itu dalam bahasa biasa.

Contoh #2

Ini adalah contoh bagus dokumentasi yang berjalan lebih dalam, menjelaskan logika di balik keputusan implementasi dan menyediakan tautan ke informasi tambahan.

Mengambil Langkah Selanjutnya

Dengan praktik terbaik ini, langkah selanjutnya adalah menggabungkan living style guide sebagai bagian dari dokumentasi Anda. Living style guide adalah dokumen hidup yang menunjukkan komentar yang Anda sertakan dalam kode Anda yang terstruktur seperti situs web, sehingga Anda dapat menavigasi dokumentasi secara terpisah dari kode sumber.

Apa yang membuat living style guide sangat penting adalah dokumentasi sebenarnya sesuai dengan kode dan dapat dengan mudah diperbarui seiring perubahan kode Anda, yang memungkinkannya tetap sinkron dan relevan. Keuntungan tambahan adalah Anda dapat membuat dokumentasi ini tersedia bagi orang lain di tim Anda yang mungkin tidak berinteraksi langsung dengan kode (seperti perancang, manajer produk, atau insinyur QA). Anggota tim ini juga akan merasa terbantu untuk mengetahui bagaimana UI terbentuk.

Dalam panduan gaya hidup, Anda dapat menyertakan demonstrasi interaktif kode Anda dan Anda selanjutnya dapat mengatur dokumentasi Anda secara independen dari struktur kode.

Kesimpulan

Mendokumentasikan CSS dimulai dengan aturan yang jelas dan basis kode yang terstruktur dengan baik. Bila dilakukan sebagai bagian dari alur kerja Anda, ini juga dapat berfungsi sebagai panduan untuk menyusun kode Anda dan tetap mengaturnya saat ia tumbuh. Ini memiliki keuntungan tambahan untuk memastikan di mana hal-hal dan di mana kode baru harus ditambahkan, mengurangi onboard anggota baru saat pengembangan pelacakan cepat.

Resource Bermanfaat

Pengingat: 8 Praktik Terbaik

  1. Tetapkan aturan dasar
  2. Temukan titik dokumentasi yang indah
  3. Indeks isi stylesheet Anda
  4. Perincian stylesheet Anda menjadi beberapa bagian
  5. Dokumen CSS dengan style guide in mind
  6. Hindari stylesheet yang panjang
  7. Tetapkan standar pengkodean Anda
  8. Jelaskan struktur basis kode Anda
Advertisement
Advertisement
Advertisement
Advertisement
Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.