文档库
咱们团队的多语言编程规范小册子
公共风格·2.4.2 文件注释
概述
序言
工具链
我们有哪些开发成果呢?
编程风格指南文档结构
2.1 作用域
2.1.1 命名空间
2.1.2 嵌套类
2.1.3 全局函数
2.1.4 局部变量
2.1.5 全局变量
2.1.6 作用域使用建议总结
2.2 类,编程规范中的类是什么意思?
2.2.1 构造函数
2.2.2 继承
2.2.3 多重继承
2.2.4 接口(Interface)
2.2.5 存取控制
2.2.6 声明次序
2.2.7 编写短小函数
2.2.8 初始化列表
2.2.9 命名空间格式化
2.2.10 水平空白
2.2.11 垂直空白(空行)
2.3 命名规范
2.3.1 通用命名规则
2.3.2 缩写
2.3.3 文件命名
2.3.4 类命名
2.3.5 变量命名
2.3.6 常量命名
2.3.7 函数命名
2.3.8 命名空间
2.8.9 命名规则例外
2.4 代码注释
2.4.1 注释风格
2.4.2 文件注释
2.4.3 类注释
2.4.4 函数注释
2.4.5 变量注释
2.4.6 实现注释
2.4.7 标点、拼写和注释语言
2.4.6 TODO
2.5 代码格式化(如缩进、换行等)
2.5.1 每一行代码的长度(避免一行代码占过多屏幕宽度)
2.5.2 非ASCII字符
2.5.3 空格 or 制表符Tab
2.5.4 函数声明与定义
2.5.5 函数调用
2.5.6 条件语句
2.5.7 循环和开关选择语句(loop and switch)
2.5.8 布尔表达式
查询构造器
查询数据
添加数据
更新数据
删除数据
查询表达式
3.1.1 协议
3.2 排版规则
3.2.1 缩进
3.2.2 大小写
3.3 元数据规则
3.3.1 编码
3.4 HTML代码风格规则
3.4.1 文档类型
3.4.2 HTML代码有效性
3.4.3 语义化
3.4.4 多媒体后备方案
3.4.5 关注点分离
3.4.6 实体引用
3.4.7 可选标签
3.4.8 type属性
3.4.9 HTML代码格式规则
4 CSS
4.1 CSS代码风格规则
4.1.1 CSS代码有效性
4.1.2 id和class的命名
4.1.3 id和class命名风格
4.1.4 类型选择器
4.2 属性缩写
4.2.1 0和单位
4.2.2 0开头的小数
4.2.3 URI外的引号
4.2.4 十六进制
聚合查询
分页查询
时间查询
高级查询
视图查询
4.3.2 代码块内容缩进
子查询
原生查询
获取查询参数
4.3.6 规则分行
4.4 CSS元数据规则
4.4.1 注释部分
5 JavaScript
5.1 JavaScript基础特性
5.1.1 变量(var,let)
5.1.2 常量
5.1.3 分号
5.1.4 嵌套函数
5.1.5 块内函数声明
5.1.6 异常处理
5.1.7 自定义异常
5.1.8 标准特性
5.1.9 基本包装类型
5.1.10 多级原型结构
5.1.11 方法定义
5.1.12 闭包
5.1.13 eval()
5.1.14 with() {}
5.1.15 this
5.1.16 for-in 循环
5.1.17 关联数组
5.1.18 多行字符串字面量
5.1.19 Array和Object字面量
5.1.20 修改内置对象的原型
5.1.21 IE下的条件注释
5.2 命名
5.2.1 属性和方法
5.2.2 方法和函数参数
5.2.3 属性的访问器
5.2.4 函数的访问器
5.3 命名空间
5.3.1 在全局作用域下使用伪命名空间
5.3.2 明确命名空间所有权
5.4 长名引用
5.5 自定义 toString() 方法
5.6 作用域
5.7 代码格式化
5.8 字符串
5.9 可见性
5.10 JavaScript中的类型
5.10.1 明确类型
5.10.2 类型定义
5.10.3 模板属性
5.11 注释、缩进
5.11.1 JSDoc的HTML
5.11.2 内部类和枚举
5.12 编译压缩
6 Php
6.1 基本规则必须遵循PSR-1的条款
6.1.1 文件
6.1.2 关键词
6.1.3 Namespace 和 Use 声明
6.2 类, 属性 和 方法
6.2.1 继承 和 实现
6.2.2 属性
6.2.3 方法
6.2.4 abstract, final 和 static
6.3 Closure 闭包
7 Java
7.1 源文件
7.1.1 特殊字符
7.1.2 包含顺序
7.1.3 import顺序
7.2 类声明
7.2.1 只有一个顶级类声明
7.2.2 类成员顺序
7.2.3 重载
7.3 具体结构
7.3.1 枚举类
7.3.2 变量声明
7.3.3 数组
7.4 注解(Annotations)
7.5 注释
7.5.1 Modifiers
7.6 命名约定
7.6.1 对所有标识符都通用的规则
7.6.2 包名
7.7 Java特性
7.7.1 @Override:能用则用
7.7.2 捕获的异常:不能忽视
7.7.3 静态成员:使用类进行调用
7.7.4 Finalizers: 禁用
8 C++
8.1 头文件
8.1.1 #define 保护
8.1.2 头文件依赖
8.1.3 内联函数
8.1.4 -inl.h文件
8.1.5 函数参数顺序
8.1.6 包含头文件的名词及次序
8.2 作用域
8.2.1 命名空间
8.2.2 嵌套类
8.2.3 局部变量
8.2.4 全局变量
8.3 C++ 类
8.3.1 构造函数
8.3.2 默认构造函数
8.3.3 明确的构造函数
8.3.4 拷贝构造函数
8.3.5 结构体和类
8.3.6 继承
8.3.7 多重继承
8.3.8 接口(Interface)
8.3.9 操作符重载
8.3.10 存取控制
8.3.11 声明次序
8.4 其他C++特性
8.5 规则之例外
8.5.1 Windows代码
9 Python
9.1 格式
9.1.1 分号
9.1.2 行长度
9.1.3 括号
9.1.4 缩进
9.1.5 空格
9.2 Shebang
9.3 注释
9.4 类
9.5 字符串
9.6 文件和sockets
9.7 使用with语句管理文件
9.8 导入格式
9.9 语句
9.10 访问控制
9.11 命名
9.11.1 示例
9.11.2 应该避免的名称
9.11.3 命名约定
9.12 Main
10 规约
11 参考文档
代码提交规范
Git提交规范
commit规范
push规范
commit message规范
公共风范
约定
各编程语言都需遵守的约定
作用域
命名空间
嵌套类
全局函数
局部变量
全局变量
作用域使用建议总结
类
类,编程规范中的类是什么意思?
构造函数
继承
多重继承
接口(Interface)
存取控制
声明次序
编写短小函数
初始化列表
命名空间格式化
水平空白
垂直空白(空行)
命名规范
通用命名规则
缩写
文件命名
类命名
变量命名
常量命名
函数命名
命名空间
命名规则例外
代码注释
注释风格
文件注释
类注释
函数注释
变量注释
实现注释
标点、拼写和注释语言
TODO
代码格式化
每一行代码的长度
非ASCII字符
空格 or 制表符Tab
函数声明与定义
函数调用
条件语句
循环和开关选择语句
布尔表达式
返回值
初始化操作
其他
现有不统一代码
HTML
样式规则
协议
排版规则
缩进
大小写
元数据规则
编码
HTML代码风格规则
文档类型
HTML代码有效性
语义化
多媒体后备方案
关注点分离
实体引用
可选标签
type属性
HTML代码格式规则
常规格式化 copy
HTML引号
CSS
CSS代码风格规则
CSS代码有效性
id和class的命名
id和class命名风格
类型选择器
属性缩写
0和单位
0开头的小数
URI外的引号
十六进制
前缀
id和class命名的定界符
Hacks
CSS代码格式规则
声明顺序
代码块内容缩进
声明完结
属性名完结
选择器和声明分行
规则分行
CSS元数据规则
注释部分
JavaScript
JavaScript基础特性
变量(var,let)
常量
分号
嵌套函数
块内函数声明
异常处理
自定义异常
标准特性
基本包装类型
多级原型结构
方法定义
闭包
eval()
with() {}
this
关联数组
多行字符串字面量
Array和Object字面量
修改内置对象的原型
IE下的条件注释
命名
属性和方法
方法和函数参数
属性的访问器
函数的访问器
命名空间
在全局作用域下使用伪命名空间
明确命名空间所有权
长名引用
自定义 toString() 方法
作用域
代码格式化
字符串
可见性
JavaScript中的类型
明确类型
类型定义
模板属性
注释、缩进
JSDoc的HTML
内部类和枚举
编译压缩
PHP
文件
关键词
Namespace 和 Use 声明
类, 属性 和 方法
继承 和 实现
属性
方法
abstract, final 和 static
Closure 闭包
Java
源文件
特殊字符
包含顺序
import顺序
类声明
只有一个顶级类声明
类成员顺序
重载
具体结构
格式
枚举类
变量声明
数组
注解(Annotations)
注释
修饰符
数值字面量
命名约定
对所有标识符都通用的规则
包名
Java特性
@Override:能用则用
捕获的异常:不能忽视
静态成员:使用类进行调用
析构方法:不使用
Javadoc
格式
摘要片段
Javadoc的使用位置
C++
头文件
#define 保护
头文件依赖
内联函数
inl.h文件
函数参数顺序
包含头文件的名词及次序
作用域
命名空间
嵌套类
局部变量
全局变量
C++ 类
构造函数
默认构造函数
明确的构造函数
拷贝构造函数
结构体和类
继承
接口(Interface)
操作符重载
存取控制
声明次序
其他C++特性
规则之例外
Windows代码
Python
格式
分号
行长度
括号
缩进
空格
Shebang
注释
类
字符串
文件和sockets
使用with语句管理文件
导入格式
语句
访问控制
命名
示例
应该避免的名称
命名约定
Main
导入
包
异常
Lambda函数
条件表达式
推导式 (comprehension expression) 和生成式 (generator exp
函数与方法装饰器
线程
威力过大的功能
Shell
Shell文件和解释器调用
文件拓展名
SUID、SGID
环境
注释
文件头
功能注释
实现部分的注释
TODO注释
格式
缩进
行的长度和长字符串
管道
循环
case语句
变量扩展
引用
特性及错误
命令替换
test,[和[[
测试字符串
文件名的通配符拓展
Eval
管道导向while循环
命名约定
函数名
变量名
常量和环境变量名
源文件名
只读变量
使用本地变量
函数位置
主函数main
调用命令
检查返回值
内建命令和外部命令
Kotlin
Android 资源文件命名与使用
Android 基本组件
UI 与布局
进程、线程与消息通信
文件与数据库
Bitmap、Drawable与动画
安全
其他
C
函数
头文件
标识符命名与定义
通用命名规则
文件命名规则
变量命名规则
函数命名规则
宏命名规则
变量
宏、常量
质量保障
程序效率
注释
排版与格式
表达式
编辑、编译
Go
概览
命名
函数和方法名称
阴影
包大小
导入
错误处理
错误结构
为错误添加信息
错误中的 %w 的位置
错误日志
程序初始化
程序检查和 panic
何时 panic
文档
公约
预览
Godoc 格式化
信号增强
变量声明
函数参数列表
复杂的命令行界面
测试
把测试留给 Test 函数
设计可扩展的验证API
使用真正的传输工具
t.Error vs. t.Fatal
在测试辅助函数中处理错误
不要从独立的 goroutines 中调用t.Fatal
对结构字使用字段标签
保持设置代码在特定的测试范围内
字符串拼接
其他
规约
开发框架
参考文档
ThinkPHP
基础
安装
开发规范
目录结构
配置
架构
请求流程
架构总览
入口文件
多应用模式
URL访问
容器和依赖注入
服务
门面
中间件
事件
路由
路由定义
变量规则
路由地址
路由参数
路由中间件
路由分组
资源路由
域名路由
MISS路由
注解路由
跨域请求
URL生成
控制器
控制器定义
基础控制器
空控制器
资源控制器
控制器中间件
请求
请求对象
请求信息
请求类型
HTTP头信息
伪静态
参数绑定
请求缓存
响应
响应输出
响应参数
重定向
文件下载
数据库
连接数据库
分布式数据库
链式操作
where
table
alias
field
strict
limit
page
order
group
having
join
union
distinct
lock
cache
cacheAlways
comment
fetchSql
force
partition
failException
sequence
replace
extra
duplicate
procedure
查询事件
事务操作
存储过程
数据库驱动
模型
定义
模型字段
新增
更新
删除
查询
查询范围
JSON字段
获取器
修改器
搜索器
数据集
自动时间戳
只读字段
延迟写入
软删除
字段映射
类型转换
模型输出
模型事件
模型关联
一对一关联
一对多关联
远程一对多
远程一对一
多对多关联
多态关联
关联预载入
关联统计
关联输出
虚拟模型
视图
模板变量
视图过滤
模板渲染
模板引擎
视图驱动
错误和日志
异常处理
日志处理
调试
调试模式
Trace调试
SQL调试
变量调试
验证
验证器
验证规则
错误信息
验证场景
路由验证
内置规则
表单令牌
杂项
缓存
Session
Cookie
多语言
上传
命令行
启动内置服务器
查看版本
自动生成应用目录
创建类库文件
清除缓存文件
生成数据表字段缓存
生成路由映射缓存
输出路由定义
自定义指令
Debug输出级别
扩展库
数据库迁移工具
Workerman
think助手工具库
验证码
Swoole
附录
助手函数
升级指导
Android
SpringBoot
ElementUI
开发指南
安装
快速上手
基础组件
Layout 布局
Container 布局容器
Color 色彩
Typography 字体
Border 边框
Icon 图标
Button 按钮
Link 文字链接
表单组件
Radio 单选框
Checkbox 多选框
Input 输入框
InputNumber 计数器
Select 选择器
Cascader 级联选择器
Switch 开关
Slider 滑块
TimePicker 时间选择器
DatePicker 日期选择器
DateTimePicker 日期时间选择器
Upload 上传
Rate 评分
ColorPicker 颜色选择器
Transfer 穿梭框
Form 表单
数据组件
Table 表格
Tag 标签
Progress 进度条
Tree 树形控件
Pagination 分页
Badge 标记
Avatar 头像
Skeleton 骨架屏
Empty 空状态
提示组件
Alert 警告
Loading 加载
Message 消息提示
MessageBox 弹框
Notification 通知
导航组件
NavMenu 导航菜单
Tabs 标签页
Breadcrumb 面包屑
PageHeader 页头
Dropdown 下拉菜单
Steps 步骤条
其他组件
Dialog 对话框
Tooltip 文字提示
Popover 弹出框
Popconfirm 气泡确认框
Card 卡片
Carousel 走马灯
Collapse 折叠面板
Timeline 时间线
Divider 分割线
Calendar 日历
Image 图片
InfiniteScroll 无限滚动
Drawer 抽屉
Vant
基础组件
Button 按钮
Cell 单元格
Icon 图标
Image 图片
Layout 布局
Popup 弹出层
内置样式
Toast 轻提示
表单组件
Calendar 日历
Checkbox 复选框
DatetimePicker 时间选择
Field 输入框
Form 表单
NumberKeyboard 数字键盘
PasswordInput 密码输入框
Picker 选择器
Radio 单选框
Rate 评分
Search 搜索
Slider 滑块
Steps 步骤条
Switch 开关
Uploader 文件上传
反馈组件
ActionSheet 动作面板
Dialog 弹出框
DropdownMenu 下拉菜单
Loading 加载
Notify 消息提示
Overlay 遮罩层
PullRefresh 下拉刷新
ShareSheet 分享面板
SwipeCell 滑动单元格
展示组件
Circle 环形进度条
Collapse 折叠面板
CountDown 倒计时
Divider 分割线
Empty 空状态
ImagePreview 图片预览
Lazyload 懒加载
List 列表
NoticeBar 通知栏
Progress 进度条
Skeleton 骨架屏
Stepper 步进器
Sticky 粘性布局
Swipe 轮播
Tag 标签
导航组件
Grid 宫格
IndexBar 索引栏
NavBar 导航栏
Pagination 分页
Sidebar 侧边导航
Tab 标签页
Tabbar 标签栏
TreeSelect 分类选择
业务组件
AddressEdit 地址编辑
AddressList 地址列表
ActionBar 动作栏
Area 省市区选择
Badge 徽标
Card 卡片
Contact 联系人
Coupon 优惠券选择器
SubmitBar 提交订单栏
Sku 商品规格
Vue
Vue2
基础
安装
介绍
Vue 实例
模板语法
计算属性和侦听器
Class 与 Style 绑定
条件渲染
列表渲染
事件处理
表单输入绑定
组件基础
深入了解组件
组件注册
Prop
自定义事件
插槽
动态组件 & 异步组件
处理边界情况
过渡 & 动画
进入 & 离开 & 列表过渡
状态过渡
可复用性 & 组合
混入
自定义指令
插件
过滤器
渲染函数 & JSX
工具
单文件组件
单元测试
TypeScript 支持
生产环境部署
规模化
路由
状态管理
服务端渲染
深入响应式原理
如何追踪变化
检测变化的注意事项
声明响应式属性
异步更新队列
Vue3
开始
简介
快速上手
基础
创建一个 Vue 应用
模板语法
响应式基础
计算属性
Class 与 Style 绑定
条件渲染
列表渲染
事件处理
表单输入绑定
生命周期钩子
侦听器
模板引用
组件基础
深入组件
注册
Props
事件
透传 Attributes
插槽 Slots
依赖注入
异步组件
逻辑复用
组合式函数
自定义指令
插件
内置组件
Transition
TransitionGroup
KeepAlive
Teleport
Suspense
应用规模化
单文件组件
工具链
路由
状态管理
测试
服务端渲染 (SSR)
最佳实践
生产部署
性能优化
无障碍访问
安全
TypeScript
TS与组合式 API
TS与选项式 API
进阶主题
使用 Vue 的多种方式
组合式 API 常见问答
深入响应式系统
渲染机制
渲染函数 & JSX
Vue 与 Web Components
动画技巧
624 次阅读
2.4.2 文件注释
2021-03-09 15:51:28
文件注释需说明当前文件在项目中的核心作用。 比如某个用户管理相关的文件,可以这样注释:
/** * 用户信息管理文件 * @author yixzm * @modify 2022-5-20 */
上一页 2.4.1 注释风格
下一页 2.4.3 类注释
探索宇宙
意见反馈