Membuat dokumen standar pengkodean

Saya bekerja di perusahaan sistem kontrol, di mana pekerjaan utamanya adalah SCADA dan PLC , bersama dengan hal-hal sistem kontrol lainnya.

Pengembangan perangkat lunak sebenarnya bukanlah sesuatu yang dilakukan perusahaan, terlepas dari potongan kecil di sana-sini, sampai ada keputusan untuk membuat manajemen proyek internal dan sistem penilaian.

Proyek ini telah diambil oleh orang-orang yang datang ke sini sebagai orang-orang perangkat lunak pada awalnya dan kami kebanyakan junior.

Proyek ini dimulai dari yang kecil, jadi kami hanya mendokumentasikan hal-hal seperti desain, hal-hal database dll, tetapi kami tidak pernah benar-benar menyetujui format / konvensi pengkodean.

Kami mulai menggunakan StyleCop untuk memastikan kami memiliki kode yang terdokumentasi dengan baik, tetapi saya merasa kami membutuhkan dokumen resmi untuk mengkode konvensi / praktik sehingga kami dapat melanjutkan standar yang baik dan jika ada pekerjaan pengembangan yang lebih besar di masa depan, siapa pun yang bekerja di dalamnya memiliki baseplate yang bagus.

Disinilah letak masalahnya, saya tidak tahu bagaimana menyusun dokumen untuk konvensi dan standar pengkodean, yang bisa saya pikirkan adalah contoh praktik yang baik vs buruk (misalnya kasus unta saat menamai variabel, menghindari notasi Hongaria dll) kita semua programmer yang cukup kompeten (tampaknya) tetapi kami hanya tidak memiliki piagam untuk hal semacam ini.

Untuk menjelaskannya, pertanyaan saya adalah: Apa saja aspek dan isi utama dari dokumen standar pengkodean yang baik?

Apa saja aspek dan isi utama dari dokumen standar pengkodean yang baik?

1. Yang didukung oleh alat yang mengaktifkan otomatis memeriksa kode . Jika saya tahu bahwa saya tidak dapat berkomitmen untuk mengontrol versi kode apa pun yang tidak cocok dengan beberapa aturan, saya akan didorong untuk mengikuti aturan-aturan dalam kode saya. Jika, di sisi lain, beberapa rekan programmer telah menulis di suatu tempat bahwa saya harus mengikuti aturan, saya tidak memberikan omong kosong tentang aturan itu.

2. Dipikirkan dengan matang, alih-alih menjadi pendapat pribadi Anda . Anda tidak dengan jelas mengatakan: "mulai sekarang, kami tidak lagi menggunakan daerah, karena saya tidak suka daerah." Sebaliknya, Anda akan menjelaskan bahwa kawasan mendorong pertumbuhan kode dan tidak memecahkan masalah besar apa pun .

   Alasannya adalah bahwa dalam kasus pertama, kolega Anda akan menjawab: "Yah, saya suka daerah, jadi saya masih akan menggunakannya". Dalam kasus kedua, di sisi lain, itu akan memaksa orang yang tidak setuju untuk datang dengan kritik, saran, dan argumen yang membangun, pada akhirnya membuat Anda mengubah pendapat awal Anda.

3. Menjadi didokumentasikan dengan baik . Kurangnya dokumentasi menciptakan kebingungan dan ruang untuk interpretasi ; kebingungan dan kemungkinan penafsiran mengarah pada perbedaan gaya, yaitu standar hal yang ingin ditekan.

4. Menjadi tersebar luas, termasuk di luar perusahaan Anda . "Standar" yang digunakan oleh dua puluh programmer kurang dari standar yang dikenal oleh ratusan ribu pengembang di seluruh dunia.

Karena Anda berbicara tentang StyleCop, saya kira aplikasi tersebut ditulis dalam salah satu bahasa .NET Framework.

Dalam hal itu, kecuali Anda memiliki alasan serius untuk melakukan hal yang berbeda, tetaplah dengan pedoman Microsoft. Ada beberapa manfaat dalam melakukannya daripada menciptakan standar Anda sendiri. Mengambil empat poin sebelumnya:

1. Anda tidak perlu menulis ulang aturan StyleCop agar sesuai dengan standar Anda sendiri. Saya tidak mengatakan sulit untuk menulis aturan Anda sendiri, tetapi jika Anda dapat menghindari melakukannya, itu berarti Anda memiliki lebih banyak waktu melakukan sesuatu yang bermanfaat sebagai gantinya.

