4.3 KiB
4.3 KiB
创建代码实体（方法、变量、参数）
目录
命名规范
为方法、变量和钩子使用 snake_case（而非 camelCase 或 PascalCase）。
例子:
// 正确
public function calculate_order_total() { }
private $order_items;
方法可见性
新增类方法默认应为 private。
仅在明确该方法将在派生类中使用时，才使用 protected。
仅在该方法将从类外部调用时，才使用 public。
示例:
class OrderProcessor {
// 默认：用于内部辅助方法的私密方法
private function validate_items( array $items ) { }
// 受保护：用于子类
protected function get_tax_rate( string $country ) { }
// 公开：外部 API
public function process_order( int $order_id ) { }
}
静态方法
纯方法（输出仅取决于输入，无外部依赖）必须声明为 static。
纯方法示例（应声明为静态）：
// 数学计算
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 );
}
非纯方法示例（不应声明为静态）：
// 依赖于数据库
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）
良好 - 简洁：
/**
* 处理订单并更新状态。
*
* @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 );
避免 - 过度解释：
/**
* 此方法通过验证订单数据、检查库存水平、处理支付，
* 然后更新订单状态以反映成功处理来处理订单。
*
* @param int $order_id 需要处理的订单的唯一标识符。
* @return bool 如果订单处理成功则返回 true，否则返回 false。
*
* @since 9.5.0
*/
对于钩子，尽可能使用一行描述性文字。
私密方法和内部回调
以下情况不需要添加 @since 注解：
- 私密方法
- 内部回调（已用
@internal标记）
例子：
/**
* 用于验证订单项目的内部辅助方法。
*
* @param array $items 待验证的项目。
* @return bool
*/
private function validate_items( array $items ) { }
@internal 注释位置
当添加 @internal 注释时，必须：
- 放在方法描述之后
- 放在参数列表之前
- 前后各有一个空白注释行
例子：
/**
* 处理 woocommerce_init 钩子。
*
* @internal
*
* @param array $args 钩子参数。
*/
public function handle_woocommerce_init( array $args ) { }
钩子文档区块
关于记录钩子的信息（包括为现有钩子添加文档区块），请参阅 hooks.md。
