Apa yang harus ada dalam standar pengkodean? [Tutup]

Apa yang harus dalam standar pengkodean yang baik (baca: bermanfaat)?

• Hal-hal yang seharusnya dimiliki kode.
• Hal-hal yang seharusnya tidak dimiliki kode.
• Haruskah standar pengkodean memasukkan definisi hal-hal yang diberlakukan oleh bahasa, kompiler, atau pemformat kode?
• Bagaimana dengan metrik seperti kompleksitas siklomatik, baris per file, dll?

Alasan untuk setiap persyaratan. Dengan cara ini, mengikuti standar tidak menjadi semacam kultus kargo dan orang-orang tahu bahwa tidak apa-apa untuk mengubah standar jika alasan untuk itu tidak lagi berlaku, atau untuk melanggar standar dalam kasus tertentu di mana alasannya jelas tidak berlaku .

Tab vs Spaces! Saya mendapatkan pembaruan gila ketika salah satu kolega saya secara tidak sengaja melakukan banyak tab pada spasi bergeser ke dalam repositori

Konvensi Penamaan

EDIT: Maksud saya ini adalah penamaan Pedoman, bukan penamaan Aturan.

Sebagai contoh, sebuah Pedoman akan menjadi All boolean values should begin with Is/Can/Has/etc when possible. Suatu aturan adalahAll boolean values must start with Is

Standar pengkodean untuk grup harus menyertakan opsi penyusun untuk peringatan dan kesalahan yang harus diatasi.

Pemrogram harus bebas meningkatkan peringatan untuk kode mereka sendiri, tetapi harus ada garis dasar sehingga membaca dan bekerja dengan kode orang lain tidak mengacaukan hasil yang Anda dapatkan dari kompiler.

Standar semacam itu juga harus membahas bagaimana pemrogram dapat menonaktifkan peringatan tersebut kasus per kasus, seandainya ada potongan kode yang luar biasa yang tidak akan sesuai.

Beberapa standar yang saya suka (saya tahu ada banyak dari mereka, tapi itu yang saya sukai):

• 80% cakupan tes unit
• Kepemilikan kolektif atas kode (tulis kode untuk dibaca oleh rekan tim Anda, bukan kompiler)
• Tulis komentar. Tulis apa yang akan Anda katakan kepada pendatang baru.
• Tetap sederhana

Standar Pengkodean sedikit membantu ketika Anda menulis kode pertama kali, mereka banyak membantu ketika Anda, atau pengganti Anda, harus memperbarui kode 2 tahun kemudian.

Standar ideal mengarah ke kode tempat Anda dapat melompat ke halaman sewenang-wenang apa pun dalam kode, dan pahami apa yang dilakukannya saat membaca pertama kali, karena

• nama-nama dengan jelas menggambarkan data apa yang sedang dimanipulasi,
• kawat gigi membuat aliran kontrol jelas,
• komentar menjelaskan algoritma yang tidak jelas, dll.

Di sisi lain, terlalu banyak standar arbitrer dapat mengganggu aliran penulisan kode. Jadi saya percaya bahwa setiap item dalam konvensi pengkodean yang diusulkan harus dievaluasi terhadap 2 kriteria ini:

• Apakah aturan ini membantu memastikan bahwa kode itu Benar ?
• Apakah aturan ini membantu memastikan bahwa kode tersebut Jelas ?

Jika tidak ada yang benar, item tersebut hanya sewenang-wenang, dan mungkin tidak perlu

Saya akan memasukkan hal-hal berikut dalam standar yang saya tulis:

Untuk kejelasan:

• Organisasi File: Menentukan urutan tetap untuk item dalam file memungkinkan tim dengan mudah menavigasi file lain. Anda tidak perlu berburu untuk menemukan #defines, atau menyusun definisi.

• Konvensi penamaan: Penamaan yang konsisten membantu keterbacaan. Tetapi hindari terlalu banyak menetapkan terlalu banyak aturan, yang membahayakan kemampuan menulis.

• Struktur Kode. Penempatan Curly Brace, level indentasi, spasi vs tab, dll. Ya, ini bisa menjadi preferensi pribadi yang kuat, tetapi tujuannya adalah kode yang jelas. Temukan opsi terbaik untuk tim, dan tetap gunakan.

Untuk kebenaran:

• Praktik Terbaik khusus untuk jenis masalah Anda: Aturan tentang alokasi memori, atau konkurensi, atau portabilitas.

• "Const Correctnesss", penggunaan yang tepat dari staticdan volatile, dll.

• Aturan tentang macro preprocessor, dan fitur bahasa lainnya yang mudah disalahgunakan.

