Seberapa baik komen HTML dan CSS anda?

Salah satu perkara yang biasanya anda pelajari apabila anda mula belajar tentang asas HTML atau CSS adalah cara menulis komen dalam kod anda. Walau bagaimanapun, banyak pemaju web masih tidak menggunakan komen untuk kelebihan mereka. Kami boleh menggunakan komen secara meluas dalam HTML dan CSS, tetapi apabila ditulis dengan betul, dan dengan niat, mereka benar -benar dapat memperbaiki aliran kerja kami.

Apabila anda mula bekerja di sebuah syarikat baru, melihat manual atau banyak halaman dokumentasi boleh menakutkan. Setiap syarikat berbeza - bermakna bahawa kod, jumlah kod warisan, pembangunan kerangka, dan jumlah kod modular boleh berbeza.

Kami sering diberitahu bahawa "kod yang baik tidak memerlukan komen", tetapi adakah anda pernah mendapati diri anda berada di dalam lingkaran, hilang sepenuhnya, dan mencari dokumentasi kerana

kekurangan komen?

Takeaways Key

Mengulas dalam HTML dan CSS bukan sahaja memudahkan pemahaman dan mengekalkan konsistensi tetapi juga mempercepatkan proses pembangunan dan bantuan dalam kerjasama yang cekap. Ia sangat membantu dalam tetapan pasukan di mana pelbagai pemaju sedang mengusahakan projek yang sama.
Semasa mengulas bermanfaat, elakkan berlebihan. Mengulas setiap blok kod boleh berlebihan dan memakan masa. Komen hendaklah ringkas dan hanya digunakan di mana kod mungkin tidak sepenuhnya jelas.
Komen boleh digunakan untuk menerangkan tujuan elemen pseudo, blok kod bersarang, mengapa! Penting mungkin diperlukan, atau mengapa blok kod dikomentari dan bukannya dihapuskan.
• bentuk dokumentasi lain, seperti mesej komit dan permintaan tarik, juga harus dianggap sebagai sebahagian daripada proses pembangunan. Mereka menyediakan konteks dan kejelasan, membuat kolaborasi dan kajian semula kod lebih cekap.
dua fakta mengenai komen kod

Komen diabaikan oleh penyemak imbas.

1. Komen dilucutkan semasa minifikasi.
Berdasarkan kedua -dua fakta ini, kita tahu bahawa komen tidak benar -benar dimaksudkan untuk mesin - mereka dimaksudkan

untuk manusia membaca

. mengapa kod mengulas penting

semasa anda bebas dan mengusahakan projek solo, atau ketika anda adalah satu -satunya pemaju yang akan melihat kod anda, mudah untuk melakukannya dengan cara anda sendiri dan membuat komen seperti yang anda lihat patut, atau mungkin Tinggalkan tiada komen sama sekali. Tetapi banyak masa, pemaju mengatakan bahawa mereka melihat kembali kod mereka sendiri dan tertanya -tanya, "Apa yang saya fikirkan?" atau berjuang untuk memahami kod yang mereka tulis.

Komen boleh membantu mengekalkan konsistensi. Sekiranya anda mempunyai komen yang konsisten dan ditulis dengan baik untuk apa yang anda bina maka anda lebih cenderung untuk membina perkara dengan cara yang sama setiap kali.

Komen memudahkan pemahaman. Ini sangat penting dalam satu pasukan di mana kadang -kadang seseorang tidak melakukan semua kerja. Anda mungkin menulis komen untuk membantu diri anda memikirkan beberapa logik, dan walaupun anda tidak menyimpan semua komen anda pada akhir projek, ia dapat membantu anda memahami dengan lebih baik bagaimana anda sampai ke penyelesaian. Ia dapat membantu anda memperbaiki penyelesaian itu dengan lebih mudah di kemudian hari.

