Cara mengatur fail dengan betul di codebase anda & elakkan keganasan

Organisasi dan penyelenggaraan pangkalan kod besar: perpustakaan utama, data, UI, dokumentasi dan wiki, ujian, komponen warisan dan komponen pihak ketiga ... bagaimana untuk mengesan dan mengekalkan susunan semua kandungan ini? Organisasi fail dalam kod boleh menjadi tugas yang sukar.

Jangan risau - kita boleh melakukannya! Artikel ini akan mengkaji sistem yang paling biasa digunakan untuk projek-projek kecil dan besar dan menyediakan beberapa amalan terbaik yang mudah diikuti.

mata utama

Mengatur fail di pangkalan kod anda dapat mengurangkan masalah dan menjimatkan masa apabila anda perlu mengakses dan mengkaji semula kandungan pada masa akan datang. Adalah sangat penting untuk menubuhkan peraturan asas untuk penamaan fail, pemprosesan dokumentasi projek, dan organisasi aliran kerja yang berkesan.
Setiap projek perisian harus mempunyai readme, changelog, salinan lesen dan fail .gitignore. Bergantung pada situasi projek, fail lain seperti penulis, pepijat, penyumbang/penggodaman, FAQ, pemasangan, berita, terima kasih, todo/roadmap, versi/pelepasan juga boleh dimasukkan.
Fail hendaklah dianjurkan ke dalam folder komponen atau subsistem, tetapi direktori harus diwujudkan untuk memastikan perkara yang boleh diurus. Jenis fail tertentu, seperti data, fail binari, dan tetapan, harus dikecualikan daripada projek.
Kunci untuk dokumen organisasi terletak pada konsistensi. Sama ada penamaan direktori atau fail, atau struktur sesuatu projek, mengekalkan konsistensi menjadikan asas kod lebih mudah untuk menavigasi dan memahami.

Mengapa bersusah payah?

Seperti hampir semua tugas yang berkaitan dengan pengurusan projek, dokumentasi, penyerahan perisian, penempatan-anda akan mendapat manfaat yang besar dari pendekatan yang sedar dan programatik.

Ini bukan sahaja akan mengurangkan masalah semasa, tetapi juga akan menjimatkan masa anda dan masa anda yang berharga apabila kandungan perlu diakses dengan cepat dan dikaji semula pada masa akan datang. Anda pasti dapat mengingat nama fungsi apa sahaja yang anda tulis sekarang dan dengan cepat mencari fail yang anda perlukan untuk mengedit dan jelas memberitahu apa yang berfungsi dan apa yang tidak - atau apa yang anda fikirkan demikian. Tetapi, bolehkah anda mengatakan perkara yang sama mengenai projek yang anda kerjakan pada tahun lepas?

Mari kita mengakui: Projek -projek perisian mungkin berlangsung selama berbulan -bulan atau bahkan tahun tidak aktif. Fail ReadMe yang mudah boleh melakukan banyak perkara untuk rakan sekerja atau masa depan anda. Tetapi mari kita pertimbangkan cara lain, anda boleh membina projek dan membina beberapa peraturan asas untuk menamakan fail, memproses dokumentasi projek, dan sedikit sebanyak mengatur aliran kerja yang berkesan yang menjadi ujian masa.

Memahami perkara kami akan menubuhkan "asas" untuk dokumen dalam projek organisasi - logik yang akan memberi kami dalam banyak situasi dalam skop pembangunan perisian.

Seperti peraturan kami mengenai penyerahan perubahan kod dengan betul, tidak satu pun dari ini ditetapkan dalam batu, dan, dari segi nilai mereka, anda dan pasukan anda boleh mencadangkan prinsip panduan yang berbeza. Bagaimanapun, konsistensi

adalah nama permainan. Pastikan anda memahami (dan membincangkan atau membantah) apakah peraturannya dan mengikutinya selepas konsensus dicapai.

Dokumen yang diperlukan

Ini adalah senarai rujukan fail yang hampir setiap projek perisian harus mempunyai:

