該怎麼開專案的資料夾結構？每個專案應該要有的資料夾結構和檔案

圖片來源：https://pixabay.com/en/key-tag-security-label-symbol-2114047/

每當需要建立一個新的專案的時候，最長遇到的問題就是，我的 資料夾應該怎麼開、有哪些檔案是必須要存在。

對於初學者來說，可能會覺得這有什麼好難的，我就visual studio開起來，然後建立一個專案就可以開始工作了，範例不都是這樣開的嗎？

這個為什麼很重要呢？假設有些必要的檔案沒有建立，除了在開發上會造成負擔（例如缺少git忽略檔案），在之後自己回來看的時候就要花很多時間去找。例如文件在哪裡？專案的變更記錄在哪裡？ci的自動化build script在哪裡？

如果每個專案的結構和內容相近的話，不僅讓找資料更加方便，也能提醒自己有些東西需要補（例如萬惡的文件XD）。

這篇將會介紹每個專案應該要有的資料夾結構和應該要有的檔案，讓未來在建立專案的時候不會忘記。

最後，在實際進入之前，和任何軟體開發一樣，這個有很重的個人喜好（personal preference）在裡面，所以可能和各位習慣不同，由我先拋磚引玉，如果有不同想法和更好建議也歡迎提出來。

關鍵字:專案結構、開專案資料夾、project strcture、特殊檔案

參考的repo：mhat-common-boilerplate-repo

• 好的專案結構的重要性
  
• 可參考的應該要有的專案結構
  
• 應該要有的資料夾結構
  
• build
  
• docs
  
• src
  
• tools
  
• 應該要有的檔案
  
• .gitignore
  
• .gitattributes
  
• README.md
  
• 最好要有的檔案
  
• LICENSE.md
  
• CONTRIBUTING.md
  
• CHANGELOG.md
  
• CODE_OF_CONDUCT.md
  
• ISSUE_TEMPLATE
  
• NEW_PULL_REQUEST
  
• 結語
  

好的專案結構的重要性

在進入正題之前，還是要先說說為什麼這件事情很重要。

先給大家一個例子：我常常在非我自己建立的專案裡面最長發現漏掉的就是 .gitignore檔案 - 這個檔案是git版控會用來忽略不要進入版控的一個設定檔案。沒有這個會造成什麼後果？每一次build之後，一堆bin底下的dll 都會變成有變更。

如果仔細一點的工程師，在commit的時候會知道不要上這些東西，如果commit不看就一股腦就上上去了，造成的後果是不止專案空間比較大，未來在追蹤log的時候有很多雜訊，浪費判斷時間。

同樣，除了和開發有直接關係的這種之外，一些專案訊息類型的也很重要，例如專案的變更記錄 - 請問你怎麼知道1.3版本和1.2版本從功能面差多少？（下面我會在詳細提這個部分） 或者是你這個專案的文件在哪裡？

這些其實都是因為在開專案的時候，專案缺少了好的結構和一些檔案。

可參考的應該要有的專案結構

我有建立了一個github的repo，裡面包含了一個專案應該要有的結構，和每一個檔案裡面應該要有的內容。

• 專案位置：mhat-common-boilerplate-repo

假設你自己要建立一個專案，可以透過以下的powershell指令快速從這個專案下載下來並且init自己的專案結構

git clone https://github.com/alantsai/mhat-common-boilerplate-repo.git
cd mhat-common-boilerplate-repo
rm .git -Recurse -Force
git init
git add -A
git commit -m "init project"

然後改對應檔案的一些內容描述以符合你的專案內容。更詳細介紹可以參考專案的說明

下面會針對裡面的每一個資料夾和檔案做說明。

應該要有的資料夾結構

首先是資料夾的部分，每一個專案至少要有：

• build
• docs
• src
• tools

build

這邊我對build的定義是和建制這個專案有關的一些script檔或者建制過程產生的一些臨時檔案可以放的地方。

我習慣性會把build script例如建立nuget或者執行測試放到一個自己的獨立資料夾，而這裡就是那個地方。