mengulas juga boleh membantu dengan hotfixes atau pembetulan cepat. Komen sebenarnya boleh membantu dalam tiga cara di sini. Mereka dapat membantu pemaju memahami kod jika mereka perlu membuat pembetulan cepat (terutama pemaju di luar pasukan depan yang mungkin membantu), ia dapat membantu dengan menandakan di mana perbaikan ini diperlukan, dan dapat menunjukkan di mana pembaikan cepat telah digunakan dan perlu dikeluarkan pada satu ketika.

Komen membantu mempercepat proses pembangunan. Anda boleh mempunyai pemahaman yang lebih jelas tentang apa yang anda buat, menukar atau mengeluarkan jika anda memasukkan komen yang relevan.

Komen memudahkan kerjasama yang lebih cekap. Sekiranya anda mengetahui selok -belok projek atau kod kod, anda lebih cenderung untuk mendapatkan bit dan kepingan yang lebih cepat, dengan itu meningkatkan aliran kerja.

Komen membantu banyak orang. Mereka bukan sahaja membantu diri sendiri, tetapi mereka dapat membantu orang lain dalam pasukan anda. Sudahlah hari -hari yang kita lihat komen seperti tidak mencuri kod saya dalam kod sumber orang. Walaupun kami sangat melindungi kod kami, tidak mahu berkongsi 'rahsia' kami, kami kini hidup di dunia di mana orang berkongsi kod, bekerja pada projek bersama dan bekerjasama. Kami tidak malu untuk mengkredit orang seperti Harry Roberts, Chris Coyier atau Jonathan Snook ketika datang ke projek web. Dengan pergeseran ini, kita juga harus mengambil perhatian terhadap amalan komen kami - dan membantu rakan -rakan kami.

Beberapa perkara yang harus dielakkan ketika datang ke komen

Elakkan mengulas semuanya

Ia mungkin menggoda untuk masuk ke dalam kebiasaan mengulas setiap blok kod, tetapi ini boleh menjadi lebih berlebihan daripada berguna atau berguna. Mengulas hanya perlu dilakukan di mana sesuatu mungkin tidak jelas sepenuhnya. Jika anda menganggap semantik semasa menamakan kelas anda, kod anda mungkin sudah mudah difahami.

Ini juga mungkin di mana konsep "kod yang baik tidak memerlukan komen". Komen tidak boleh dielakkan sepenuhnya, tetapi hanya digunakan di mana perlu.

jangan terlalu verbose

Saya secara peribadi bersalah menulis beberapa komen yang agak panjang di CSS saya, kerana saya suka menjelaskan dan mendokumentasikan perkara. Walau bagaimanapun, anda tidak boleh menulis novel - komen panjang adalah seperti kesakitan untuk dibaca kerana mereka boleh menulis. Jika anda boleh ringkas, berbuat demikian. Kadang -kadang, ketika menamakan kelas CSS, nasihat berikut diberikan:

membuat nama kelas seketika mungkin tetapi selagi perlu.

sama berlaku untuk komen. Adalah baik untuk membaca apa -apa komen yang anda tulis untuk memastikan anda memahami sendiri. Bayangkan anda adalah seseorang yang baru dalam kod dan anda membaca komen sebagai panduan.

jangan menghabiskan terlalu banyak masa menulis komen

Saya pernah melihat fail dalam projek yang saya sedang kerjakan yang mempunyai garis di atas bacaan:

<span>// Update this with how many hours you have spent on this file:
</span><span>// TIME_WASTED = 438;</span>

Anda tidak perlu menghabiskan banyak masa menulis komen. Beberapa perkataan biasanya cukup. Sekiranya anda menghabiskan terlalu banyak masa untuk mengulas kod anda untuk memastikan orang lain akan memahaminya, pertimbangkan bahawa bahagian kod anda sebenarnya memerlukan refactoring.

beberapa contoh bila menggunakan komen

untuk menerangkan tujuan elemen pseudo

Contoh ini menunjukkan elemen pseudo dengan nilai kandungan yang diisi.

