程式碼審查樣式指南

如果您有一組自訂最佳做法或慣例，希望 GitHub 專用 Gemini Code Assist 在執行程式碼審查時檢查或遵循，可以將 styleguide.md Markdown 檔案新增至存放區的 .gemini/ 根資料夾。GitHub 上的 Gemini Code Assist 企業版使用者可以使用 Google Cloud 控制台新增樣式指南資訊，供多個存放區使用。在這兩種情況下，樣式指南都會視為一般 Markdown 檔案，並擴充 GitHub 上的 Gemini Code Assist 所用的標準提示。

標準程式碼審查模式

如果未指定自訂風格指南，Gemini Code Assist 會著重於以下主要類別的程式碼審查：

• 正確性：確保程式碼能正常運作並處理極端情況，檢查邏輯錯誤、競爭條件或 API 使用方式有誤。

• 效率：找出潛在的效能瓶頸或可最佳化的區域，例如過多的迴圈、記憶體洩漏、效率低落的資料結構、多餘的計算、過多的記錄，以及效率低落的字串操作。

• 可維護性：評估程式碼的可讀性、模組化程度，以及是否符合語言慣用語和最佳做法。目標是變數、函式和類別的命名不佳、缺少註解或文件、程式碼複雜、程式碼重複、格式不一致，以及魔術數字。

• 安全性：找出資料處理或輸入驗證的潛在安全漏洞，例如機密資料儲存不安全、注入攻擊、存取控管不足、跨網站要求偽造 (CSRF) 和不安全的直接物件參照 (IDOR)。

• 其他：審查提取要求時，我們會考量其他主題，例如測試、效能、可擴充性、模組化和可重複使用性，以及錯誤記錄和監控。

樣式指南範例

styleguide.md 檔案未定義結構定義。而是以自然語言描述您希望 Gemini Code Assist 如何架構程式碼審查。以下程式碼片段是 styleguide.md 檔案的範例：

# Company X Python Style Guide

## Introduction

This style guide outlines the coding conventions for Python code developed at
Company X. It's based on PEP 8, but with some modifications to address
specific needs and preferences within our organization.

## Key Principles

*   **Readability:** Code should be easy to understand for all team members.
*   **Maintainability:** Code should be easy to modify and extend.
*   **Consistency:** Adhering to a consistent style across all projects
    improves collaboration and reduces errors.
*   **Performance:** While readability is paramount, code should be efficient.

## Deviations from PEP 8

### Line Length

* **Maximum line length:** 100 characters (instead of PEP 8's 79).
    *   Modern screens allow for wider lines, improving code readability in
        many cases.
    *   Many common patterns in our codebase, like long strings or URLs, often
        exceed 79 characters.

### Indentation

*   **Use 4 spaces per indentation level.** (PEP 8 recommendation)

### Imports

*   **Group imports:**
    *   Standard library imports
    *   Related third party imports
    *   Local application/library specific imports
*   **Absolute imports:** Always use absolute imports for clarity.
*   **Import order within groups:**  Sort alphabetically.

### Naming Conventions

*   **Variables:** Use lowercase with underscores (snake_case): `user_name`, `total_count`
*   **Constants:**  Use uppercase with underscores: `MAX_VALUE`, `DATABASE_NAME`
*   **Functions:** Use lowercase with underscores (snake_case): `calculate_total()`, `process_data()`
*   **Classes:** Use CapWords (CamelCase): `UserManager`, `PaymentProcessor`
*   **Modules:** Use lowercase with underscores (snake_case): `user_utils`, `payment_gateway`

### Docstrings

*   **Use triple double quotes (`"""Docstring goes here."""`) for all docstrings.**
*   **First line:** Concise summary of the object's purpose.
*   **For complex functions/classes:** Include detailed descriptions of
    parameters, return values, attributes, and exceptions.
*   **Use Google style docstrings:** This helps with automated documentation generation.
    ```python
    def my_function(param1, param2):
        """Single-line summary.

        More detailed description, if necessary.

        Args:
            param1 (int): The first parameter.
            param2 (str): The second parameter.

        Returns:
            bool: The return value. True for success, False otherwise.

        Raises:
            ValueError: If `param2` is invalid.
        """
        # function body here
    ```

### Type Hints

*   **Use type hints:**  Type hints improve code readability and help catch
    errors early.
*   **Follow PEP 484:**  Use the standard type hinting syntax.

### Comments

*   **Write clear and concise comments:** Explain the "why" behind the code,
    not just the "what".
*   **Comment sparingly:** Well-written code should be self-documenting where
    possible.
*   **Use complete sentences:** Start comments with a capital letter and use
    proper punctuation.

### Logging

*   **Use a standard logging framework:**  Company X uses the built-in
    `logging` module.
*   **Log at appropriate levels:** DEBUG, INFO, WARNING, ERROR, CRITICAL
*   **Provide context:** Include relevant information in log messages to aid
    debugging.

### Error Handling

*   **Use specific exceptions:** Avoid using broad exceptions like `Exception`.
*   **Handle exceptions gracefully:** Provide informative error messages and
    avoid crashing the program.
*   **Use `try...except` blocks:**  Isolate code that might raise exceptions.

## Tooling

*   **Code formatter:**  [Specify formatter, e.g., Black] - Enforces
    consistent formatting automatically.
*   **Linter:**  [Specify linter, e.g., Flake8, Pylint] - Identifies potential
    issues and style violations.

管理多個存放區的樣式指南

如果您使用 GitHub 專用 Gemini Code Assist 的企業版，可以讓多個存放區套用同一份樣式指南。存放區會依據 Developer Connect 連線分組，並透過 Google Cloud 控制台管理集合式樣式指南。

如果存放區是群組的一部分，但也有自己的 styleguide.md 檔案，存放區的 styleguide.md 會與群組樣式指南合併。

以下步驟說明企業版使用者如何跨多個存放區控管單一風格指南。這些步驟假設您先前已在 GitHub 上設定 Gemini Code Assist。

預覽

這項功能適用《Google Cloud 服務專屬條款》中「一般服務條款」一節的《正式發布前產品條款》。正式發布前功能是依「原樣」提供，支援服務可能受限。詳情請參閱「Google Cloud 推出階段說明」。

1. 在 Google Cloud 控制台中，前往 Gemini Code Assist 的「Agents & Tools」頁面。

   前往「代理程式和工具」

2. 在「代理程式」部分中，找到「Code Assist 原始碼管理」資訊卡，然後按一下「進階」。

   「Edit Code Assist Source Code Management」(編輯 Code Assist 原始碼管理) 窗格隨即開啟。

3. 在「連線」表格中，按一下要套用樣式指南的連線名稱。

   系統會開啟連線的詳細資料頁面。

4. 在「樣式指南」分頁中，新增要與這個連線建立關聯的存放區使用的樣式指南。

5. 按一下 [儲存]。

後續步驟

• 修改 GitHub 專用 Gemini Code Assist 的設定。