Pertanyaan yang diberi tag «documentation»

Banyak orang mengklaim bahwa "komentar harus menjelaskan 'mengapa', tetapi tidak 'bagaimana'". Yang lain mengatakan bahwa "kode harus mendokumentasikan diri sendiri" dan komentar harus langka. Robert C. Martin mengklaim bahwa (diucapkan dengan kata-kata saya sendiri) sering "komentar adalah permintaan maaf untuk kode yang ditulis dengan buruk". Pertanyaan saya adalah sebagai berikut: …

236 programming-practices  documentation  comments 

Saya telah secara khusus diminta untuk memberikan penjelasan atau komentar per baris (atau yang sesuai - misalnya, gambar per gambar, dll.) Yang ingin dibaca dan diikuti oleh bos saya. Karena dia bukan seorang programmer, dia tidak bisa mengikuti kode sehingga ingin semuanya diterjemahkan ke dalam bahasa Inggris. Adakah yang pernah …

155 documentation 

RFC 2606 standar mencadangkan nama domain example.org , example.net dan example.com untuk tujuan digunakan sebagai contoh dalam dokumentasi. Apa yang setara dengan nomor telepon (termasuk kode negara) yang dapat digunakan sebagai contoh, misalnya untuk memberikan contoh kepada pengguna dalam format apa untuk memasukkan nomor telepon? Dalam kasus terbaik, itu akan …

112 documentation  standards  help-documentation 

Misalkan saya sedang mengembangkan proyek yang relatif besar. Saya sudah mendokumentasikan semua kelas dan fungsi saya dengan Doxygen, namun, saya punya ide untuk meletakkan "catatan programmer" pada setiap file kode sumber. Gagasan di balik ini adalah untuk menjelaskan dalam istilah awam bagaimana kelas tertentu bekerja (dan tidak hanya mengapa seperti …

104 documentation  large-scale-project 

Selama pertemuan mengenai kemunduran SDK pihak ketiga dari versi terbaru, dicatat bahwa pengembang kami telah menandai dalam komit sejarah bahwa versi terbaru tidak boleh digunakan. Beberapa pengembang berpendapat bahwa ini adalah praktik yang buruk dan seharusnya dicatat dalam file sumber (yaitu // Don't upgrade SDK Version x.y.z, see ticket 1234) …

94 version-control  documentation 

Saya mengerjakan proyek yang cukup besar dan mendapat tugas untuk melakukan beberapa terjemahan untuknya. Ada banyak label yang belum diterjemahkan dan ketika saya sedang menggali kode, saya menemukan sepotong kode ini //TODO translations Ini membuat saya berpikir tentang arti dari komentar-komentar ini untuk diri Anda sendiri (dan yang lainnya?) Karena …

86 documentation  comments 

Saya menulis kode berikut: if (boutique == null) { boutique = new Boutique(); boutique.setSite(site); boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo()); boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl()); boutique.setNom(fluxBoutique.getNom()); boutique.setSelected(false); boutique.setIdWebSC(fluxBoutique.getId()); boutique.setDateModification(new Date()); boutiqueDao.persist(boutique); } else { boutique.setSite(site); boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo()); boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl()); boutique.setNom(fluxBoutique.getNom()); //boutique.setSelected(false); boutique.setIdWebSC(fluxBoutique.getId()); boutique.setDateModification(new Date()); boutiqueDao.merge(boutique); } Ada garis komentar di sini. Tapi saya pikir itu membuat kode lebih jelas, dengan memperjelas …

83 documentation  comments 

Pertama-tama, dalam pertanyaan ini saya ingin menjauh dari polemik apakah komentar kode sumber itu baik atau buruk. Saya hanya mencoba memahami dengan lebih jelas apa yang dimaksud orang ketika mereka berbicara tentang komentar yang memberi tahu Anda MENGAPA, APA atau BAGAIMANA. Kita sering melihat pedoman seperti "Komentar harus memberi tahu …

78 documentation  comments 

Saya mengerjakan sebuah proyek tiga bulan lalu, dan kemudian tiba-tiba proyek mendesak lainnya muncul dan saya diminta untuk mengalihkan perhatian saya. Mulai besok, saya akan kembali ke proyek lama. Saya menyadari bahwa saya tidak ingat apa yang sebenarnya saya lakukan. Saya tidak tahu harus mulai dari mana. Bagaimana saya bisa …

72 project-management  documentation 

Saya berencana meninggalkan pekerjaan saya saat ini karena kami terkunci dalam menggunakan Blub , dengan kerangka kerja perusahaan Blub dan server web tingkat-Blub, pada hosting bersama yang biasa-biasa saja. Rekan kerja saya ramah dan bos saya rata-rata pemilik usaha kecil - saya ingin pergi sepenuhnya karena alasan teknis. Saya merasa …

66 career-development  documentation 

Saya mengerti pentingnya kode yang terdokumentasi dengan baik. Tetapi saya juga memahami pentingnya kode dokumentasi diri . Semakin mudah membaca fungsi tertentu secara visual, semakin cepat kita dapat melanjutkan selama pemeliharaan perangkat lunak. Dengan itu, saya suka memisahkan fungsi besar menjadi yang lebih kecil. Tapi saya melakukannya ke titik di …

63 programming-practices  code-quality  documentation 

Pembuatan dokumentasi otomatis dapat dilakukan dengan berbagai alat, GhostDoc menjadi salah satu yang lebih menonjol. Namun, menurut definisi, semua yang dihasilkannya berlebihan. Dibutuhkan melihat nama-nama metode, kelas, dll dan keluaran bahasa Inggris yang mungkin menjelaskannya lebih jelas. Dalam kasus terbaik, ia melakukan apa yang sudah dapat dilakukan oleh pembaca di …

60 documentation  automation  automatic-programming 

Saya menulis dokumentasi pengguna (SOP) yang melibatkan program pihak ketiga yang saya coba gambarkan dengan baik. Salah satu program tersebut adalah server yang menawarkan sedikit indikasi startup itu selain grafik yang menunjukkan selama rutin inisialisasi / startup. Sebagai pengembang, saya telah menggunakan jendela ini sebagai indikator status cepat dan saya …

59 documentation  component  jargon 

Kadang-kadang saya menemukan diri saya dalam situasi ketika bagian dari kode yang saya tulis adalah (atau tampaknya ) sangat jelas sehingga namanya pada dasarnya akan diulang sebagai komentar: class Example { /// <summary> /// The location of the update. /// </summary> public Uri UpdateLocation { get; set; }; } (Contoh …

54 programming-practices  documentation  language-agnostic 

Ketika Anda menggunakan alat-alat seperti jsdocs , itu menghasilkan file HTML statis dan gayanya di basis kode Anda berdasarkan komentar dalam kode Anda. Haruskah file-file ini diperiksa ke dalam repositori Git atau haruskah mereka diabaikan dengan .gitignore?

49 git  documentation