<span><span>.post__comment-container::after</span> {
</span>  <span>background-color: #f9f9f9;
</span>  <span>border: 1px solid #dedede;
</span>  <span>border-radius: 0.25em;
</span>  <span>color: #888;
</span>  <span>content: 'Post author';
</span>  <span>display: inline-block;
</span>  <span>font-size: 0.7rem;
</span>  <span>margin-left: 0.5rem;
</span>  <span>padding: 0.2rem 0.45rem;
</span>  <span>vertical-align: middle;
</span><span>}</span>

Ia mungkin tidak segera jelas apa unsur pseudo, terutamanya jika harta kandungan dipaparkan sebagai kandungan: ''. Dengan komen ringkas di atas blok kod, kita dapat memperbaiki ini.

/* Post author label for comment */

<span><span>.post__comment-container::after</span> {
</span>  <span>background-color: #f9f9f9;
</span>  <span>border: 1px solid #dedede;
</span>  <span>border-radius: 0.25em;
</span>  <span>color: #888;
</span>  <span>content: 'Post author';
</span>  <span>display: inline-block;
</span>  <span>font-size: 0.7rem;
</span>  <span>margin-left: 0.5rem;
</span>  <span>padding: 0.2rem 0.45rem;
</span>  <span>vertical-align: middle;
</span><span>}</span>

untuk menerangkan blok kod bersarang

Walaupun ia pasti membantu menggunakan kelas semantik sebanyak mungkin, mungkin tidak selalu jelas mengapa blok CSS akan bersarang ketika menggunakan preprocessor:

<span><span>.c-segment-controls.is-active</span> {
</span>  <span><span>.c-segment-controls__panel</span> {
</span>    <span>background-color: #fafafa;
</span>    <span>border: 1px solid #aaa;
</span>    <span>opacity: 1;
</span>    <span>transition: opacity 0.5s ease;
</span>  <span>}
</span><span>}</span>

Enam perkataan sudah cukup untuk komen untuk menunjukkan apa yang dilakukan oleh kod ini, membolehkan seseorang dapat melangkau dokumen dan sama ada berhenti atau melangkau ke hadapan.

<span><span>.c-segment-controls.is-active</span> {
</span>
  <span>/* Active state for segment controls panel */
</span>
  <span><span>.c-segment-controls__panel</span> {
</span>    <span>background-color: #fafafa;
</span>    <span>border: 1px solid #aaa;
</span>    <span>opacity: 1;
</span>    <span>transition: opacity 0.5s ease;
</span>  <span>}
</span><span>}</span>

untuk menjelaskan mengapa! Penting mungkin diperlukan

kita sering melihat! Penting dan anggap kita melihat kod warisan atau hack kotor:

<span><span>.c-accordion-container.ng-hide</span> {
</span>  <span>display: block !important;
</span><span>}</span>

Setelah pemeriksaan yang lebih dekat, kami hanya mengatasi tingkah laku lalai kerangka.

/**
 * Overriding some rogue Angular code.
 * Forces `display: block` so that the element can be animated.
 */

<span><span>.c-accordion-container.ng-hide</span> {
</span>  <span>display: block !important;
</span><span>}</span>

untuk menjelaskan mengapa blok kod telah dikomentari dan bukannya hanya dipadam

Jika kita melihat blok kod di bawah, kita mungkin menganggap pemadaman ini baik -baik saja. Tentunya ia tidak digunakan di mana -mana sahaja? Sekiranya saya memadamkannya, ia akan menjadi kawalan versi apabila kita memerlukannya kemudian, kan?

<span>// .c-segmented-button__icon {
</span><span>//   transform: translateY(calc((40px - 100%)/2));
</span><span>// }</span>

Tetapi jika kita memadamkannya, seseorang mungkin tidak tahu ia wujud di tempat pertama. Mungkin idea yang baik untuk meninggalkan ini di sini:

/**
 * Calculation for vertical alignment.
 * Can be used when IE11 support is dropped.
 */