Ide-ide inspiratif dan pragmatis yang membuat orang berpikir, bukannya pembatasan negatif yang menghentikan orang untuk berpikir.

Kalau tidak, Anda akan mendapatkan kode monyet yang takut mengejar pisang .

Apa yang harus ada dalam standar pengkodean? Sesedikit mungkin. Kurang lebih banyak. Dan dengan justifikasi, kumohon.

Bukan karena saya seorang koboi pembuat kode yang tidak menginginkan proses, tetapi karena saya telah melihat spesifikasi pengkodean yang berat tanpa logika di baliknya (mungkin) "Saya menemukan ini di 'Net di suatu tempat di tahun '95" yang akhirnya menjadi mimpi buruk birokrasi untuk bekerja dengannya.

Beberapa orang dengan jujur ​​tampaknya percaya bahwa dengan menaikkan standar mereka akan melihat peningkatan yang sesuai dalam "kualitas" kode dan mungkin dengan ukuran itu mereka akan. Sementara itu mereka akan mengabaikan arsitektur, kinerja, akal sehat, dan banyak hal lain yang akhirnya lebih penting daripada jumlah baris dalam sebuah file.

Prosedur untuk tinjauan kode untuk menegakkan standar. Oh, dan untuk menemukan bug juga.

Beberapa akal sehat lama yang baik tidak akan salah; ada terlalu banyak pengkodean dokumen standar yang bekerja pada poin yang tidak relevan (item seperti jenis font dan ukuran menjadi salah satu yang lebih ekstrim yang pernah saya lihat).

Hal terbaik yang harus dilakukan jika Anda berada dalam kelompok pengembang adalah berbicara satu sama lain dan melihat kode Anda, membentuk konsensus tentang apa yang dapat diterima dan jika Anda perlu menuliskan poin utama sebagai pedoman, tetapi simpan sebagai hanya pedoman itu. Jika Anda tidak dapat membenarkan perbedaan apa pun dari pedoman, Anda harus benar-benar mempertimbangkan mengapa Anda melakukannya.

Pada akhirnya, kode yang jelas dan mudah dipahami lebih penting daripada aturan kaku tentang tata letak atau tipografi.

Seperti yang telah disebutkan orang lain, cakupan tes kode penting. Saya juga suka melihat:

• Struktur proyek. Apakah tes bagian dari kode, atau mereka dalam proyek / paket / direktori yang terpisah? Apakah kode UI hidup dengan hal-hal back-end? Jika tidak, bagaimana kompartemennya?

• Proses pengembangan. Tulis tes sebelum kode? Apakah memperbaiki bangunan yang rusak lebih diprioritaskan daripada pembangunan? Kapan ulasan kode dilakukan, dan apa yang harus mereka bahas?

• Manajemen kode sumber. Apa yang diperiksa kapan? Apakah dokumen desain dan rencana pengujian dikendalikan oleh revisi? Kapan Anda bercabang dan kapan Anda menandai? Apakah Anda menyimpan bangunan sebelumnya, dan jika ada berapa / berapa lama?

• Standar penempatan. Bagaimana sebuah build dikemas? Apa yang perlu dimasukkan ke dalam catatan rilis? Bagaimana cara skrip upgrade dibuat / dikendalikan / dijalankan?

Lupakan semua omong kosong tentang konvensi penamaan, pemformatan dan berapa banyak baris yang bisa ada dalam fungsi / metode / modul. Satu aturan: gunakan apa pun gaya yang ada dalam apa pun yang sedang Anda edit. Jika Anda tidak menyukai gaya seseorang, pisahkan dalam ulasan kode. Satu-satunya pengecualian mungkin adalah tab-vs-spasi, jika hanya karena banyak editor / IDE akan secara buta mengkonversi satu ke yang lain, dan kemudian Anda akhirnya menghancurkan sejarah perubahan Anda karena setiap baris diubah.

Saya pikir sebenarnya ada dua hal untuk diatasi, dan saya sebenarnya akan mempertimbangkannya secara terpisah karena mereka tidak dapat didekati dengan cara yang sama, meskipun saya menemukan keduanya penting.

• Aspek teknis: yang bertujuan menghindari kode berisiko atau tidak terbentuk dengan benar (walaupun diterima oleh kompiler / juru bahasa)
• Aspek presentasi: yang berkaitan dengan membuat program menjadi jelas bagi pembaca

Aspek teknis saya memenuhi syarat Standar Pengkodean , seperti halnya Herb Sutter dan Andrei Alexandrescu dengan Standar Pengodean C ++ . Presentasi saya memenuhi syarat dari Coding Style , yang meliputi konvensi penamaan, indentasi, dll ...

Standar Pengkodean