docs

放文件的地方，有些習慣用doc - 不過很多專案都有加s，所以這邊是有加s的版本

原則上任何專案都應該有文件，而文件可以放在另外一個地方，但是最好是用markdown和專案放在一起，這樣也可以順便版控文件

整個結構大概會是：

docs
   |--asset
   |--topic 1
     |--asset
     |--sub topic 1
       |--...
     |--README.md
   |-README.md
   |-SUMMARY.md

說明一下：

asset

這個資料夾用來放markdown裡面用到的圖片或者檔案 - 方便鏈接過去

README.md

這個是每一個chapter或者每一個部分的起始頁，有點類似index.html在網站的地位

SUMMARY.md

這個則是整個文件的目錄的概念

src

這個就是主要放程式碼的地方，有些專案會叫他lib或app。

裡面的資料結構大概會是：

src
   |--{project name}.Bll
   |--{project name}.Web
   |-- ...
   |-{project name}.sln

說明一下：

{project name}

這個指的是專案名稱，例如假設我今天有一個xxx專案的網站，那麼我就會有 xxx.Bll作為bll層的csproj位置，xxx.Web作為網站的csproj位置。

{project name}.sln

src進去之後的唯一檔案就是他，這樣不僅很明確如何開啟這個專案，如果有多個sln也不會混在一起

一般我在開專案的時候，我建立的都會是一個blank solution（只有sln） - 然後我會把它手動拉倒src下面，這樣之後建立的csproj專案的結構就會像描述那樣。

tools

這個資料夾我會放一些工具類的內容。例如說網站都要套版，ui就會放在裡面。

假設有用到一些第三方的dll或者exe也可以放在這邊

以上是關於資料夾結構的部分，也可以參考一些說明像是Folder-Structure-Conventions這個專案就是在介紹這些內容。

應該要有的檔案

介紹完應該要有的資料夾結構，接下來就是檔案啦，一定要有的會有：

1. .gitignore
2. .gitattributes
3. README.md

.gitignore

.gitignore基本上就是git的忽略檔案 - 忽略那些不要進入版控的檔案。

這個為什麼重要？除了可以讓git的repo小一點之外，也可以避免每一次commit看到一堆修改，或者是在追log的時候看到一些“雜訊”。

什麼才應該commit到git裡面？基本上只要是可以 重新建立出來的都應該進入忽略檔案。例如build出來的bin檔案。

在github上面有個專案專門放那些語言和環境應該忽略什麼https://github.com/github/gitignore。我這邊的gitignore也是組合這個repo裡面的內容。

.gitattributes

這個檔案能夠設定git在操作某些檔案的時候要做那些處理。

為什麼重要？還記得之前有一篇介紹關於斷行的問題：[git]為什麼常出現有修改但是比對不卻顯示不出差異？談談檔案斷行問題和如何達到不同平台正確一致化

README.md

這個檔案就好比以前一包html裡面index.html的概念 - 所有資訊的入口都在這個檔案。

為什麼重要？如果沒有一個入口，根本無法快速上手這個專案。尤其目前各個git host都會預設呈現這個檔案的內容。

在這個檔案裡面，一般來說會有幾個內容：

介紹專案的目的

每個專案都有特定目的，介紹清楚可以讓後來看的時候馬上知道這個專案是不是你在找的那個專案。

專案狀態的badge

例如目前最新版本的build狀態，還是透過gitter溝通的網址，這些都可以用badge快速呈現讓使用者一看知道一些資訊。

badge可以參考http://shields.io/

如何快速上手

怎麼讓人能夠快速使用這個專案，例如透過nuget安裝然後使用

其他資訊的鏈接

例如要看文件提供一個鏈接連到docs的README.md檔案；看變更記錄提供鏈接到對應檔案。

網路上蠻多README.md的範例（例如這個https://github.com/fraction/readme-boilerplate）大家都可以參考一下

我專案的ReadMe裡面都有說明每一個部分應該寫的內容。