2. Pedoman Microsoft dipikirkan dengan sangat baik. Ada kemungkinan bahwa jika Anda tidak setuju dengan beberapa dari mereka, itu mungkin karena Anda tidak memahaminya. Ini persis kasus saya; ketika saya memulai pengembangan C #, saya menemukan beberapa aturan yang benar-benar bodoh. Sekarang, saya sepenuhnya setuju dengan mereka, karena saya akhirnya mengerti mengapa mereka ditulis dengan cara ini.

3. Pedoman Microsoft didokumentasikan dengan baik, sehingga Anda tidak perlu menulis dokumentasi Anda sendiri.

4. Pengembang baru yang akan dipekerjakan di perusahaan Anda nanti mungkin sudah akrab dengan standar pengkodean Microsof. Ada beberapa kemungkinan bahwa tidak ada yang akan terbiasa dengan gaya pengkodean internal Anda.

Hal penting pertama yang perlu diperhatikan adalah bahwa dokumen standar pengkodean bukan tentang benar dan salah. Ini bukan tentang baik dan buruk atau metode mana yang lebih baik.

Tujuan dokumen standar pengkodean adalah untuk memastikan bahwa semua kode dirancang, ditulis, dan ditata sama untuk membuatnya lebih mudah bagi pengembang untuk beralih dari satu pekerjaan orang ke orang lain tanpa diperlukan perubahan mentalitas untuk membaca gaya orang lain.

Ini semua tentang keseragaman, dan tidak ada tentang "Benar dan salah"

Dengan mengingat beberapa hal yang harus Anda perjelas dalam dokumen standar pengkodean adalah:

Konvensi Penamaan

Bagaimana Anda memberi nama metode, variabel, kelas, dan antarmuka Anda? Notasi mana yang akan Anda gunakan?

Juga hal lain yang termasuk dalam standar kami adalah standar pemisahan untuk SQL, jadi kami memiliki nama yang mirip untuk tabel, prosedur, kolom, bidang id, pemicu, dll.

Lekukan

Apa yang akan Anda gunakan untuk indentasi? Satu tab? 3 ruang?

Tata letak

Apakah kawat gigi akan disimpan pada garis yang sama dengan garis metode pembukaan? (umumnya java) atau di baris berikutnya atau baris sendiri? (umumnya C #)

Penanganan / Penebangan Eksepsi

Apa standar Anda untuk penanganan & penebangan pengecualian, apakah semuanya dibuat sendiri atau Anda menggunakan alat pihak ketiga? Bagaimana cara menggunakannya?

Mengomentari

Kami memiliki standar untuk menentukan ketepatan tata bahasa, dan bahwa komentar dimulai pada baris sebelum, atau setelah, bukan pada baris yang sama, ini meningkatkan keterbacaan. Apakah komentar harus dijorok ke kedalaman yang sama dengan kode? Apakah Anda akan menerima batas komentar yang digunakan di sekitar teks yang lebih besar?

Bagaimana dengan Metode untuk deskripsi? Apakah ini untuk digunakan? Kapan?

Paparan

Haruskah semua metode dan bidang Anda menerapkan tingkat akses serendah mungkin?

Juga hal yang penting untuk diperhatikan. Dokumen standar yang baik dapat membantu dalam meninjau kode, apakah memenuhi standar minimum ini?

Saya baru saja menggaruk permukaan apa yang bisa masuk ke salah satu dokumen ini, tetapi KISS

Jangan membuatnya panjang, dan membosankan, dan tidak mungkin untuk dilalui, atau standar-standar itu tidak akan diikuti, tetap sederhana.

Saya telah melalui proses ini beberapa kali. Dan pendekatan yang paling sukses (walaupun bergelombang) adalah mengambil dokumen "Standar Pengkodean" dari perusahaan terkenal dan memodifikasinya agar sesuai dengan kebutuhan Anda.

Sebagai contoh, saya baru saja menemukan ini: http://www.tiobe.com/content/paperinfo/gemrcsharpcs.pdf

Ngomong-ngomong, jaga agar pelempar nyala api Anda tetap berguna.

Bersulang,

Saya benci sebagian besar dokumen standar karena mereka biasanya berusaha untuk mengeluarkan barang-barang kecil dan mengabaikan gambar yang lebih besar.

Misalnya, hampir semua dari mereka akan mengatakan bagaimana memberi nama variabel atau menempatkan tanda kurung. Ini adalah gaya murni dan tidak banyak membantu sekelompok kode devs dengan benar. Mereka mengabaikan hal-hal seperti struktur direktori dan tata letak kode. Saya telah melihat dokumen standar yang memberi tahu Anda dengan tepat berapa banyak ruang untuk diletakkan di antara operator dan berapa banyak garis kosong untuk menempatkan di antara metode. Semua ini biasanya berakhir dengan satu ton pengecualian untuk aturan yang hanya menunjukkan betapa tidak bergunanya mereka sebenarnya, dan kemudian mereka begitu besar tidak ada yang bisa mengikuti mereka, yang lagi-lagi, membuat ejekan dari titik yang mereka coba buat .

Sekarang bagi saya, saya menggunakan banyak bit perangkat lunak dari banyak orang yang berbeda dan mereka semua memiliki gaya yang berbeda. Saya cukup terbiasa dengan ini, saya tidak mengeluh bahwa tidak ada gaya umum di semua kelompok pengembangan. Selama kode itu adalah gaya umum di seluruh proyek, saya benar-benar tidak peduli apa gaya itu. Jadi aturan pertama saya untuk semua dokumen standar adalah: Pertahankan gaya pengkodean yang konsisten dalam proyek . tidak seorang pun harus memberi tanda di mana tanda kurung berada, asalkan semuanya sama. Ambil perang agama dan dorong mereka :)