<span>// .c-segmented-button__icon {
</span><span>//   transform: translateY(calc((40px - 100%)/2));
</span><span>// }</span>

jenis dokumentasi lain

Dokumentasi sangat penting dan bukan hanya terhad kepada komen dalam kod. Apabila kita selesai dengan tugas, kita mungkin dapat dikaji semula rakan sebaya.

Commit Mesej

Apabila menggunakan kawalan versi (contohnya, git), kita boleh mengambil apa yang kita tahu tentang menulis komen berguna dalam kod dan memohon ini kepada mesej komit kami.

Mesej komit yang buruk tidak memberi banyak konteks. Mereka kelihatan ceroboh, dan sukar difahami. Mereka tidak berguna untuk nota pelepasan. Ia boleh menjadi sukar bagi pemaju untuk mengetahui apa yang telah berubah. Mesej komit yang buruk sering kelihatan seperti ini.

commit 2faa2
    wip
commit 591ad
    tried to fix some weird box
commit af830
    made the triangle thing work
commit bd02a
    refactor
commit bed4b
    hotfix navigation
commit 22fe0
    oops

Contoh yang lebih baik akan menerangkan, menggunakan kata kerja, tugas yang diselesaikan dalam komit. Tugas kecil yang berbeza akan tersebar di pelbagai komitmen.

<span>// Update this with how many hours you have spent on this file:
</span><span>// TIME_WASTED = 438;</span>

Karma mempunyai panduan yang cukup mudah untuk menulis komitmen yang lebih baik, sedangkan Chris Beam mempunyai panduan yang sangat mendalam. David DeMaree juga menulis artikel bertajuk 'The Art of the Commit'. Mesej komit pasti patut mendapat perhatian.

Tarik permintaan

Selepas menulis beberapa komitmen, anda biasanya membuat permintaan tarik untuk salah satu rakan anda untuk melihat. Saya telah melihat terlalu banyak permintaan tarik yang mempunyai sedikit terperinci atau tidak ada penerangan sama sekali:

Apabila anda menulis permintaan tarik, anda biasanya mengharapkan seseorang mengkaji semula kod anda. Untuk membantu orang itu dan membantu meringankan proses, anda harus menulis perihalan tentang permintaan tarik. Ini adalah senarai semak mental saya:

• nombor tiket, nombor tugas atau nombor isu
• sebutkan tugas dalam beberapa perkataan
• sebutkan jenis fail yang saya ubah
• Jika ia adalah pepijat, nyatakan bagaimana pepijat seperti sebelum dan selepas perubahan
• Huraikan tingkah laku yang diharapkan selepas perubahan (sekiranya ia sama?)
• Senaraikan sebarang langkah yang perlu diambil untuk memeriksa perubahan, sama ada dalam penyemak imbas atau dalam kod
• Perhatikan apa sahaja yang harus diabaikan, contohnya pepijat yang ditangani di cawangan lain
• termasuk tangkapan skrin antara muka yang diperlukan

Contoh ini agak mudah, dan anda pasti tidak perlu memasukkan segala -galanya dalam senarai di atas jika tidak perlu:

Kesimpulan

Walaupun saya telah menyediakan beberapa contoh di mana untuk memasukkan komen dan beberapa cadangan tentang apa yang harus dielakkan, tidak ada peraturan yang sukar dan cepat tentang cara memformat komen dalam kod anda. Bilangan baris, kata -kata, atau maklumat apa yang hendak disertakan adalah terpulang kepada anda, atau boleh diputuskan antara anda dan rakan -rakan anda. Selagi anda menyimpan format yang konsisten, ia akan memastikan perkara -perkara yang kemas dan menggalakkan orang lain yang bekerja dengan kod untuk melakukan perkara yang sama.

Terdapat banyak faedah yang berkaitan dengan membuat komen sebahagian daripada proses pembangunan anda. Adalah baik untuk masuk ke dalam kebiasaan termasuk mereka di mana anda melihat patut, terutamanya apabila anda mempunyai banyak orang yang bekerja pada fail yang sama. Ia juga membantu mempertimbangkan bentuk dokumentasi lain yang tertanam dalam aliran kerja - seperti mesej komit dan permintaan tarik - dan bukan sekadar dokumen garis panduan luaran.