最好要有的檔案

接下來介紹的檔案都是最好要有類型的檔案，有些可能和open source比較有關，所以不一定都會放，但是和大家做個極少。

題外話，這些特殊類型的檔案預設都會是全大寫，例如README.md，不過也沒有一定規定，所以還是看個人喜好。

總共會介紹：

• LICENSE.md
• CONTRIBUTING.md
• CHANGELOG.md
• CODE_OF_CONDUCT.md
• ISSUE_TEMPLATE
• NEW_PULL_REQUEST

LICENSE.md

這個很明顯就是open source專案會用到的，明確告訴使用者你的授權模式。

一般來說，如果只是希望版權是你的，但是允許大家做任何修改並且沒有其他限制，那麼MIT最適合。

MIT的license很簡單，就是一段話，把名字改成自己的的名字和年份改成對應年份就好。

1. 如果不知道該選什麼作為license，可以參考github建立的一個網站：https://choosealicense.com/
2. 其他相關資訊可以參考：lisense opensource project、 Licensing a repository

提醒大家，我不是法律人士，所以對這種授權也可能理解有錯，所以如果你對於你的授權有疑慮，最好還是請教相關的法律專業人士。

CONTRIBUTING.md

這個檔案基本上是介紹如何貢獻到你的專案。

貢獻有很多形式，例如：

1. 翻譯
2. 寫文件
3. 改code - 介紹如何build和改code

這邊也可以提供一些專案目標（roadmap）的資訊，讓其他人知道你的目標。

也可以提到一些這個專案不接受什麼貢獻，避免有人不清楚一直問。

更多參考資訊：

1. writing有人contributing guidelines
2. contributing template
3. Mozila contributing guidelines
4. github contributing guidelines

CHANGELOG.md

專案的變更記錄檔案。

這個檔案為什麼重要？

是否能夠讓人家一眼了解版號之間變更的主要目的就是這個檔案要傳達的消息。

和git的log有什麼差別？

切記，git log是細部的說明每次調整什麼，但是這個檔案則是從大局來看到底變動了什麼，所以他絕對不是git log貼上去就好。

github 的 release不就可以寫說明，幹嘛還要有這個檔案？

github release非常巧妙的利用了git tag的資訊讓大家方便找每一個release，但是問題是 假設今天你的repo要搬到別的地方去呢，假設那個hosting不支援release的時候要怎麼辦？因此這個檔案提供一種萬用（universal）資訊的提供位置。

這個檔案應該些什麼？

基本上，每一個版號會有個時間記錄，然後這個版號下面會有 對應的 變更類型（Added、Changed、Deprecated、Removed、Fixed和 Security）

更多關於格式的部分可以參考：Keep a changelog（也有中文，進去右上角可以切換語言，提供英文鏈接因為是最新內容）

CODE_OF_CONDUCT.md

這個是大家在這個repo合作的合作公約。

不過說實話，我個人覺得意義比較沒那麼大，所以我的範例repo沒有放。

相關資訊可以參考：https://opensource.guide/code-of-conduct/

ISSUE_TEMPLATE

這個是github上面才會吃的檔案，當使用者建立一個issue，會有一個範本跑出來。這個檔案就是定義範本內容。

詳細資訊參考github：https://github.com/blog/2111-issue-and-pull-request-templates

NEW_PULL_REQUEST

一樣是github上面才會吃的檔案，當使用者建立一個pull request呈現的內容，這個範本就是定義那些內容。

詳細資訊參考github：https://github.com/blog/2111-issue-and-pull-request-templates

以上就是這些特殊檔案的說明。其他參考資訊：https://github.com/kmindi/special-files-in-repository-root

結語

這篇介紹了專案應該要有的結構和一些特殊檔案的使用說明。希望未來對於大家在建立專案的時候有幫助。

當然，這個和個人喜好有非常大的關係，所以由我先和大家拋磚引玉一下，也希望大家給我一些回饋。

標籤: Git,C#,FAQ,best practices