Karena murni teknis, Standar Pengkodean sebagian besar obyektif. Karena itu setiap aturan harus didukung oleh suatu alasan. Dalam buku yang sayaacu setiap item memiliki:

• Judul, sederhana dan to the point
• Ringkasan, yang menjelaskan judul
• Diskusi, yang menggambarkan masalah melakukan sebaliknya dan dengan demikian menyatakan alasannya
• opsional Beberapa contoh, karena contoh yang baik bernilai ribuan kata
• opsional Daftar pengecualian yang aturan ini tidak bisa diterapkan, kadang-kadang dengan kerja di sekitarnya
• Daftar referensi (buku lain, situs web) yang telah membahas poin ini

Alasan dan Pengecualian sangat penting, karena mereka merangkum mengapa dan kapan.

Judul harus cukup eksplisit sehingga selama ulasan orang hanya perlu memiliki daftar judul (lembar contekan) untuk bekerja dengannya. Dan jelas, kelompokkan item berdasarkan kategori untuk membuatnya lebih mudah untuk mencari satu.

Sutter dan Alexandrescu berhasil memiliki daftar hanya seratus item, meskipun C ++ dianggap berbulu;)

Gaya Pengodean

Bagian ini umumnya kurang objektif (dan bisa benar-benar subjektif). Maksudnya di sini adalah untuk menjamin konsistensi, karena ini membantu para pengelola dan pendatang baru.

Anda tidak ingin memasuki perang suci tentang gaya lekukan atau penjepit mana yang lebih baik di sini, ada forum untuk ini: jadi dalam kategori ini Anda melakukan sesuatu dengan konsensus> suara terbanyak> keputusan sewenang-wenang oleh pemimpin.

Untuk contoh pemformatan, lihat daftar opsi Gaya Artistik . Idealnya, aturannya harus jelas dan cukup lengkap sehingga suatu program dapat menulis ulang kode (meskipun tidak mungkin Anda akan pernah kode satu;))

Untuk konvensi penamaan, saya akan mencoba membuat kelas / tipe mudah dibedakan dari variabel / atribut.

Juga dalam kategori ini saya mengklasifikasikan "tindakan" seperti:

• lebih suka metode pendek ke panjang: biasanya sulit untuk menyepakati berapa lama
• lebih suka kembali / melanjutkan / istirahat awal untuk mengurangi lekukan

Lain-lain?

Dan sebagai kata terakhir, ada satu item yang jarang, jika pernah, dibahas dalam Standar Pengkodean, mungkin karena itu khusus untuk setiap aplikasi: organisasi kode. Masalah arsitektur mungkin adalah masalah yang paling menonjol, mengacaukan desain awal dan Anda akan diganggu olehnya bertahun-tahun dari sekarang. Anda mungkin harus menambahkan bagian untuk penanganan file dasar: header publik / pribadi, manajemen ketergantungan, pemisahan masalah, berinteraksi dengan sistem atau perpustakaan lain ...

Tapi itu bukan apa - apa jika tidak benar-benar diterapkan dan ditegakkan .

Pelanggaran apa pun harus diajukan selama ulasan kode, dan tidak ada review kode yang boleh diterima jika pelanggaran terjadi:

• perbaiki kode agar sesuai dengan aturan
• perbaiki aturan sehingga kode tidak menonjol lagi

Jelas, mengubah aturan berarti mendapatkan "jalan terus" dari para pemimpin.

Saya suka format dalam Kerangka Desain Pedoman ini termasuk bagian umum dan rasional untuk pedoman. Bit yang paling berguna adalah detail yang dimulai dengan Lakukan, Jangan, Hindari dan Pertimbangkan.

Berikut ini adalah contoh di bagian Menerapkan Antarmuka Anggota secara eksplisit memiliki item berikut (catatan saya menjatuhkan alasan demi kepentingan bervity)

Hindari menerapkan anggota antarmuka secara eksplisit tanpa memiliki alasan kuat untuk melakukannya

Pertimbangkan untuk mengimplementasikan anggota antarmuka secara eksplisit jika anggota dimaksudkan untuk dipanggil hanya melalui antarmuka.

Jangan menggunakan anggota eksplisit sebagai batas keamanan.

Berikan anggota virtual terlindungi yang menawarkan fungsionalitas yang sama dengan anggota yang diimplementasikan secara eksplisit jika fungsionalitas dimaksudkan untuk dikhususkan oleh kelas turunan.

Ini menciptakan nada umum yang baik. Dengan menggunakan Hindari dan Pertimbangkan, Anda dapat mengizinkan pengembang menggunakan penilaian mereka. Juga karena itu adalah pedoman dan bukan peraturan, pengembang cenderung menganggapnya lebih enak dan pada gilirannya lebih mungkin untuk mengikutinya.