• Readme: Ini adalah apa yang diberikan oleh GitHub untuk anda di bawah pokok sumber, yang dapat membantu menjelaskan kandungan projek, bagaimana fail -fail itu dianjurkan, dan di mana untuk mencari maklumat lanjut. Changelog: Menyenaraikan kandungan baru, diubahsuai, atau dilumpuhkan dalam setiap versi atau semakan-biasanya untuk kemudahan, dalam susunan anti-kronologi (perubahan terkini berada di barisan hadapan).
• Lesen Penyalinan: Fail yang mengandungi teks penuh lesen yang meliputi perisian, dan, jika perlu, beberapa maklumat hak cipta lain (seperti lesen pihak ketiga).
• .Gitignore: Dengan mengandaikan anda menggunakan git (yang kemungkinan besar anda gunakan), ini juga perlu untuk memberitahu fail mana yang tidak disegerakkan dengan repositori. .
• penyokong

Bergantung pada situasi projek, anda juga mungkin ingin mempertimbangkan termasuk beberapa dokumen lain:

Pengarang: Atribusi orang yang terlibat dalam menulis kod.

Bugs: Isu dan arahan yang diketahui untuk melaporkan kesilapan baru yang dijumpai.
Menyumbang/Hacking: Panduan untuk penyumbang yang berpotensi, terutamanya berguna untuk projek sumber terbuka.
FAQ: Anda sudah tahu apa ini. ;)
Pasang: Arahan tentang cara menyusun atau memasang perisian pada sistem yang berbeza.
Berita: Sama seperti fail Changelog, tetapi untuk pengguna akhir, bukan pemaju.
Terima kasih: Terima kasih.
Todo/Roadmap: Senarai ciri -ciri yang akan datang yang dirancang.
versi/pelepasan: Barisan kod yang menerangkan nombor versi atau nama pengedaran semasa.
• folder komponen atau subsistem

kita sering menghadapi satu set fungsi yang boleh digabungkan menjadi satu konsep.

beberapa contoh mungkin:

Pengantarabangsaan (I18N) dan Penyetempatan (L18N)

Modul Pengesahan
add-ons pihak ketiga
Alat Umum dan Tugasan Cron
antara muka pengguna (UI) dan antara muka pengguna grafik (GUI)
• Semua ini boleh dianjurkan menjadi direktori "komponen" atau "subsistem" tunggal -tetapi jangan gila!

Kami mahu menyekat penciptaan direktori untuk memastikan perkara yang boleh diurus, sama ada dalam direktori root (komponen utama akan ditempatkan di sini) atau rekursif (dalam setiap direktori). Jika tidak, kami mungkin menghabiskan banyak masa secara rutin melayari fail dalam direktori yang teratur.

sila tidak termasuk ini

dari pokok sumber

Walaupun kami mahu projek itu kemas dan teratur, terdapat beberapa dokumen yang kami mahu dikecualikan sepenuhnya dari projek.

data. Anda mungkin tergoda untuk mempunyai data/direktori di pokok sumber untuk fail CSV, dan lain -lain, terutamanya jika mereka hanya mengambil beberapa kilobytes. Tetapi bagaimana jika mereka mengambil megabait atau gigabait (yang tidak biasa hari ini)? Adakah anda benar -benar mahu menghantar ini

ke kod anda seperti yang anda lakukan dengan asas kod anda? Tidak

fail binari. Anda tidak mahu video rendering atau executable yang disusun terletak di sebelah kod sumber. Ini bukan fail pembangunan, mereka tidak berada di sini sama sekali. Seperti fail data, mereka mungkin mengambil banyak ruang.

Tetapan. Ini adalah satu lagi tabu besar. Anda tidak boleh meletakkan kelayakan, kata laluan, atau token keselamatan di pangkalan kod anda. Kami tidak dapat menampung penyelesaian kepada masalah ini di sini, tetapi jika anda seorang pemaju Python, pertimbangkan untuk menggunakan Python Decouple.

Kes 1: Aplikasi Web

