diff --git a/2023-08-24-16-33-49.gif b/2023-08-24-16-33-49.gif deleted file mode 100644 index 0aa962c..0000000 Binary files a/2023-08-24-16-33-49.gif and /dev/null differ diff --git a/README.md b/README.md index c1e38b8..e40541a 100644 --- a/README.md +++ b/README.md @@ -6,4 +6,4 @@ ## 文档目录结构 -[中文文档](zh-cn/doc/doc.md) \ No newline at end of file +[中文文档](zh-cn/doc/JCNC开发者文档.md) \ No newline at end of file diff --git a/zh-cn/doc/gitcode.md b/zh-cn/doc/Git常用命令.md similarity index 100% rename from zh-cn/doc/gitcode.md rename to zh-cn/doc/Git常用命令.md diff --git a/zh-cn/doc/JCNC开发者文档.md b/zh-cn/doc/JCNC开发者文档.md new file mode 100644 index 0000000..5dd161d --- /dev/null +++ b/zh-cn/doc/JCNC开发者文档.md @@ -0,0 +1,19 @@ +# JCNC开发者文档 + +本目录是JCNC开发者文档的中文目录。目录内容包括: + +### 新手指南 + +[第一次接触开源项目?](第一次接触开源项目.md) + +[Git常用命令](Git常用命令.md) + +[JCNC项目开发流程](JCNC项目开发流程/JCNC项目开发流程.md) + + +### 项目文档 + +[JNotepad文档](https://gitee.com/jcnc-org/JNotepad/blob/release-v1.1.13/README.md) + + +### 欢迎补充和修复文档! \ No newline at end of file diff --git a/zh-cn/doc/JCNC项目开发流程/JCNC项目开发流程.md b/zh-cn/doc/JCNC项目开发流程/JCNC项目开发流程.md new file mode 100644 index 0000000..152f66f --- /dev/null +++ b/zh-cn/doc/JCNC项目开发流程/JCNC项目开发流程.md @@ -0,0 +1,50 @@ +# 1. 开发流程 +基于**AoneFlow**开发流程,具体请阅读:[在阿里,我们如何管理代码分支?](https://developer.aliyun.com/article/573549) +## 1.1 IDEA IDE版 +### 步骤一 Fork JCNC/JNotepad或同步JCNC/JNotepad到个人仓库 +#### 首次开发,进行Fork操作 +![输入图片说明](img/1.png "屏幕截图") +#### 非首次开发,进行同步操作 +![输入图片说明](img/2.png "屏幕截图") + +### 步骤二 clone个人仓库或fetch +#### 首次开发,clone个人仓库 +![输入图片说明](img/3.png "屏幕截图") +#### 非首次开发,执行fetch +![输入图片说明](img/4.png "屏幕截图") + +### 步骤三 从remote下的master分支创建本地开发分支 +![输入图片说明](img/5.png "屏幕截图") +![输入图片说明](img/6.png "屏幕截图") + +分支命名规则见:1.3节 + +### 步骤四 推送本地分支到远程 + +### 步骤五 发起Pull Request(PR) +![输入图片说明](img/7.png "屏幕截图") + +**注意:目标分支选择预期要发布的release分支** + +## 1.2 GIT命令行版本 +步骤一、步骤二、步骤五同1.1操作 +```shell +# 步骤三 +git fetch +git checkout origin/master && git checkout -b feature-demo +# 步骤四 +git push origin feature-demo +``` + +## 1.3 分支命名规则 +|issue类别|分支名格式|示例| +|--------|--------|----| +|功能/优化/文档修改|feature-issue编号|feature-I7W9LX| +|bug fix| fix-issue编号| fix-I7W9LX| +|代码重构|refactor-issue编号|refactor-I7W9LX| + +# 2. IDEA插件配置 +* 按照Resource Bundle插件 + ![输入图片说明]( img/8.png "屏幕截图") +* 安装成功后,打开i18n.properties,可以看到Resource Bundle tab + ![输入图片说明]( img/9.png "屏幕截图") \ No newline at end of file diff --git a/zh-cn/doc/JCNC项目开发流程/img/1.png b/zh-cn/doc/JCNC项目开发流程/img/1.png new file mode 100644 index 0000000..3e36958 Binary files /dev/null and b/zh-cn/doc/JCNC项目开发流程/img/1.png differ diff --git a/zh-cn/doc/JCNC项目开发流程/img/2.png b/zh-cn/doc/JCNC项目开发流程/img/2.png new file mode 100644 index 0000000..eebe93d Binary files /dev/null and b/zh-cn/doc/JCNC项目开发流程/img/2.png differ diff --git a/zh-cn/doc/JCNC项目开发流程/img/3.png b/zh-cn/doc/JCNC项目开发流程/img/3.png new file mode 100644 index 0000000..a4571fe Binary files /dev/null and b/zh-cn/doc/JCNC项目开发流程/img/3.png differ diff --git a/zh-cn/doc/JCNC项目开发流程/img/4.png b/zh-cn/doc/JCNC项目开发流程/img/4.png new file mode 100644 index 0000000..82e99f1 Binary files /dev/null and b/zh-cn/doc/JCNC项目开发流程/img/4.png differ diff --git a/zh-cn/doc/JCNC项目开发流程/img/5.png b/zh-cn/doc/JCNC项目开发流程/img/5.png new file mode 100644 index 0000000..448aa35 Binary files /dev/null and b/zh-cn/doc/JCNC项目开发流程/img/5.png differ diff --git a/zh-cn/doc/JCNC项目开发流程/img/6.png b/zh-cn/doc/JCNC项目开发流程/img/6.png new file mode 100644 index 0000000..265bc3a Binary files /dev/null and b/zh-cn/doc/JCNC项目开发流程/img/6.png differ diff --git a/zh-cn/doc/JCNC项目开发流程/img/7.png b/zh-cn/doc/JCNC项目开发流程/img/7.png new file mode 100644 index 0000000..62ce588 Binary files /dev/null and b/zh-cn/doc/JCNC项目开发流程/img/7.png differ diff --git a/zh-cn/doc/JCNC项目开发流程/img/8.png b/zh-cn/doc/JCNC项目开发流程/img/8.png new file mode 100644 index 0000000..e0be4d2 Binary files /dev/null and b/zh-cn/doc/JCNC项目开发流程/img/8.png differ diff --git a/zh-cn/doc/JCNC项目开发流程/img/9.png b/zh-cn/doc/JCNC项目开发流程/img/9.png new file mode 100644 index 0000000..a414773 Binary files /dev/null and b/zh-cn/doc/JCNC项目开发流程/img/9.png differ diff --git a/zh-cn/doc/doc-jnotepad/doc-jnotepad.md b/zh-cn/doc/doc-jnotepad/doc-jnotepad.md deleted file mode 100644 index 8420d77..0000000 --- a/zh-cn/doc/doc-jnotepad/doc-jnotepad.md +++ /dev/null @@ -1,80 +0,0 @@ -# JNotepad - -![](https://img.shields.io/badge/Windows-Passing-49%2C198%2C84.svg?style=falt&logo=Windows) -![](https://img.shields.io/badge/Ubuntu-Passing-49%2C198%2C84.svg?style=falt&logo=Ubuntu) -![](https://img.shields.io/badge/MacOS-Passing-49%2C198%2C84.svg?style=falt&logo=Apple) - - -JNotepad(Java Notepad)是一款简约而强大的跨平台文本编辑器,旨在提供用户友好的界面和丰富的功能。无论你是在Linux、Windows还是macOS系统上使用,JNotepad都能满足你对文本编辑和查看的需求。 JNotepad使用Java语言编写,并基于JavaFX框架开发,具有良好的可扩展性和稳定性。 -## 功能介绍 - -- 文本编辑和查看:JNotepad提供了完善的文本编辑和查看功能,使你能够轻松创建、编辑和浏览各种类型的文本文件。 - -- 跨平台支持:不论你使用哪种操作系统,JNotepad都能够无缝地适应,并提供一致的用户体验。 - -- 轻量级设计:JNotepad采用简约而现代的设计风格,界面清晰简洁,使得使用起来非常直观和便捷。 - -- 基于Java:JNotepad使用Java语言编写,并基于JavaFX框架开发,具有良好的可扩展性和稳定性。 - - -## 安装教程 - -1. Windows 平台,可以直接使用我编译好的可执行程序或自己编译 - -[gitee-download]: https://gitee.com/jcnc-org/JNotepad/releases -[java-download]: https://www.oracle.com/cn/java/technologies/downloads/ -[qq-url]: http://qm.qq.com/cgi-bin/qm/qr?_wv=1027&k=zOfwWb1lcle68cbEdJCjSIp3Itx0nEC0&authKey=bOsZFT9OVYZpZQbS6IYO4onBQoeBorF5nanMEi1G%2FgPbzmUkOweXBo9qB0G34R5K&noverify=0&group_code=386279455 - - - -- [下载][gitee-download] - -2. Linux/MacOS 平台,查看入门指南 - - -## 入门指南 - -要使用 JNotepad,请按照以下步骤进行: - -1. 下载并安装 Java(如果尚未安装)。 -- [下载][gitee-download] - -2. 克隆或下载 JNotepad 项目。 -
git clone https://gitee.com/jcnc-org/JNotepad.git
-3. 在您偏好的 Java IDE 中打开项目。 - -## 使用方法 - -1. 运行 `JNotepad` 类以启动应用程序。 -2. 主窗口将显示菜单栏、标签区域和状态栏。 -3. 使用菜单栏执行各种操作: -- `文件 > 新建`:创建一个带有空白文本区域的新标签。 -- `文件 > 打开`:打开现有文本文件进行编辑。 -- `文件 > 保存`:将当前活动标签的内容保存到关联文件中。 -- `文件 > 另存为`:将当前活动标签的内容保存为新文件。 -4. 在每个标签的文本区域中编辑内容。 -5. 状态栏将显示有关光标位置和文本统计信息的信息。 - -## 依赖项 - - - - org.openjfx - javafx-controls - 17.0.1 - - -## 软件运行截图 -- Windows 平台 - ![Windows](screenshot/windows-1.png) -- MacOS 平台 - ![MacOS](screenshot/Mac0S-1.png) - -### 参与贡献 - -1. Fork 本仓库 -1. 加入JCNC社区 -1. [加入QQ群:386279455][qq-url] -1. 新建分支 -1. 提交代码 -1. 新建 Pull Request diff --git a/zh-cn/doc/doc-jnotepad/screenshot/Mac0S-1.png b/zh-cn/doc/doc-jnotepad/screenshot/Mac0S-1.png deleted file mode 100644 index 78515ca..0000000 Binary files a/zh-cn/doc/doc-jnotepad/screenshot/Mac0S-1.png and /dev/null differ diff --git a/zh-cn/doc/doc-jnotepad/screenshot/windows-1.png b/zh-cn/doc/doc-jnotepad/screenshot/windows-1.png deleted file mode 100644 index 32f64ba..0000000 Binary files a/zh-cn/doc/doc-jnotepad/screenshot/windows-1.png and /dev/null differ diff --git a/zh-cn/doc/doc.md b/zh-cn/doc/doc.md deleted file mode 100644 index 1248433..0000000 --- a/zh-cn/doc/doc.md +++ /dev/null @@ -1,13 +0,0 @@ -# JCNC开发者文档 - -本目录是JCNC开发者文档的中文目录。目录内容包括: - -### 新手指南 - -[新人参与开源项目指南](guide.md) - -[Git常见命令](gitcode.md) - -### 项目文档 - -[JNotepad文档](doc-jnotepad/doc-jnotepad.md) \ No newline at end of file diff --git a/zh-cn/doc/开发规范/编码规范.md b/zh-cn/doc/开发规范/编码规范.md deleted file mode 100644 index d689493..0000000 --- a/zh-cn/doc/开发规范/编码规范.md +++ /dev/null @@ -1,392 +0,0 @@ -# JCNC编码规范 -[1 说明](#1-说明) -* [1.1 范围](#11-范围) -* [1.2 术语和定义](#12-术语和定义) - -[2 排版规则](#2-排版规则) -* [2.1 编码](#21-编码) -* [2.2 页宽](#22-页宽) -* [2.3 换行](#23-换行) -* [2.4 缩进](#24-缩进) -* [2.5 空行](#25-空行) -* [2.6 大括号](#26-大括号) -* [2.7 小括号](#27-小括号) -* [2.8 空格](#28-空格) -* [2.9 TODO](#29-todo) -* [2.10 import](#210-import) -* [2.11 变量](#211-变量) - -[3 命名规范](#3-命名规范) -* [3.1 package](#31-package) -* [3.2 Class](#32-class) -* [3.3 Interface](#33-Interface) -* [3.4 方法命名](#34-方法命名) -* [3.5 变量](#35-变量) - -[4 注释规范](#4-注释规范) -* [4.1 文档注释](#41-文档注释) -* [4.2 块注释](#42-块注释) -* [4.3 单行注释](#43-单行注释) -* [4.4 注意事项](#44-注意事项) - -[5 编程技巧](#5-编程技巧) -* [5.1 类](#51-类) -* [5.2 方法](#52-方法) -* [5.3 控制语句](#53-控制语句) -* [5.3 数据校验](#54-数据校验) - -[Creators](#creators) - -## 1 说明 -### 1.1 范围 -本规范规定了使用Java语言时排版、注释、命名、编码的规则和建议。 -本规范适用于使用Java语言成的产品和项目。 - -### 1.2 术语和定义 -* 规则:必须遵守 -* 建议:有充足的理由时可不遵守,但必须优先考虑 -* 格式:对规范格式的说明或模板 -* 说明:对规范或建议进行的必要解释 -* 示例:对规范或建议从正反两方面给出的例子 -* 补充:一些实践技巧或额外的说明 - -## 2 排版规则 -### 2.1 编码 -**规 则:IDE的text file encoding设置为UTF-8。** -**规 则:IDE中文件的换行符使用Unix格式,不要使用windows格式。** -### 2.2 页宽 -**规 则:编辑器列宽应设置为100列** -**说 明:** 当一行代码的长度过长时,为了阅读方便,应该换行展示。但因为每个人的字体设置,屏幕大小有所不同,因此需要统一列宽为100列。 -**补 充:** -在Eclipse中我们可以设置自动排版的单行代码最大宽度。选择:【Window】→【Preferences】→【Java】→【Code Style】→【Formatter】,点击“new”新建一个“Profile”(若已经是自定义的profile则不需要新建)。选择选项卡【Line Wrapping】,修改下边的“Maximum line width”为100。 -在Eclipse中我们可以在编辑界面设置一条参考线提醒我们代码宽度。选择:【Window】→【Preferences】→【General】→【Editors】→【Text Editors】。将右侧的单选框“Show print margin”设置为选中状态,然后设置下边的“Print margin column”为100。 -### 2.3 换行 -**规 则:第二行相对第一行缩进4个空格,从第三行开始,不再缩进,而是与第二行保持同级。** -**规 则:运算符、方法调用的点符号与下文一起换行。** -**规 则:在多个参数超长时,逗号后换行。** -**示 例:** -```java -//符合规范 -StringBuffer sb = new StringBuffer(); -//超过100个字符的时候,换行缩进4个空格,并且方法钱的点符号一起换行 -sb.append("wan").append("fang")... - .append("shu")... - .append("ju")... - .append("gu"); -//在逗号后换行 -method(arg1, arg2, arg3, ...argx, - argx1) -``` -### 2.4 缩进 -**规 则:程序块需要采用缩进风格编写,缩进为4个空格。** -**说 明:** 不同的编辑工具会导致Tab字符的宽度不统一,在编码时应注意其可能造成的问题。 -**补 充:** -在Eclipse中我们可以设置Tab的宽度和输入空格数。 -选择:【Window】→【Preferences】→【General】→【Editors】→【Text Editors】。将右侧的“Display tab width”设置为4,将单选框“Insert spaces for tabs”设置为选中状态。 -选择:【Window】→【Preferences】→【Java】→【Code Style】→【Formatter】,点击“new”新建一个“Profile”(若已经是自定义的profile则不需要新建)。选择选项卡【Indentation】,将左侧的下拉框“Tab policy”改为Spaces only。然后修改“Tab size”为4。 -### 2.5 空行 -**规则:独立的程序块与变量声明之间加空行分割** -**示 例:** -```java -//不符合规范 -if(log.getLevel() < LogConfig.getRecordLevel()){ - return; -} -LogWriter writer; -int index; -``` -```java -//符合规范 -if(log.getLevel() < LogConfig.getRecordLevel()){ - return; -} - -LogWriter writer; -int index; -``` -### 2.6 大括号 -**规 则:使用大括号(即使是可选的)** -**说 明:** 大括号与if, else, for, do, while即使只有一条语句或是空,也应该把大括号写上。 -**示 例:** -```java -//不符合规范的 -if(writeToFile) - writeFileThread.interrupt(); -``` -```java -//符合规范的 -if(writeToFile){ - writeFileThread.interrupt(); -} -``` - -**规 则:对于非空块和块状结构,大括号遵循Kernighan和Ritchie风格(紧凑风格)。** -**说 明:** - -* 左大括号前不换行 -* 左大括号后换行 -* 右大括号前换行 -* 如果右大括号是一个语句、函数体或类的终止,则右大括号后换行; 否则不换行。例如,如果右大括号后面是else或逗号,则不换行 - -**示 例:** -```java -//不符合规范 -if(isOk) -{ - someThing(); -} -else -{ - otherThing(); -} -``` -```java -//符合规范 -if(isOk){ - someThing(); -}else{ - otherThing(); -} -``` -**补 充:** -Kernighan和Ritchie风格指的是,Kernighan和Ritchie的《C Programming Language》一书中约定的“大括号放在同一行”规则。这种编码风格比较紧凑,也是Java官方和Google等诸多主流公司遵循的编码风格。 - -**建 议:空块可以简洁的写成{},除非它是多块语句的一部分。** -**说 明:** 一个空的块状结构里什么也不包含,大括号可以简洁地写成{},不需要换行。例外:如果它是一个多块语句的一部分(if/else 或 try/catch/finally) ,即使大括号内没内容,右大括号也要换行。 -**示 例:** -```java -void doNothing() {} -``` -### 2.7 小括号 -**规 则:用小括号来限定计算优先级** -**说 明:** 没有理由假设代码的阅读者能够清晰的记住整个Java运算符优先级表。 -###2.8 空格 -**规 则:函数参数在“,”后需要加空格。** -**规 则:各种双目操作符,比如“=”,“<”等,前后都要加空格。** -**规 则:if, while等关键字后面需要有空格。** -**补 充:** 基本上Eclipse的自动格式化功能,就能保证这些空格的正确使用。 -### 2.9 TODO -**规 则:TODO用于任务标记,要避免出现无用的TODO标记** -**说 明:** 自动生成代码中如果有TODO标记,请根据需要编写注释或删除TODO标记,避免产生无用的TODO,影响他人跟踪任务。 -### 2.10 import -**规 则:import不要使用通配符** -**说 明:** 不要出现类似这样的import语句:import java.util.*。使用通配符会造成歧义,及不可预期的冲突或bug。程序应保持清晰、易懂、无歧义。 - -**规 则:import不要引用不需要的包** -### 2.11 变量 -**规 则:每次只声明一个变量** -**说 明:** 不要使用组合声明(int a,b;),减少歧义性,增强可读性 - -**规 则:需要时才声明,并尽快进行初始化** - -**规 则:使用非C风格的数组声明** -**说 明:** 使用String[] args,而非String args[] - -**建 议:谨慎的使用公共变量** -**说 明:** 公共变量是增大模块间耦合的原因之一,应减少没必要的公共变量以降低模块间的耦合度。 - -## 3 命名规范 -**规 则:命名应尽可能做到见名知意,力求语义表达清晰完整。** -**规 则:代码中的命名均不能以下划线或美元符号开始,也不能以下划线或美元符号结束。** -**规 则:代码中的命名严禁使用拼音与英文混合的方式,更不允许直接使用中文的方式。** -### 3.1 package -**规 则:包名均采用小写** -**建 议:包名一般为一个单词** - -**规 则:内部包名规则一般为com.部门名称/站点域名.产品名/项目名.模块名,通用包放在com.wanfangdata下** -**说 明:** 由于历史遗留原因,部分内部包名格式为:部门名称.产品名/项目名.模块名。原则上,新建的包不要用此命名规则,但暂时也不修改此规则的包名 -### 3.2 Class -**规 则:类的命名应该都是名词** -**规 则:类名第一个字母要为大写,其他每个单词的第一个字母为大写(UpperCamelCase)** -**规 则:类名要用完整的单词,除非是被公认的单词缩写** -**规 则:抽象类命名应以Abstract为开头** -**规 则:异常类命名使用Exception结尾** -**规 则:测试类命名以它要测试的类名称开始,以Test结尾** - -**建 议:如果使用了设计模式,建议在类(接口)命名中体现出具体的设计模式** -**建 议:枚举类名以Enum后缀结束,美剧成员名称需要全部大写,单词间用下划线分隔。** -**示 例:** -```java -public class BalanceLimitAccountHandler; -public interface SqlSessionFactory; -public class LoginProxy; -``` -### 3.3 Interface -**规 则:接口名的命名应该是名词或形容词** -**规 则:接口名应以大写的I开头,其他单词第一个字母都要大写(UpperCamelCase)** -**规 则:接口名要用完整的单词,除非是被公认的单词缩写** -**建 议:接口类中的方法和属性不要加任何修饰符好(public也不要加)。** -### 3.4 方法命名 -**规 则:方法名应以动词或惯用短语描述** -**规 则:方法名第一个字母都要小写,其他每个单词第一个字母都要大写(lowerCamelCase)** - -**建 议:方法名中不要加入对象名字,可能会带来误解。** -**说 明:** 因为对象本身已经包含在调用语句中了 -### 3.5 变量 -**规 则:应避免用单个字符命名变量** -**规 则:代码中严禁使用拼音与英文混合的方式,优先使用英文而非拼音** - -**规 则:参数名第一个字母使用小写,其他每个单词第一个字母大写(lowerCamelCase)** - -**规 则:常量名应该为名词或名词短语** -**规 则:常量名每一个字母都应为大写,单词之间用“_”分开。** - - -**规 则:不允许出现任何魔法值(未经定义的常量)直接出现在代码中。** -**建 议:不要使用一个常量类维护所有常量,应该按常量功能进行归类,分开维护。** - -**规 则:long或者Long初始赋值时,必须使用大写的L,不能是小写的l,小写容易跟数字1混淆,造成误解。** - -**规 则:局部变量名第一个字母使用小写,其他每个单词第一个字母大写(lowerCamelCase)。** -**规 则:局部变量名可以更宽松的使用缩写,但除了临时变量和循环变量应避免单字符命名。** - -**规 则:POJO类中布尔类型的变量,都不要加is,否则部分框架解析会引起序列化错误。(参考阿里java规范)** -**说 明:** -定义为基本数据类型Boolean isSuccess;的属性,它的方法也是isSuccess(),RPC框架在反向解析的时候,“以为”对应的属性名称是success,导致属性获取不到,进而抛出异常。 -## 4 注释规范 -### 4.1 文档注释 -**规 则:一般情况下,源程序有效注释量必须在30%以上。** -**规 则:接口、Action方法、工具类的public方法等凡是提供给外界调用的方法都必须添加文档注释。** -**规 则:文档注释用于描述Java的类、接口、构造函数、方法,一级成员变量(field)。** - -**规 则:类和接口的注释在 package 关键字之后,class 或者 interface 关键字之前。** -**规 则:类和接口的注释内容:类的注释主要是一句话功能简述、功能详细描述。** -**说 明:** 可根据需要列出:版本号、生成日期、作者、内容、功能、与其它类的关系等。 如果一个类存在Bug,请如实说明这些Bug - -**规则:对于接口需要标注** - -```java -/** - * 〈一句话功能简述〉 - * 〈功能详细描述〉 - * @author [作者] - * @see [相关类/方法] - * @deprecated - */ -``` -**示例:** -```java -/** - * LogManager 类集中控制对日志读写的操作。 - * 全部为静态变量和静态方法,对外提供统一接口。分配对应日志类型的读写器, - * 读取或写入符合条件的日志纪录。 - * @author 张三,李四,王五 - * @see LogIteraotor - * @see BasicLog - */ -``` -**规 则:类属性、公有和保护方法注释:写在类属性、公有和保护方法上面** -**规 则:成员变量使用文档注释,而不是单行注释或尾部注释** -**规 则:成员变量注释内容:成员变量的意义、目的、功能,可能被用到的地方** - -**规 则:公有和保护方法注释内容:列出方法的一句话功能简述、功能详细描述、输入参数、输出参数、返回值、违例等** -**说明:** -```java -/** - * 〈一句话功能简述〉 - * 〈功能详细描述〉 - * @param [参数1] [参数1说明] - * @param [参数2] [参数2说明] - * @return [返回值类型] [返回类型说明] - * @exception/throws [违例类型] [违例说明] - * @see [类、类#方法、类#成员] - * @deprecated - */ -``` -**示 例:** -```java -/** - * 根据日志类型和时间读取日志。 - * 分配对应日志类型的LogReader, 指定类型、查询时间段、条件和反复器缓冲数, - * 读取日志记录。查询条件为null或0表示无限制,反复器缓冲数为0读不到日志。 - * 查询时间为左包含原则,即 [startTime, endTime) 。 - * @param logTypeName 日志类型名(在配置文件中定义的) - * @param startTime 查询日志的开始时间 - * @param endTime 查询日志的结束时间 - * @param logLevel 查询日志的级别 - * @param userName 查询该用户的日志 - * @param bufferNum 日志反复器缓冲记录数 - * @return LogIterator 结果集,日志反复器 - * @since CommonLog1.0 - */ -public static LogIterator read(String logType, Date startTime, Date endTime, - int logLevel, String userName, int bufferNum) -``` -### 4.2 块注释 -**规 则:块注释用来为文件、方法、数据结构和算法进行描述或是用来划分文件的模块** -**规 则:块注释一般放在每个文件的开始或是每个模块、方法的前面,也可能放在方法之内** -**规 则:在块注释前应该有一个空行,以便同其他代码进行分割** -### 4.3 单行注释 -**规 则:简短的注释可以只用一行来说明,并与后面的代码进行相同的缩进** -**规 则:单行注释如果一行写不下,就应该考虑使用块注释** -**规 则:在单行注释前应该有一个空行,以便痛其他代码进行分割** -### 4.4 注意事项 -**规 则:注释必须与代码同步更新** -**建 议:应避免注释中提供代码中已清晰表达出来的重复信息** -**建 议:当要写非文档注释的时候,应考虑下是否可以将代码写的更清晰易懂** -**说 明:** 过多的非文档注释,往往反映出代码的低质量 -**建 议:TODO与FIXME注释格式建议包含(标记人,标记时间,[预计处理时间])** -## 5 编程技巧 -### 5.1 类 -**规 则:明确类的功能,精确(而非近似)地实现类的设计,一个类仅实现一组相近的功能** -**说 明:** 划分类的时候,应该尽量把逻辑处理、数据和显示分离,实现类功能的单一性 -**示 例:** 数据类不能包含数据处理的逻辑,通信类不能包含显示处理的逻辑 - -**规 则:所有的数据类必须重载toString() 方法,返回该类有意义的内容** -**说 明:** 如果父类中已经实现了较为合理的toString()方法,子类可以继承而不必重写 - -**规 则:只要重写equals,就必须重写hashCode。** -**规 则:因为Set存储的是不重复的对象,依据hashCode和equals进行判断,所以Set存储的对象必须重写这两个方法。** -**规 则:如果自定义对象做为Map的键,那么必须重写hashCode和equals。** - -**建 议:@Override能用则用** -**说 明:** 只要是合法的,就把@Override注解用上。 -**补 充:** 参考自谷歌编码规范 -### 5.2 方法 -**规 则:参数个数>4个时抽取参数类** -**建 议:参数列表中请尽量不取用true、false类参数,避免因为调用者不明确导致的问题** - -**建 议:返回调用函数方应该知道的消息,慎用void** -**建 议:返回空的集合时使用Collections.empty方法,不要直接返回null** - -**规 则:每个方法不得超过100行** -**建 议:超过50行的代码建议考虑重构** - -**规 则:方法不得包含隐式功能** -**说 明:** 如:getIdsFromList(List modelList)仅应该执行从list获取id的操作,而不应该对list有修改 - -**规 则:避免使用不易理解的数字,用有意义的标识来替代** -**规 则:涉及物理状态或者含有物理意义的常量,不应直接使用数字,必须用有意义的静态变量来代替** -### 5.3 控制语句 -**规 则:在一个switch块内,都必须包含一个default语句并且放在最后,即使它什么代码也没有** -**规 则:在if/else/for/while/do语句中必须使用大括号,即使只有一行代码,避免使用下面的形式:if (condition) statements;** - -**规 则:尽量少用else** -**示 例:** -```java -//不符合规范 -if(condition) -{ - ... - return obj; -} -//接着写else的业务逻辑代码 -``` -### 5.4 数据校验 -**建 议:方法中需要进行参数校验的场景** -* 调用频次低的方法 -* 执行时间开销很大的方法,参数校验时间几乎可以忽略不计,但如果因为参数错误导致中间执行回退,或者错误,那得不偿失。 -* 需要极高稳定性和可用性的方法 -* 对外提供的开放接口,不管是RPC/API/HTTP接口 -* 敏感权限入口 - -**建 议:方法中不需要参数校验的场景** -* 极有可能被循环调用的方法,不建议对参数进行校验。但在方法说明里必须注明外部参数检查。 -* 底层的方法调用频度都比较高,一般不校验。(参数错误不太可能到底层才会暴露问题) -* 被声明成private只会被自己代码所调用的方法。 -## Creators - -引用自[编码规范](https://github.com/wanfangdata/guide/blob/master/java%E5%BC%80%E5%8F%91%E8%A7%84%E8%8C%83/%E7%BC%96%E7%A0%81%E8%A7%84%E8%8C%83.md) - -原作者:[梅葆瑞](https://github.com/meibaorui) [李辉]() [张锐](https://github.com/pizirui) - diff --git a/zh-cn/doc/guide.md b/zh-cn/doc/第一次接触开源项目.md similarity index 98% rename from zh-cn/doc/guide.md rename to zh-cn/doc/第一次接触开源项目.md index e11d30e..d31f4ae 100644 --- a/zh-cn/doc/guide.md +++ b/zh-cn/doc/第一次接触开源项目.md @@ -1,4 +1,4 @@ -# 新人参与开源项目指南 +# 第一次接触开源项目 ## 1. 什么是开源? @@ -15,7 +15,7 @@ * 提交: 提交是对代码所做更改的快照,它包含有关更改内容的说明。 * 拉取请求(Pull Request): 这是将你的更改合并到主代码库的方式,维护者和其他贡献者可以审查并提供反馈。 - [Git常见命令](gitcode.md) + [Git常见命令](Git常用命令.md) ## 3. 选择一个适合的开源项目