Sepertinya tidak ada yang menyebutkan keamanan - dalam standar pengkodean Anda harus memiliki referensi ke persyaratan kode aman (misalnya penggunaan modul validasi input, melarang fungsi yang dikenal lemah seperti strcpy, persyaratan penanganan kesalahan dll)

Contohnya. Contoh-contoh yang tersusun rapi, tidak sepele, dan nyaris mirip dengan dunia nyata yang memanfaatkan setiap aturan. Komentar (tidak harus bagian dari kode) bagian mana dari contoh mengikuti aturan mana.

Templat. Bukan jenis C ++, tetapi sesuatu untuk disalin-tempel dan isi dengan live. Ini jauh lebih mudah untuk mendapatkan komentar boilerplate 24-baris yang tepat ketika Anda memiliki referensi untuk menyalin.

Fitur nomor satu: Maksimal dua halaman.

Ini adalah sesuatu yang Anda ingin setiap pengembang baca dan ingat. Anda tidak harus mencari dalam standar setiap kali Anda perlu menulis fungsi baru (atau lebih buruk baris baru). Jadi, tetap singkat dan tetap hanya aturan yang benar-benar memberikan peningkatan nilai pada produk akhir.

Standar pengkodean benar-benar beberapa item:

Konvensi pengkodean

• hal-hal ini tidak memerlukan alasan lain selain "konsistensi basis kode" untuk ex. untuk menggunakan '_' dalam variabel anggota pribadi atau tidak.
• mungkin ada beberapa pendekatan yang benar. Hanya perlu memilih satu untuk konsistensi. misalnya menangani kesalahan menggunakan pengecualian atau kode kesalahan.

Praktik terbaik

• barang-barang ini selalu membutuhkan alasan yang bagus dengan beberapa contoh yang jelas

misalnya Jangan pernah meninggalkan Tangkapan kosong setelah mencoba

try { Foo(); } catch { //do nothing }

1) Jika ada pengecualian yang dilemparkan oleh Foo () dapat menyebabkan masalah lain pada fungsi yang mengikuti, yang menganggap bahwa foo berhasil.

2) Global error handler tidak akan memberi tahu tim pendukung pengecualian ketika itu terjadi pada prod

• membahas praktik-praktik "Defensive Coding", seperti menggunakan Asserts untuk menguji asumsi Anda.

Lingkungan Pengkodean

• alat yang digunakan seluruh tim. misalnya VS 2010, Resharper, Kiln, dll.

Standar pengkodean, ketika dituliskan di atas kertas, hanya sangat efektif. Saya suka bagaimana Go menerbitkan standar pengkodeannya. Ini memiliki alat gofmtuntuk memformat teks program ke format. Setiap debat pada format pengkodean kemudian hanya akan menghasilkan sebagai tambalan ke sumber gofmt.

Adapun apa format seharusnya,

• cara memberi nama variabel, makro, konstanta, literal, fungsi, dll
• bagaimana menempatkan {,}, (,), [,] ketika datang ke if, badan fungsi, blok pernyataan untuk tujuan lain,
• seberapa lebar lekukan itu,
• berapa banyak karakter yang diperbolehkan satu baris teks
• berapa tingkat indentasi yang diizinkan sebelum kode ditolak / dikirim untuk refactoring
• berapa banyak baris kode yang dibolehkan per fungsi sebelum dikirim kembali untuk refactoring
• jumlah argumen maksimum yang dapat diambil suatu fungsi sebelum dikirim kembali untuk refactoring
• Beberapa baris komentar sebelum suatu fungsi mulai menjelaskan secara singkat apa fungsinya, jika tubuh melebihi satu halaman pada kode layar; meninggalkan bagaimana objek dicapai ke kode di tubuh fungsi

Ketika saya membaca kode orang lain (sebagian besar bahasa C), jika nama variabel / fungsi tidak intuitif dalam konteks proyek atau jika melebihi lima tingkat lekukan atau fungsi, perlu lebih dari enam atau tujuh argumen atau fungsi berjalan selama lebih dari dua atau tiga halaman di layar, menjadi sangat sulit untuk membaca dan memahami kodenya. Ketika diminta untuk melakukan peningkatan / pemeliharaan bekerja di atasnya, itu hanya menambah kesulitan. Itu membuat saya berharap gofmtprogram ditulis untuk setiap proyek (atau bahkan bahasa) dan setiap file kode sumber dijalankan melalui program itu sebelum dimasukkan ke dalam proyek.

Saya suka Panduan Gaya Google JavaScript .

Ringkasnya dalam panduannya belum memiliki detail jika Anda membutuhkannya.

Kode dokumentasi diri (komentar, nama variabel, nama fungsi, dll.)