Pengiriman perpustakaan kelas satu saya. Adakah gotchas yang perlu saya waspadai?


12

Saya seorang Pengembang Web yang akan membuka kunci pencapaian "Perpustakaan Kelas Pertama yang Diterbitkan" dalam karir saya dan saya berkeringat (saya terjaga sepanjang malam karena stres). Saya ingin mengetuk pengalaman komunitas untuk melihat apakah ada yang punya saran atau rekomendasi untuk memastikan ini berjalan semulus mungkin. Apakah ada spesifik atau Gotcha yang perlu saya ketahui? Adakah yang istimewa tentang proses pembuatan yang dapat kembali menggigit saya?

Di sinilah tempat saya:

  • Perpustakaan adalah unit yang diuji dan memiliki sekitar 97% cakupan kode
  • API didokumentasikan dengan baik dan dokumen xml untuk dukungan intellisense telah dibuat
  • Saya telah memastikan bahwa aksesor kelas publik / swasta akurat dan benar. Hal yang sama berlaku untuk semua getter / setter
  • Penanganan kesalahan tidak seanggun yang saya inginkan, tapi saya menghadapi tenggat waktu dan telah menerima bahwa itu "sebagus apa yang akan terjadi" untuk saat ini
  • Tidak ada penebangan yang ramah. Debug.Writeline digunakan secara luas ... Saya baru-baru ini belajar bahwa ini adalah cerminan dari pengalaman saya yang kurang :(

Nasihat Anda sangat dihargai!

Perpustakaan akan digunakan untuk menghasilkan laporan. Topi standar - menghubungkan ke database hanya baca, melakukan calcs, format dan output data ke aliran respons.


Saya disadap sebagai sumber daya pinggiran untuk mengisi salah satu programmer yang berhenti, dan tugas ini diberikan kepada saya sebagai proyek "potong gigi". Pustaka kelas akan dirilis untuk programmer lain di perusahaan untuk digunakan saat mereka menulis kode produksi.


2
Perlu detail, lepaskan caranya? Rilis untuk dijual? Lepaskan sumber terbuka untuk berbagi? Melepaskan ke klien per kontrak yang sedang Anda jalani? Melepaskan ke seluruh organisasi pengembangan Anda sebagai bagian dari proyek untuk majikan penuh waktu Anda? Melepaskan sebagai v1.0 produk baru ke ketersediaan klien untuk atasan penuh-waktu Anda?
Jimmy Hoffa

@JimmyHoffa: menambahkan jawaban untuk pertanyaan Anda. Terima kasih telah meluangkan waktu!
Tn. JavaScript

1
Berpura-puralah Anda adalah pengguna perpustakaan tanpa pengetahuan tentang cara kerjanya. Gunakan itu untuk membangun sesuatu. Ubah / hapus / tambahkan hal-hal berdasarkan pengalaman. Kemudian lepaskan ke pengguna nyata dan dapatkan umpan balik mereka.
mike30

Mungkin menggunakan Sandcastle atau perpustakaan yang menghasilkan dokumen lain untuk memiliki bahan referensi offline (ish)?
Jesse C. Slicer

7
Bersantai. Bahkan memiliki satu tes unit tunggal dan satu baris dokumentasi API sudah meningkatkan rilis ini di atas ~ 95% dari kode "dirilis untuk programmer lain di perusahaan untuk menggunakan", menurut pengalaman saya.
Carson63000

Jawaban:


8

Kunci API

Seni membangun API secara efektif adalah tentang mengelola harapan seperti halnya tentang struktur.

Ketika saya mengatakan API, saya secara khusus merujuk pada bagaimana kelas / metode publik / internal dinamai dan apa tingkat aksesnya (yaitu privat / publik / internal).

Jika Anda khawatir kode tersebut mungkin tidak sepenuhnya siap untuk prime-time, Anda pada awalnya selalu dapat mempublikasikannya sebagai beta.

Rilis:

  • Beta (yaitu pra 1.0)

    • dapat berisi beberapa perubahan API yang melanggar
    • mungkin tidak memiliki perubahan kompatibilitas ke belakang antara versi
    • mungkin memiliki kekurangan cat
  • Resmi (1.0+)

    • API terkunci hingga rilis besar berikutnya
    • setiap perubahan yang diperkenalkan harus menjamin kompatibilitas ke belakang
  • Minor (ex 1.1)

    • mengandung perbaikan bug dan-atau implementasi fitur
    • dapat menambah tetapi tidak mengambil dari API yang ditentukan

Jika menurut Anda API perlu diperangi dengan pertempuran, maka lepaskan untuk sementara waktu sebagai beta. Itu menandakan bahwa itu tersedia untuk digunakan tetapi tidak boleh digunakan untuk produksi dan / atau kode misi-kritis.

Banyak orang memperlakukan skema versi bernomor seperti omong kosong tetapi ketika mereka digunakan secara efektif mereka dapat digunakan untuk memberikan ruang gerak sampai Anda mendapatkan struktur beres.

Asumsi Anda tentang bagaimana itu akan digunakan salah

Tidak peduli seberapa baik sesuatu dirancang, orang akan menemukan cara untuk menyalahgunakan atau membuat penggunaan alternatif.

Salah satu cara untuk menangani ini adalah mengunci sebanyak mungkin implementasi menggunakan pengakses (yaitu pribadi / publik / internal) tetapi tidak ada jumlah desain atau rekayasa yang akan memberi Anda wawasan sebanyak melepaskan kode ke pengguna.

Tidak masalah seberapa 'sempurna' Anda pikir kode Anda dapat menjadi, pengguna Anda akan membuktikan bahwa itu tidak.

Saya berpendapat bahwa ini adalah alasan utama mengapa selalu lebih baik untuk menggunakan basis kode yang ada daripada melakukan penulisan ulang penuh. Paling-paling penulisan ulang yang lengkap akan memangkas mengasapi tetapi ada kemungkinan besar bahwa basis kode baru akan mengandung sebanyak (dan mungkin lebih) bug seperti basis kode asli.

Dalam kasus Anda, Anda sedang berjuang keras dari awal sehingga Anda bisa memulai.


Sepertinya Anda memiliki sisa pangkalan Anda tertutup. Dokumentasi API sangat penting dan tes akan bagus untuk memastikan stabilitas ketika perubahan dilakukan di masa depan.

Menerapkan skema penebangan yang konsisten akan menjadi penting sebelum kode dirilis untuk produksi karena Anda akan memerlukan cara untuk mengaktifkan / menonaktifkan / memfilter log secara global. BTW, dalam kebanyakan kasus logging hanya benar-benar melibatkan mengimpor perpustakaan dan mengubah panggilan keluaran dari Debug.WriteLine () ke sesuatu seperti Logging.Debug (), Logging.Info (), Logging.Error (). Logger itu sendiri hanya menyediakan implementasi standar untuk konfigurasi, pemfilteran, dan berbagai skema output yang lebih luas (file ex, konsol, dll).

Selain itu, saya akan mencari kode dan digunakan. Bahkan jika hanya dengan sejumlah kecil pengguna untuk memulai.


1
+1 Re: logging - Saya sangat merekomendasikan TraceSource . Ini tidak memperkenalkan dependensi eksternal karena merupakan bagian dari inti. NET librari dan memungkinkan pengguna untuk melampirkan pendengar dan mengkonfigurasi pelacakan baik melalui kode dan melalui file app.config.
Dan Lyons

4

Ini adalah dua hal yang saya temukan adalah kunci untuk merilis perangkat lunak:

  • Tahu persis apa yang telah Anda lepaskan
  • Kelola harapan

Anda ingin dapat kembali dan memperbaiki bug apa yang telah Anda rilis dan Anda ingin orang-orang memahami masalah apa yang akan dipecahkan oleh kode Anda.

Mengetahui apa yang telah Anda lepaskan

Pastikan Anda memilikinya versi yang benar dan ditandatangani (jika sesuai). Gunakan kontrol sumber Anda untuk memberi tag \ label kode yang terkait dengan versi yang dirilis secara resmi. Ini akan membantu Anda mengidentifikasi bug dengan lebih mudah karena Anda dapat kembali ke kode sumber yang Anda rilis. Ini juga akan membantu Anda ketika Anda mungkin memiliki beberapa versi rilis yang berbeda.

Cobalah untuk membuat versi terbaru mudah didapat dan diperbarui. Entah itu pemasang, atau hanya meletakkannya di saham biasa tergantung pada siapa \ kapan \ seberapa sering Anda akan dikirim.

Pastikan Anda meminta seseorang untuk meninjau rilis final Anda, termasuk dokumentasinya. Sangat mudah untuk menjadi gugup atau bersemangat tentang merilis perangkat lunak dan kehilangan sesuatu.

Mengelola harapan

Dokumentasikan batasannya dan buat itu cukup jelas bagi pengembang. Adalah baik bahwa Anda telah menemukan mereka. Orang-orang seringkali lebih memahami jika mereka tahu keterbatasan dengan perangkat lunak Anda, terutama jika Anda memiliki rencana untuk memperbaikinya.

Dokumentasikan bagaimana Anda ingin umpan balik, baik atau buruk. Karena ini adalah proyek internal, jika setiap orang memiliki akses ke sistem pelacakan bug umum, minta mereka untuk mengajukan bug terhadap proyek yang sesuai.

Di masa depan, hindari mengubah API jika memungkinkan, ini adalah satu hal yang berpotensi mengganggu pelanggan Anda. Ingatlah bahwa pengecualian juga merupakan bagian dari API, meskipun dalam C # itu bukan bagian dari dokumentasi metode. Ini mungkin mungkin untuk meningkatkan pengecualian yang dilemparkan di kemudian hari, tetapi Anda akan perlu untuk berbicara dengan pengguna akhir dan melihat apa dampak yang akan terjadi.


0

Saya memiliki daftar periksa untuk penerapan yang mungkin berguna bagi Anda. Saya melakukan pengembangan desktop tetapi beberapa di antaranya harus diterjemahkan. Ini beberapa di antaranya:

Umum:

  • Masukkan cek nol untuk parameter fungsi yang seharusnya tidak nol. Ini membantu saya gagal lebih awal.
  • Hapus komentar yang tidak perlu dan file komentar. Ini menyebabkan pekerjaan di masa depan.
  • Cari komentar "// TODO". Terkadang saya meninggalkan catatan untuk diri saya sendiri. Terkadang saya melupakan mereka.
  • Jalankan tes kode saya menggunakan basis data produksi jika memungkinkan. Ini membantu memastikan saya memiliki semua perubahan database saya di server produksi.
  • Dimasukkan ke dalam penebangan berlebihan. Khusus untuk penyebaran awal. Sebenarnya saya menyimpan logging untuk akhirnya karena kode saya biasanya di-gel beberapa saat ini. Anda tidak ingin berada dalam situasi di mana Anda mengalami tabrakan dan Anda berkata pada diri sendiri, "Seandainya saya tahu berapa nilai X saat ini". Cobalah rencanakan ke depan.
  • Cobalah untuk membungkus panggilan perpustakaan pihak ketiga di Fasad. Ini membuatnya mudah untuk mengubah perpustakaan di masa depan serta memberikan daftar periksa tentang apa yang Anda butuhkan dari perpustakaan.

Khusus Net:

  • Pastikan saya menelepon Buang () pada benda sekali pakai. Saya menggunakan Analisis Kode atau FxCop untuk membantu menemukan kasus ini.
  • Pastikan saya melepas kaitan semua penangan acara dengan benar. Ini mencegah kebocoran memori.
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.