185 lines
No EOL
4.3 KiB
Markdown
185 lines
No EOL
4.3 KiB
Markdown
# 创建代码实体（方法、变量、参数）
|
||
|
||
## 目录
|
||
|
||
- [命名约定](#naming-conventions)
|
||
- [方法可见性](#method-visibility)
|
||
- [静态方法](#static-methods)
|
||
- [文档块必需条件](#docblock-requirements)
|
||
- [公开、受保护方法和钩子](#public-protected-methods-and-hooks)
|
||
- [私密方法和内部回调](#private-methods-and-internal-callbacks)
|
||
- [@internal 注解位置](#internal-annotation-placement)
|
||
- [钩子文档块](#hook-docblocks)
|
||
|
||
## 命名规范
|
||
|
||
为方法、变量和钩子使用 snake_case（而非 camelCase 或 PascalCase）。
|
||
|
||
**例子:**
|
||
|
||
```php
|
||
// 正确
|
||
public function calculate_order_total() { }
|
||
private $order_items;
|
||
```
|
||
|
||
## 方法可见性
|
||
|
||
新增类方法默认应为 `private`。
|
||
|
||
**仅在明确该方法将在派生类中使用时**，才使用 `protected`。
|
||
|
||
**仅在该方法将从类外部调用时**，才使用 `public`。
|
||
|
||
**示例:**
|
||
|
||
```php
|
||
class OrderProcessor {
|
||
// 默认：用于内部辅助方法的私密方法
|
||
private function validate_items( array $items ) { }
|
||
|
||
// 受保护：用于子类
|
||
protected function get_tax_rate( string $country ) { }
|
||
|
||
// 公开：外部 API
|
||
public function process_order( int $order_id ) { }
|
||
}
|
||
```
|
||
|
||
## 静态方法
|
||
|
||
纯方法（输出仅取决于输入，无外部依赖）必须声明为 `static`。
|
||
|
||
**纯方法示例（应声明为静态）：**
|
||
|
||
```php
|
||
// 数学计算
|
||
public static function calculate_percentage( float $amount, float $percent ) {
|
||
return $amount * ( $percent / 100 );
|
||
}
|
||
|
||
// 字符串操作
|
||
public static function format_product_sku( string $sku ) {
|
||
return strtoupper( trim( $sku ) );
|
||
}
|
||
|
||
// 数据转换
|
||
public static function normalize_address( array $address ) {
|
||
return array_map( 'trim', $address );
|
||
}
|
||
```
|
||
|
||
**非纯方法示例（不应声明为静态）：**
|
||
|
||
```php
|
||
// 依赖于数据库
|
||
public function get_order_total( int $order_id ) { }
|
||
|
||
// 依赖于系统时间
|
||
public function is_order_recent( int $order_id ) { }
|
||
|
||
// 使用对象状态
|
||
public function calculate_with_tax( float $amount ) {
|
||
return $amount * $this->tax_rate;
|
||
}
|
||
```
|
||
|
||
**例外情况：** 非纯方法不应声明为 `static`，除非有特定的架构原因（例如，单例样板、工厂方法）。
|
||
|
||
## 文档块要求
|
||
|
||
为所有钩子和方法添加简洁的文档块。理想情况下使用一行。
|
||
|
||
### 公开、受保护的方法和钩子
|
||
|
||
必须包含带有下一个 WooCommerce 版本号的 `@since` 注解。
|
||
|
||
`@since` 注解必须：
|
||
|
||
- 是文档块的最后一行
|
||
- 前面有一个空注释行
|
||
- 使用 trunk 上 `includes/class-woocommerce.php` 中的版本号，并移除 `-dev` 后缀
|
||
（例如，如果 trunk 显示 `10.4.0-dev`，则使用 `@since 10.4.0`）
|
||
|
||
**良好 - 简洁：**
|
||
|
||
```php
|
||
/**
|
||
* 处理订单并更新状态。
|
||
*
|
||
* @param int $order_id 订单 ID。
|
||
* @return bool 成功时返回 true。
|
||
*
|
||
* @since 9.5.0
|
||
*/
|
||
public function process_order( int $order_id ) { }
|
||
|
||
/**
|
||
* 在订单处理后触发。
|
||
*
|
||
* @param int $order_id 订单 ID。
|
||
*
|
||
* @since 9.5.0
|
||
*/
|
||
do_action( 'woocommerce_order_processed', $order_id );
|
||
```
|
||
|
||
**避免 - 过度解释：**
|
||
|
||
```php
|
||
/**
|
||
* 此方法通过验证订单数据、检查库存水平、处理支付，
|
||
* 然后更新订单状态以反映成功处理来处理订单。
|
||
*
|
||
* @param int $order_id 需要处理的订单的唯一标识符。
|
||
* @return bool 如果订单处理成功则返回 true，否则返回 false。
|
||
*
|
||
* @since 9.5.0
|
||
*/
|
||
```
|
||
|
||
对于钩子，尽可能使用一行描述性文字。
|
||
|
||
### 私密方法和内部回调
|
||
|
||
以下情况**不需要**添加 `@since` 注解：
|
||
|
||
- 私密方法
|
||
- 内部回调（已用 `@internal` 标记）
|
||
|
||
**例子：**
|
||
|
||
```php
|
||
/**
|
||
* 用于验证订单项目的内部辅助方法。
|
||
*
|
||
* @param array $items 待验证的项目。
|
||
* @return bool
|
||
*/
|
||
private function validate_items( array $items ) { }
|
||
```
|
||
|
||
### @internal 注释位置
|
||
|
||
当添加 `@internal` 注释时，必须：
|
||
|
||
- 放在方法描述之后
|
||
- 放在参数列表之前
|
||
- 前后各有一个空白注释行
|
||
|
||
**例子：**
|
||
|
||
```php
|
||
/**
|
||
* 处理 woocommerce_init 钩子。
|
||
*
|
||
* @internal
|
||
*
|
||
* @param array $args 钩子参数。
|
||
*/
|
||
public function handle_woocommerce_init( array $args ) { }
|
||
```
|
||
|
||
## 钩子文档区块
|
||
|
||
关于记录钩子的信息（包括为现有钩子添加文档区块），请参阅 [hooks.md](.ai/skills/woocommerce-backend-dev/zh-cn/hooks)。 |