mari kita pertimbangkan aplikasi web -perisian yang berjalan pada pelayan web yang boleh anda akses melalui penyemak imbas, sama ada pada desktop atau peranti mudah alih. Dan dengan mengandaikan ia adalah aplikasi web yang menyediakan keahlian untuk mengakses beberapa jenis perkhidmatan premium -laporan eksklusif, petua perjalanan, atau perpustakaan video.

Struktur fail

<code>├── .elasticbeanstalk
├── .env
├── billing
├── changelog.txt
├── locale
│   ├── en
│   └── zh_Hans
├── members
├── readme.txt
├── static
│   ├── fonts
│   ├── images
│   ├── javascript
│   └── styles
├── templates
│   ├── admin
│   └── frontend
├── todo.txt
└── tools</code>

Analisis

Ini adalah struktur aplikasi web asas dengan sokongan untuk dua bahasa (Bahasa Inggeris dan Cina yang dipermudahkan (Direktori Locale). Terdapat juga dua komponen utama, pengebilan dan ahli.

Jika anda lebih akrab dengan perkembangan laman web, kandungan folder statik dan templat mungkin kelihatan biasa. Mungkin satu-satunya elemen yang luar biasa mungkin. ElasticBeAnStalk, yang menyimpan fail penempatan untuk Amazon Web Services (AWS), dan .Env, yang hanya menyimpan tetapan untuk projek di premis seperti kelayakan pangkalan data. Selebihnya, seperti Readme dan Todo, kami telah membincangkannya. Direktori Alat adalah direktori yang menarik. Di sini kita boleh menyimpan skrip, sebagai contoh, memotong pangkalan data, periksa status pembayaran, atau membuat fail statik ke cache -pada dasarnya, apa -apa yang bukan aplikasi itu sendiri tetapi membantu menjadikannya berfungsi.

Mengenai penamaan, jika kita namakan direktori imej sebagai imej/ atau img/, atau namakan direktori gaya sebagai gaya/ atau css/, atau namakan JavaScript/ direktori sebagai JS/, tidak ada perbezaan. Perkara utama ialah strukturnya adalah logik, dan kami sentiasa mengikuti konvensyen tertentu, sama ada nama deskriptif yang panjang atau yang pendek.

Kes 2: Aplikasi Desktop

Marilah kita pertimbangkan aplikasi yang boleh anda muat turun dan pasang di komputer anda. Dan anggap aplikasi memerlukan beberapa input, seperti fail CSV, dan kemudian memberikan beberapa laporan.

Dalam contoh ini, kita akan menjadikan pokok sumber sedikit lebih besar.

Struktur fail

Analisis

<code>├── .gitignore
├── data
├── doc
├── legacy
│   ├── dashboard
│   ├── img
│   └── system
├── LICENSE
├── README
├── tests
├── thirdparty
├── tools
│   ├── data_integration
│   └── data_scraping
├── ui
│   ├── charts
│   ├── css
│   ├── csv
│   ├── dashboard
│   ├── img
│   │   └── icons
│   ├── js
│   ├── reports
│   └── summaries
├── VERSION
└── wiki</code>

ui/folder pada dasarnya adalah teras aplikasi. Nama subfolder hampir jelas (satu lagi kebiasaan yang baik). Tidak seperti contoh aplikasi web kami, di sini kami memilih nama singkatan (mis. JS bukan JavaScript). Sekali lagi, apa yang penting ialah kita konsisten merentasi projek.

Sebelum ini, saya mencadangkan tidak termasuk fail data dari pokok sumber, tetapi terdapat data/folder di sana. Bagaimana mungkin ini berlaku? Fikirkan pokok ini sebagai kotak pemaju yang memerlukan data untuk menguji aplikasi dengan betul. Walau bagaimanapun, data masih belum keluar dari penyegerakan repositori, berikutan peraturan yang ditetapkan dalam fail .gitignore.

Legacy/ Folder digunakan untuk sebahagian daripada aplikasi yang akan dihentikan, tetapi masih menyediakan beberapa ciri yang mungkin berguna sehingga ia sepenuhnya refactored ke dalam sistem baru. Oleh itu, ia menyediakan cara yang baik untuk memisahkan kod lama dari kod semasa.

Penambahan baru di sini adalah ujian/, yang menyediakan tempat untuk memastikan kualiti menggunakan ujian unit, dan ThirdParty/, tempat untuk menyimpan perpustakaan luaran yang diperlukan oleh perisian.

Perhatikan bahawa terdapat doc/ dan wiki/ folder, yang mungkin kelihatan seperti pendua. Walau bagaimanapun, ia juga mungkin mempunyai folder dokumen untuk pengguna akhir dan wiki untuk pasukan pembangunan - walaupun munasabah.

Ringkasan

Berita baik yang patut diulangi adalah: walaupun anda bekerja sendiri, anda mesti dianjurkan. Mudah -mudahan artikel ini memberikan anda beberapa idea yang anda boleh mula memohon kepada aliran kerja anda dengan segera untuk mengelakkan kekeliruan kerana bilangan fail dalam permohonan anda meningkat.

Seperti yang dinyatakan sebelum ini, garis panduan mungkin berubah dari semasa ke semasa, kerana (hampir) setiap projek adalah berbeza, dan begitu juga pasukan. Idealnya, anda atau pasukan anda akan memutuskan bagaimana untuk membina projek - menambah dokumen kecil untuk menggambarkan sebab -sebab struktur ini - dan kemudian anda akan melekat pada peraturan ini dari sekarang.

ingat bahawa untuk banyak garis panduan di sini, tidak kira jika anda memilih dash atau garis bawah untuk menamakan fail (pilih salah satu daripada banyak topik). Kuncinya adalah konsistensi.

bacaan selanjutnya

• Struktur projek dari "Python Geting Starting Guide".
• Kaedah sistem untuk menguruskan struktur folder projek dari UX Collective.
• Pengurusan Projek Berkesan: Tradisional, Agile, Extreme, Hybrid

Soalan Lazim Mengenai Penganjuran Dokumen Projek (FAQ)

Apakah faedah menganjurkan dokumen projek dengan cara berstruktur?

Terdapat banyak manfaat menganjurkan dokumen projek dengan cara berstruktur. Pertama, ia meningkatkan kebolehbacaan dan pemeliharaan kod. Apabila fail dianjurkan secara logik, lebih mudah bagi pemaju untuk memahami asas kod dan membuat perubahan tanpa melanggar fungsi sedia ada. Kedua, ia meningkatkan kerja berpasukan. Apabila pelbagai pemaju bekerja pada projek yang sama, struktur fail yang teratur memastikan semua orang tahu di mana untuk mencari coretan tertentu. Akhirnya, ia mempercepatkan proses pembangunan. Pemaju menghabiskan lebih sedikit masa mencari fail dan lebih banyak masa menulis dan mengoptimumkan kod.

Bagaimana untuk menentukan struktur optimum fail projek?

Struktur optimum fail projek bergantung kepada sifat dan kerumitan projek. Untuk projek kecil, struktur direktori mudah mungkin cukup. Walau bagaimanapun, untuk projek yang lebih besar dengan pelbagai komponen, anda mungkin memerlukan struktur yang lebih kompleks. Pertimbangkan faktor seperti bahasa pengaturcaraan yang anda gunakan, rangka kerja atau perpustakaan yang anda gunakan, dan keutamaan pasukan. Adalah penting untuk menjadikan struktur fleksibel supaya ia dapat berkembang apabila projek berkembang.

Apakah beberapa strategi umum untuk menganjurkan kod?

Terdapat beberapa strategi untuk menganjurkan kod. Kaedah yang sama adalah untuk kumpulan fail mengikut fungsi. Ini bermakna semua fail yang berkaitan dengan fungsi tertentu disimpan dalam direktori yang sama. Cara lain adalah untuk kumpulan fail mengikut jenis, seperti pemisahan CSS, JavaScript, dan fail HTML ke dalam direktori yang berbeza. Sesetengah pemaju lebih suka menggunakan pendekatan hibrid, menggabungkan unsur -unsur kedua -dua strategi. Kuncinya ialah memilih strategi yang masuk akal untuk projek dan pasukan anda.

Bagaimana mengekalkan organisasinya sebagai asas kod tumbuh?

Apabila asas kod berkembang, adalah penting untuk memeriksa dan refactor struktur fail secara berkala. Ini mungkin termasuk memisahkan fail besar ke dalam fail yang lebih kecil, lebih mudah diurus, atau menyusun semula direktori untuk lebih mencerminkan keadaan semasa projek. Alat automasi boleh membantu mengenal pasti kawasan di pangkalan kod yang menjadi canggung atau sukar untuk dijaga. Ulasan kod biasa juga boleh membantu memastikan kod baru mematuhi struktur fail yang ditubuhkan.

Peranan apa yang menamakan konvensyen dalam organisasi fail?

Penamaan konvensyen memainkan peranan penting dalam organisasi dokumen. Konsisten, nama fail deskriptif memudahkan untuk memahami apa yang setiap fail terkandung sekilas. Ini boleh mempercepatkan proses pembangunan, terutamanya apabila berurusan dengan projek besar atau bekerja dengan pasukan. Konvensyen penamaan harus dipersetujui pada permulaan projek dan sentiasa tetap konsisten.

Bagaimana untuk memastikan semua ahli pasukan mengikuti strategi organisasi fail saya?

Untuk memastikan semua ahli pasukan mengikuti dasar organisasi fail anda, adalah penting untuk mendokumenkan dasar anda dengan jelas dan menjadikan dokumen itu dapat diakses. Kajian kod biasa juga boleh membantu menguatkuasakan dasar. Juga, pertimbangkan untuk menggunakan alat automasi yang boleh menyemak sama ada ia mematuhi peraturan organisasi dokumen anda.

Bolehkah saya menukar dasar organisasi fail saya di pertengahan projek?

Ya, anda boleh menukar dasar organisasi fail di pertengahan projek, tetapi ini perlu dilakukan dengan berhati -hati untuk mengelakkan mengganggu aliran kerja. Sebelum membuat apa -apa perubahan, bincangkan strategi baru yang dicadangkan dengan pasukan anda dan pastikan semua orang memahami sebab -sebab perubahan dan cara melaksanakannya. Adalah penting untuk mengemas kini sebarang dokumen yang berkaitan untuk mencerminkan dasar baru.

Bagaimana menangani kebergantungan semasa menganjurkan fail projek?

Apabila menganjurkan fail projek, pengendalian kebergantungan boleh menjadi cabaran. Salah satu cara adalah untuk menyelamatkan semua kebergantungan dalam direktori berasingan. Ini menjadikannya lebih mudah untuk mengurus dan mengemas kini mereka. Sesetengah bahasa pengaturcaraan dan pengurus pakej juga menyediakan alat untuk menguruskan kebergantungan yang mengautomasikan kebanyakan proses.

Apakah kesilapan biasa yang harus dielakkan semasa menganjurkan fail projek?

Beberapa kesilapan umum yang harus dielakkan apabila menganjurkan fail projek termasuk: tidak merancang struktur fail terlebih dahulu, tidak mengikuti konvensyen penamaan yang konsisten, tidak merakam dasar organisasi fail, dan pemeriksaan tidak teratur dan refactoring struktur fail. Mengelakkan kesilapan ini boleh membantu mengekalkan asas kod yang kemas, teratur, dan mudah dinavigasi.

Bagaimana untuk mengetahui lebih lanjut mengenai amalan terbaik dalam organisasi dokumen?

Terdapat banyak sumber yang tersedia untuk mempelajari amalan terbaik untuk organisasi dokumen. Tutorial dalam talian, bootcamp pengekodan dan forum pemaju boleh memberikan pandangan yang berharga. Di samping itu, mengkaji struktur folder projek sumber terbuka dapat memberikan contoh praktikal bagaimana untuk menganjurkan fail projek dengan berkesan.

Atas ialah kandungan terperinci Cara mengatur fail dengan betul di codebase anda & elakkan keganasan. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!