Adakah anda mengikuti mana -mana garis panduan untuk mengulas kod? Atau mungkin anda bekerja di sebuah syarikat yang mempunyai dokumentasi jenis yang berbeza tetapi berkesan?

Soalan Lazim (Soalan Lazim) Mengenai Komen HTML dan CSS

Apakah kepentingan menggunakan komen dalam komen HTML dan CSS? Pertama, mereka membantu memahami struktur dan fungsi kod, terutamanya ketika bekerja dalam pasukan atau meninjau semula kod anda setelah lama. Kedua, mereka boleh digunakan untuk mematikan sementara bahagian tertentu kod anda semasa debugging. Akhir sekali, komen boleh memberikan maklumat atau arahan berguna kepada sesiapa yang membaca kod.

. Sebagai contoh, . Dalam CSS, komen dibuat dengan membungkus teks antara /* dan

/. Sebagai contoh, /

ini adalah komen * /.

Bolehkah komen mempengaruhi prestasi laman web saya?

Tidak, komen tidak menjejaskan prestasi laman web anda. Mereka diabaikan oleh penyemak imbas semasa proses rendering. Walau bagaimanapun, komen yang berlebihan dapat meningkatkan saiz fail, yang mungkin sedikit mempengaruhi masa pemuatan. Menjadi ringkas namun deskriptif, mengulas mengenai bahagian kod kompleks atau penting, dan mengelakkan komen yang tidak perlu atau berlebihan. Ia juga merupakan amalan yang baik untuk kerap mengemas kini komen anda untuk mencerminkan perubahan dalam kod anda. Bolehkah saya menggunakan komen untuk menyembunyikan kod dari penyemak imbas tertentu? penyemak imbas tertentu. Teknik ini, yang dikenali sebagai komen bersyarat, sering digunakan untuk memberikan gaya atau skrip yang berbeza untuk versi Internet Explorer yang berlainan. dengan sementara melumpuhkan bahagian tertentu kod anda. Ini dapat membantu anda mengasingkan dan mengenal pasti bahagian -bahagian yang bermasalah dari kod anda. Percubaan untuk berbuat demikian boleh menyebabkan hasil yang tidak dijangka. Di CSS, anda boleh mengulas sarang, tetapi secara amnya tidak disyorkan kerana ia boleh membuat kod anda lebih sukar untuk dibaca dan difahami. > Komen line tunggal digunakan untuk penjelasan ringkas atau anotasi, manakala komen berbilang baris digunakan untuk penerangan atau blok kod yang lebih lama. Di HTML, semua komen secara teknikalnya berbilang talian. Di CSS, komen satu baris bermula dengan // dan berakhir pada akhir baris, manakala komen multi-line bermula dengan / * dan berakhir dengan * /.

Bolehkah saya menggunakan aksara khas dalam komen saya?

Ya, anda boleh menggunakan aksara khas dalam komen anda. Walau bagaimanapun, dalam HTML, anda harus mengelakkan menggunakan aksara " -" dalam komen anda kerana mereka boleh menyebabkan komen berakhir dengan awal.

Bagaimana saya boleh menggunakan komen untuk meningkatkan kebolehbacaan kod saya?

Komen boleh meningkatkan kebolehbacaan kod anda dengan memberikan penjelasan dan anotasi. Mereka juga boleh digunakan untuk memisahkan bahagian yang berlainan kod anda, menjadikannya lebih mudah untuk menavigasi. Walau bagaimanapun, penting untuk menyeimbangkan antara mengulas dan mengutamakan. Terlalu banyak komen boleh membuat kod anda berantakan dan lebih sukar untuk dibaca.

Atas ialah kandungan terperinci Seberapa baik komen HTML dan CSS anda?. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!