Yang kedua adalah tata letak kode. Ketika saya mengambil sepotong kode, saya ingin melihat bahwa itu diletakkan di sepanjang garis yang sama dengan yang lain, karya yang serupa. Jika saya memiliki layanan web saya ingin nama kontrak wsdl menjadi jelas, saya ingin nama implementasinya menjadi jelas. Saya tidak ingin seseorang membuat tata letak baru dan berbeda untuk file dan kelas. Itu berarti saya harus bermain "berburu kode" yang merupakan gangguan. Jika kelihatannya sama dengan proyek terakhir yang saya kerjakan, saya bisa langsung tahu di mana menemukan apa yang saya cari dan itu mungkin bantuan terbesar untuk bekerja dengan kode orang lain yang saya tahu. Jadi, simpan struktur bagaimana kode diletakkan (misalnya folder Dokumentasi untuk dokumen, antarmuka untuk antarmuka dll - apa pun itu yang bekerja untuk Anda, tetapi tetap gunakan itu).

Artefak kode juga harus ada, jadi Anda harus mengatakan apakah penanganan kesalahan yang diharapkan adalah pengecualian atau kode kesalahan - yaitu. mendokumentasikan fungsi arsitektur yang sedang digunakan . Itu juga harus mengatakan jenis logging apa yang digunakan dan bagaimana menyajikan log / penanganan kesalahan kepada pengguna atau subsistem apa pun yang digunakan untuk mengelola kode di alam. Saya bekerja di tempat di mana setiap proyek melakukan logging secara berbeda - itu menyedihkan bagaimana setiap rilis kode harus memiliki sendiri, berbeda, dokumen operasi memberitahu ops guys bagaimana cara mengetahui apakah itu salah. Log peristiwa, file log (dalam hal ini di mana), dll semuanya valid di sini. Hal yang sama berlaku untuk aspek umum lainnya pada kode - cara mengkonfigurasinya (tidak ada gunanya menggunakan file .config untuk beberapa program, atau DB khusus, atau params baris perintah, atau registri untuk yang lain).

Singkatnya, satu-satunya hal yang penting adalah Konsistensi . Dan karena dokumen standar besar terlalu banyak untuk dibaca dan dihafal, saya lebih suka memberi tahu orang-orang tentang hal-hal yang tidak dapat mereka lihat (misalnya standar arsitektur seperti pencatatan) dan meminta mereka untuk menjaga kode yang mereka tulis sesuai dengan apa yang ada saat ini. Dan jika Anda belum memiliki kode maka Anda tidak memerlukan dokumen standar! (yah, tidak sampai Anda cukup menulis untuk membuatnya berguna).

Jadi, ambil dari poin utama itu: jangan mencoba membuat dokumen hukum , pikirkan hal-hal yang tidak hanya coding tetapi juga bagaimana kode bekerja dan bagaimana kode sesuai dengan harapan orang lain. Kemudian percaya orang untuk melakukan kode yang baik dan Anda akan melihat bahwa mereka melakukannya. (dan jika tidak, Anda dapat berbicara dengan mereka, tidak perlu meletakkannya seperti hukum).

Jangan, ini buang-buang waktu dan energi. StyleCop hebat dan didirikan selama bertahun-tahun oleh orang-orang yang jauh lebih berpengalaman dan jauh lebih pintar daripada Anda atau siapa pun di tim Anda. Rangkullah dan cintai! Ini memandu Anda terus-menerus, yang lebih baik daripada dokumen apa pun yang menunggu seseorang yang dapat repot membacanya.