Membuat dokumen standar pengkodean


14

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?


2
Apakah Anda sudah memiliki cakupan tes yang komprehensif? Tidak masalah seberapa cantik kodenya jika salah ...
JBRWilkinson

2
Hal yang baik adalah kita benar-benar menguji barang-barang kami, kami memiliki unit testing yang diimplementasikan untuk proyek kami, dan kami sebelum rilis kami akan menggunakan pengujian lorong acak, dan menulis spesifikasi tes untuk pengujian kotak hitam dan putih.
Felix Weir

Prioritas kelompok kecil kami adalah kode kami kuat dan tidak dapat rusak. Kami juga menggunakan bugzilla untuk pelacakan bug, dan alat pelaporan bug khusus untuk pengguna.
Felix Weir

Berikut adalah beberapa sumber yang dianggap "klasik" bekerja pada subjek. Saya menyarankan mengambil bagian terbaik dari standar ini untuk membuat dokumen yang memenuhi kebutuhan grup Anda: 1. Bell Labs, Indian Hill C Style dan Standar Pengkodean, 19 Februari 1997, maultech.com/chrislott/resources/cstyle/indhill-cstyle .pdf 2. Stallman, Richard, Standar Pengodean GNU, 30 Juni 2012, gnu.org/prep/standards/standards.html 3. Jet Propulsion Laboratory, JPL Institutional Coding Standard untuk Bahasa Pemrograman C, Versi 1.0, 3 Maret 2009, lars-lab.jpl.nasa.gov/JPL_Coding_Standard_
William Leara

Jawaban:


24

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.


Kami memiliki kontrol versi (SVN, berharap untuk segera pindah ke GIT), dan pimpinan proyek selalu mengingatkan kami untuk memperbarui secara berkala kemudian berkomitmen untuk menghindari konflik massal (setidaknya beberapa kali seminggu).
Felix Weir

BTW, Anda menyebutkan "alat yang memungkinkan pemeriksaan otomatis", alat apa ini? Saya penasaran.
Felix Weir

@ FelelixWeir: untuk .NET Framework? StyleCop.
Arseni Mourzenko

Oh benar, saya pikir Anda mengisyaratkan sesuatu yang lain. Kami menggunakan Stylecop ...: ^)
Felix Weir

1
@ Felelix Weir: juga, coba (jika Anda belum melakukannya) Analisis kode. Tujuannya berbeda dan tidak terkait dengan gaya itu sendiri, tetapi juga memungkinkan standarisasi.
Arseni Mourzenko

8

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.


1
Standar pengkodean sering, terutama untuk pengembangan C / C ++, juga berisi bagian (besar) tentang bahasa mana yang Anda sebaiknya tidak menggunakan dan mengapa.
Bart van Ingen Schenau

1
@ BartartIngenSchenau tidak ada alasan mengapa Anda membutuhkannya untuk C ++, atau mengapa Anda tidak membutuhkan bagian yang serupa untuk bahasa lain - Anda dapat membuat kekacauan dari C # atau JS atau .. yah, apa saja. Semua bahasa memiliki 'fitur yang dapat disalahgunakan'. Terbaik untuk melatih para dev Anda untuk menjadi baik dalam pekerjaan mereka alih-alih mengisi dokumen standar dengan tutorial mini "bagaimana tidak memberi kode".
gbjbaanb

@ gbjbaanb: Saya tidak dapat mengomentari bahasa lain, tetapi C ++ memiliki sudut dan jebakan yang cukup gelap sehingga ini bukan tentang menghindari kesalahan penggunaan, tetapi mengarahkan orang menjauh dari fitur yang sulit digunakan dengan benar (misalnya, kelebihan muatan dari &&). Pelatihan itu baik, tetapi kadang-kadang lebih baik memiliki dokumen referensi yang bagus untuk menyegarkan ingatan Anda mengapa Anda tidak harus melakukannya.
Bart van Ingen Schenau

1
@ BartartIngenSchenau saya merasa akan lebih baik ditempatkan dalam Dokumen Pedoman Pengkodean , bukan Dokumen Standar Pengkodean
RhysW

@RhysW: Cukup adil. Pengalaman saya adalah bahwa keduanya biasanya digabungkan dalam satu dokumen (berjudul 'Standar Pengkodean'), tetapi saya tidak menganggapnya dalam dua dokumen sebagai masalah.
Bart van Ingen Schenau

6

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,


2
+1 Saya akan mengatakan hal yang sama. Membuat dokumen standar pengkodean adalah pekerjaan besar yang telah dilakukan sebelumnya. Temukan yang baik, kemudian ubah untuk menyesuaikan.
John MacIntyre

4

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).


2

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.

Dengan menggunakan situs kami, Anda mengakui telah membaca dan memahami Kebijakan Cookie dan Kebijakan Privasi kami.
Licensed under cc by-sa 3.0 with attribution required.