Part 13 - 實戰應用：程式碼文件
🏠 課程首頁 📘 FB 🎥 YT

GitHub Copilot 完整教學

Part 13：實戰應用 - 程式碼文件

用 Copilot 自動產生註解和文件

/doc 指令 Docstring README

🎯 本單元學習目標

完成這個單元後，你將能夠：

1. 使用 /doc 指令

為函式自動產生 docstring 文件

2. Chat 產生註解

請 Copilot 加上中文註解說明

3. 行內註解

為每一行程式碼加上說明

4. 產生 README

為專案產生說明文件

核心觀念：好的文件讓程式碼更容易理解、維護和協作！

📖 為什麼需要程式碼文件？

👀 提高可讀性

讓其他人快速理解
程式碼在做什麼

🔧 方便維護

半年後的自己
也能看懂當初的程式

🤝 團隊協作

新成員加入時
能快速上手專案

📚 知識傳承

程式碼的邏輯和決策
被完整記錄下來

痛點：手動寫文件很花時間，而且常常忘記更新！Copilot 可以幫你快速產生。

📑 程式碼文件的層級

行內註解

# 單行說明

→

函式文件

Docstring

→

檔案說明

模組文件

→

專案文件

README.md

Copilot 可以產生所有層級的文件：
  • /doc - 產生函式 docstring
  • Chat 對話 - 產生行內註解、檔案說明
  • @workspace - 產生專案 README

📝 方法一：使用 /doc 產生文件

操作步驟

  1. 在編輯器中選取一個沒有 docstring 的函式
  2. 開啟 Copilot Chat（Ctrl + Alt + I）
  3. 輸入 /doc
  4. 按 Enter 送出
使用 /doc

選取函式後，在 Chat 中輸入 /doc

📋 /doc 產生的 Docstring

/doc 產生的文件

Copilot 自動產生完整的 docstring

Docstring 通常包含：
  • 函式用途說明
  • 參數說明（Args / Parameters）
  • 回傳值說明（Returns）
  • 使用範例（Examples）- 有時會有

💬 方法二：Chat 詢問產生註解

操作步驟

  1. 選取一段尚未有完整註解的程式碼
  2. 開啟 Copilot Chat
  3. 輸入請求
請為這段程式碼加上詳細的中文註解
Chat 產生註解

請 Copilot 加上中文註解

📌 方法三：行內註解

操作步驟

  1. 選取一段邏輯較複雜的程式碼
  2. 在 Chat 中輸入請求
請在每一行加上註解說明
行內註解

Copilot 為每一行加上註解

使用時機：複雜的演算法、不直覺的邏輯、需要特別說明的程式碼

📚 Python Docstring 格式

風格 特點 範例
Google 簡潔易讀，最常用 Args: / Returns:
NumPy 科學計算領域常用 Parameters / Returns
Sphinx 適合產生 API 文件 :param: / :return:
指定格式：在 Chat 中說明你要的格式，例如：
請用 Google 風格為這個函式產生 docstring

📄 為整個檔案產生文件

操作方式

使用 #file: 或 @workspace 參照檔案：

#file:practice9.py 請說明這個檔案的功能和結構

或：

@workspace 請為這個專案的主要檔案產生文件說明
檔案文件

產生檔案層級的說明文件

📘 產生 README 文件

操作方式

請 Copilot 為專案產生 README：

請為這個專案產生一個 README.md 文件

或：

@workspace 請產生專案說明文件
README 文件

Copilot 產生的 README 內容

README 通常包含：專案名稱、說明、安裝方式、使用方法、範例等

💡 文件撰寫技巧

1. 清楚

說明「做什麼」而非「怎麼做」
程式碼本身就說明了怎麼做

2. 簡潔

不要重複程式碼已經表達的
避免冗長的說明

3. 完整

參數、回傳值、例外情況
都要說明清楚

4. 保持更新

程式碼改了，文件也要改
過時的文件比沒有還糟

注意：Copilot 產生的文件要檢查，確保內容正確且符合你的需求！

🏋️ 實作練習

練習目標：使用 Copilot 為程式碼產生各層級的文件

練習步驟

  1. 開啟之前的練習檔案（practice9.py）
  2. 選取一個沒有 docstring 的函式，使用 /doc 產生文件
  3. 選取一段程式碼，請 Copilot 加上中文註解
  4. 選取複雜邏輯，請 Copilot 加上行內註解
  5. 使用 #file: 為整個檔案產生說明
  6. 嘗試產生 README.md 文件
進階挑戰：
  • 嘗試指定 docstring 格式（Google / NumPy）
  • 請 Copilot 產生英文版文件

📝 隨堂測驗

問題 1：在 Copilot Chat 中，哪個指令可以為函式產生 docstring？

A. /comment
B. /doc
C. /document
D. /readme

問題 2：想讓 Copilot 為特定檔案產生說明，應該使用？

A. @file:檔名
B. #file:檔名
C. /file:檔名
D. $file:檔名

問題 3：Python 中最常用的 docstring 風格是？

A. Microsoft 風格
B. Google 風格
C. Apple 風格
D. Amazon 風格

✅ 測驗解答

問題 1 答案：B

/doc 是 Copilot Chat 用來產生函式 docstring 文件的指令。選取函式後輸入 /doc，Copilot 會自動產生包含參數說明、回傳值等的完整文件。

問題 2 答案：B

#file:檔名 是在 Copilot Chat 中參照特定檔案的語法。使用這個語法可以讓 Copilot 針對該檔案進行說明或操作。

問題 3 答案：B

Google 風格是 Python 社群中最常用的 docstring 格式，特點是簡潔易讀。使用 Args:、Returns: 等關鍵字標示參數和回傳值。

🎉 Part 13 重點回顧

文件層級

行內註解 → 函式文件
→ 檔案說明 → README

/doc 指令

為函式產生 docstring
包含參數和回傳值說明

Chat 對話

產生中文註解
行內說明、檔案文件

README 產生

@workspace 產生
專案說明文件

核心觀念

「好的文件是給未來的自己和他人的禮物」

下一單元預告

Part 14：實戰應用 - API 整合
用 Copilot 快速串接各種 API！