AgentSkillsCN

p3c-coding-style

提供编码风格规范，包括命名规范、代码格式化、常量定义与注释准则。当用户询问关于代码风格、命名规则或格式化标准时，此技能将助您事半功倍。

SKILL.md
--- frontmatter
name: "p3c-coding-style"
description: "Provides coding style standards including naming conventions, code formatting, constant definitions, and comment guidelines. Invoke when user asks about code style, naming rules, or formatting standards."

P3C 代码风格规范

本技能提供阿里巴巴Java开发手册中的代码风格相关规范，包括命名风格、代码格式、常量定义和注释规约。

命名风格

基本规则

  1. •【强制】代码中的命名均不能以下划线或美元符号开始，也不能以下划线或美元符号结束
  2. •【强制】代码中的命名严禁使用拼音与英文混合的方式，更不允许直接使用中文的方式

类名规范

  1. •【强制】类名使用UpperCamelCase风格，但以下情形例外：DO / BO / DTO / VO / AO / PO等

方法与变量命名

  1. •【强制】方法名、参数名、成员变量、局部变量都统一使用lowerCamelCase风格，必须遵从驼峰形式

常量命名

  1. •【强制】常量命名全部大写，单词间用下划线隔开，力求语义表达完整清楚

特殊类命名

  1. •【强制】抽象类命名使用Abstract或Base开头；异常类命名使用Exception结尾；测试类命名以它要测试的类名开始，以Test结尾

数组定义

  1. •【强制】类型与中括号紧挨相连来定义数组

布尔变量命名

  1. •【强制】POJO类中布尔类型的变量，都不要加is前缀，否则部分框架解析会引起序列化错误

包名规范

  1. •【强制】包名统一使用小写，点分隔符之间有且仅有一个自然语义的英语单词。包名统一使用单数形式

缩写规范

  1. •【强制】杜绝完全不规范的缩写，避免望文不知义

完整命名

  1. •【推荐】为了达到代码自解释的目标，任何自定义编程元素在命名时，使用尽量完整的单词组合来表达其意

设计模式命名

  1. •【推荐】如果模块、接口、类、方法使用了设计模式，在命名时体现出具体模式

接口命名

  1. •【推荐】接口类中的方法和属性不要加任何修饰符号（public 也不要加），保持代码的简洁性

接口和实现类命名

  1. •接口和实现类的命名有两套规则：
    • •【强制】对于Service和DAO类，基于SOA的理念，暴露出来的服务一定是接口，内部的实现类用Impl的后缀与接口区别
    • •【推荐】如果是形容能力的接口名称，取对应的形容词为接口名（通常是–able的形式）

枚举命名

  1. •【参考】枚举类名建议带上Enum后缀，枚举成员名称需要全大写，单词间用下划线隔开

各层命名规约

  1. •【参考】各层命名规约：
    • •A) Service/DAO层方法命名规约
      • •获取单个对象的方法用get作前缀
      • •获取多个对象的方法用list作前缀
      • •获取统计值的方法用count作前缀
      • •插入的方法用save/insert作前缀
      • •删除的方法用remove/delete作前缀
      • •修改的方法用update作前缀
    • •B) 领域模型命名规约
      • •数据对象：xxxDO，xxx即为数据表名
      • •数据传输对象：xxxDTO，xxx为业务领域相关的名称
      • •展示对象：xxxVO，xxx一般为网页名称
      • •POJO是DO/DTO/BO/VO的统称，禁止命名成xxxPOJO

代码格式

大括号使用

  1. •【强制】大括号的使用约定。如果是大括号内为空，则简洁地写成{}即可，不需要换行；如果是非空代码块则：
    • •左大括号前不换行
    • •左大括号后换行
    • •右大括号前换行
    • •右大括号后还有else等代码则不换行；表示终止的右大括号后必须换行

括号空格

  1. •【强制】左小括号和字符之间不出现空格；同样，右小括号和字符之间也不出现空格

关键字空格

  1. •【强制】if/for/while/switch/do等保留字与括号之间都必须加空格

运算符空格

  1. •【强制】任何二目、三目运算符的左右两边都需要加一个空格

缩进规范

  1. •【强制】采用4个空格缩进，禁止使用tab字符

注释空格

  1. •【强制】注释的双斜线与注释内容之间有且仅有一个空格

行长度限制

  1. •【强制】单行字符数限制不超过2000个，超出需要换行，换行时遵循如下原则：
    • •第二行相对第一行缩进4个空格，从第三行开始，不再继续缩进
    • •运算符与下文一起换行
    • •方法调用的点符号与下文一起换行
    • •方法调用时，多个参数，需要换行时，在逗号后进行
    • •在括号前不要换行

参数空格

  1. •【强制】方法参数在定义和传入时，多个参数逗号后边必须加空格

编码格式

  1. •【强制】IDE的text file encoding设置为UTF-8; IDE中文件的换行符使用Unix格式，不要使用Windows格式

对齐规范

  1. •【推荐】没有必要增加若干空格来使某一行的字符与上一行对应位置的字符对齐

空行使用

  1. •【推荐】不同逻辑、不同语义、不同业务的代码之间插入一个空行分隔开来以提升可读性

常量定义

魔法值

  1. •【强制】不允许任何魔法值（即未经预先定义的常量）直接出现在代码中

Long类型

  1. •【强制】long或者Long初始赋值时，使用大写的L，不能是小写的l，小写容易跟数字1混淆

常量分类

  1. •【推荐】不要使用一个常量类维护所有常量，按常量功能进行归类，分开维护

常量复用层次

  1. •【推荐】常量的复用层次有五层：跨应用共享常量、应用内共享常量、子工程内共享常量、包内共享常量、类内共享常量

枚举使用

  1. •【推荐】如果变量值仅在一个固定范围内变化用enum类型来定义

注释规约

Javadoc规范

  1. •【强制】类、类属性、类方法的注释必须使用Javadoc规范，使用/*内容/格式，不得使用// xxx方式

抽象方法注释

  1. •【强制】所有的抽象方法（包括接口中的方法）必须要用Javadoc注释、除了返回值、参数、异常说明外，还必须指出该方法做什么事情，实现什么功能

类注释

  1. •【强制】所有的类都必须添加创建者和创建日期

方法内部注释

  1. •【强制】方法内部单行注释，在被注释语句上方另起一行，使用//注释。方法内部多行注释使用/* */注释，注意与代码对齐

枚举注释

  1. •【强制】所有的枚举类型字段必须要有注释，说明每个数据项的用途

注释语言

  1. •【推荐】与其"半吊子"英文来注释，不如用中文注释把问题说清楚。专有名词与关键字保持英文原文即可

注释同步更新

  1. •【推荐】代码修改的同时，注释也要进行相应的修改，尤其是参数、返回值、异常、核心逻辑等的修改

注释代码

  1. •【参考】谨慎注释掉代码。在上方详细说明，而不是简单地注释掉。如果无用，则删除

注释要求

  1. •【参考】对于注释的要求：第一、能够准确反应设计思想和代码逻辑；第二、能够描述业务含义，使别的程序员能够迅速了解到代码背后的信息

注释精简

  1. •【参考】好的命名、代码结构是自解释的，注释力求精简准确、表达到位

特殊注释标记

  1. •【参考】特殊注释标记，请注明标记人与标记时间。注意及时处理这些标记，通过标记扫描，经常清理此类标记
    • •待办事宜（TODO）
    • •错误，不能工作（FIXME）