This is an automated email from the ASF dual-hosted git repository.
casion pushed a commit to branch dev
in repository https://gitbox.apache.org/repos/asf/incubator-linkis-website.git
The following commit(s) were added to refs/heads/dev by this push:
new 26d6bdb232 Optimizing annotation specifications (#546)
26d6bdb232 is described below
commit 26d6bdb232a35853016716010f55337034d98f53
Author: aiceflower <[email protected]>
AuthorDate: Wed Oct 19 17:19:32 2022 +0800
Optimizing annotation specifications (#546)
---
.../programming-specification.md | 77 ++++++++++++++++++++
.../programming-specification.md | 85 +++++++++++++++++++++-
2 files changed, 160 insertions(+), 2 deletions(-)
diff --git a/community/development-specification/programming-specification.md
b/community/development-specification/programming-specification.md
index eb355b8524..b9180105ed 100644
--- a/community/development-specification/programming-specification.md
+++ b/community/development-specification/programming-specification.md
@@ -19,3 +19,80 @@ sidebar_position: 1
## 2. Annotation Protocol
1. [**Mandatory**] The class, class attribute, interface method must be
commented, and the comment must use the Javadoc specification, using the format
of `/**content*/`
2. [**Mandatory**] All abstract methods (including methods in interfaces) must
be annotated with Javadoc. In addition to return values, parameters, and
exception descriptions, they must also indicate what the method does and what
functions it implements
+3. [**Mandatory**] All abstract methods (including methods in interfaces) must
be annotated with Javadoc, indicating what the method does and does in addition
to return values, parameters, and exception descriptions.
+
+
+
+4. [**Mandatory**] method inside a single line comment, a separate line above
the comment statement, use // comment. Multi-line comments inside methods use
/* */ comments, aligned with code.
+
+
+
+Example:
+
+```java
+
+// Store the reflection relation between parameter variable like 'T' and type
like
+
+Map< String, Type> typeVariableReflect = new HashMap< > (a);
+```
+
+5. [**Mandatory**] All enumeration type fields must have a comment stating the
purpose of each data item.
+
+
+
+Example:
+
+```java
+/**
+ * to monitor node status info
+ */
+public enum NodeHealthy {
+
+ /**
+ * healthy status
+ */
+ Healthy,
+
+ /**
+ * EM identifies itself as UnHealthy or
+ * The manager marks it as abnormal in the status of UnHealthy processing
engine.
+ * The manager requests all engines to withdraw forcibly (engine suicide).
+ */
+ UnHealthy,
+
+ /**
+ * The engine is in the alarm state, but can accept tasks
+ */
+ WARN,
+
+ /**
+ * The stock is available and can accept tasks. When the EM status is not
reported for the last n heartbeats,
+ * the Engine that has been started is still normal and can accept tasks
+ */
+ StockAvailable,
+
+ /**
+ * The stock is not available. Tasks cannot be accepted
+ */
+ StockUnavailable;
+```
+
+6. [Recommendation] At the same time of code modification, comments should
also be modified, especially parameters, return values, exceptions, core logic,
etc.
+
+7. [Recommendation] Delete any unused fields, methods, and inner classes from
the class; Remove any unused parameter declarations and internal variables from
the method.
+
+8. Carefully comment out code. Specify above, rather than simply commenting it
out. If no, delete it. There are two possibilities for the code to be commented
out: 1) The code logic will be restored later. 2) Never use it. The former
without the comment information, it is difficult to know the annotation
motivation. The latter suggestion IS deleted directly CAN, if NEED to consult
historical code, log in code WAREHOUSE can.
+
+
+Example:
+
+```java
+ public static final CommonVars<String> TUNING_CLASS =
+ CommonVars.apply(
+ "wds.linkis.cs.ha.class",
"org.apache.linkis.cs.highavailable.DefaultContextHAManager");
+ // The following comment code should be removed
+ // public static final CommonVars<String> TUNING_CLASS =
+ //
CommonVars.apply("wds.linkis.cs.ha.class","org.apache.linkis.cs.persistence.ProxyMethodA");
+```
+
+9. [Reference] for annotation requirements: first, can accurately reflect the
design ideas and code logic; Second, be able to describe the business meaning,
so that other programmers can quickly understand the information behind the
code. A large piece of code with no comments at all is like a book to the
reader. The comments are for the reader, even after a long time, they can
clearly understand the thinking at that time. The comments are also for the
successor to see, so that he can qu [...]
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs-community/current/development-specification/programming-specification.md
b/i18n/zh-CN/docusaurus-plugin-content-docs-community/current/development-specification/programming-specification.md
index 8174cdf0e3..04795eff83 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs-community/current/development-specification/programming-specification.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs-community/current/development-specification/programming-specification.md
@@ -17,5 +17,86 @@ sidebar_position: 1
|配置Key命名|小写'.'分隔| linkis+模块名+keyName| linkis.bml.hdfs.prefix|
## 2. 注释规约
-1. 【**强制**】类、类属性、接口方法必须加注释，且注释必须使用 Javadoc 规范，使用`/**内容*/`格式
-2. 【**强制**】所有的抽象方法（包括接口中的方法）必须要用 Javadoc 注释、除了返回值、参数、
异常说明外，还必须指出该方法做什么事情，实现什么功能
+1. 【**强制**】类、类属性、接口方法必须加注释，且注释必须使用 Javadoc 规范，使用`/**内容*/`格式。
+
+示例：
+```java
+/** Wrap the communication between Bml service */
+public class BmlAppServiceImpl implements BmlAppService {
+ /** Bml client */
+ private BmlClient client;
+}
+```
+2. 【**强制**】所有的类都不要添加创建者。Linkis项目已捐献给Apache，无须添加作者信息。
+
+3. 【**强制**】所有的抽象方法（包括接口中的方法）必须要用 Javadoc 注释、除了返回值、参数、
异常说明外，还必须指出该方法做什么事情，实现什么功能。
+
+4. 【**强制**】方法内部单行注释，在被注释语句上方另起一行，使用 // 注释。方法内部多行注释使用 /* */ 注释，注意与代码对齐。
+
+示例：
+```java
+ // Store the reflection relation between parameter variable like 'T' and
type like
+ Map<String, Type> typeVariableReflect = new HashMap<>();
+```
+5. 【**强制**】所有的枚举类型字段必须要有注释，说明每个数据项的用途。
+
+示例：
+```java
+/**
+ * 节点监控状态信息
+ * to monitor node status info
+ */
+public enum NodeHealthy {
+
+ /**
+ * 状态正常
+ * healthy status
+ */
+ Healthy,
+
+ /**
+ * EM自己标识自己为UnHealthy 或者manager把他标识为UnHealthy 处理引擎状态不正常，
+ * manager主动要求所有的engine强制退出（engine自杀）
+ * EM identifies itself as UnHealthy or
+ * The manager marks it as abnormal in the status of UnHealthy processing
engine.
+ * The manager requests all engines to withdraw forcibly (engine suicide).
+ */
+ UnHealthy,
+
+ /**
+ * 引擎处于告警状态，但是可以接受任务
+ * The engine is in the alarm state, but can accept tasks
+ */
+ WARN,
+
+ /**
+ * 存量可用状态，可以接受任务。当EM状态最近n次心跳没有上报，但是已经启动的Engine还是正常的可以接受任务
+ * The stock is available and can accept tasks. When the EM status is not
reported for the last n heartbeats,
+ * the Engine that has been started is still normal and can accept tasks
+ */
+ StockAvailable,
+
+ /**
+ * 存量不可用状态，不可以接受任务。（超过n+1没上报心跳）或者（EM自己判断，但是服务正常的情况），
+ * 但是如果往上面提交任务会出现error失败情况 EM处于StockUnavailable时，
+ * manager主动要求所有的engine非强制退出，manager需要将EM标识为UnHealthy。
+ * 如果StockUnavailable状态如果超过n分钟，则发送IMS告警
+ * The stock is not available. Tasks cannot be accepted
+ */
+ StockUnavailable;
+}
+```
+6. 【推荐】代码修改的同时，注释也要进行相应的修改，尤其是参数、返回值、异常、核心逻辑等的修改。
+7. 【推荐】在类中删除未使用的任何字段、方法、内部类；在方法中删除未使用的任何参数声明与内部变量。
+8.
【参考】谨慎注释掉代码。在上方详细说明，而不是简单地注释掉。如果无用，则删除。代码被注释掉有两种可能性：1）后续会恢复此段代码逻辑。2）永久不用。前者如果没有备注信息，难以知晓注释动机。后者建议直接删掉即可，假如需要查阅历史代码，登录代码仓库即可。
+
+示例：
+```java
+ public static final CommonVars<String> TUNING_CLASS =
+ CommonVars.apply(
+ "wds.linkis.cs.ha.class",
"org.apache.linkis.cs.highavailable.DefaultContextHAManager");
+ // 应该删除如下注释代码
+ // public static final CommonVars<String> TUNING_CLASS =
+ //
CommonVars.apply("wds.linkis.cs.ha.class","org.apache.linkis.cs.persistence.ProxyMethodA");
+```
+9.
【参考】对于注释的要求：第一、能够准确反映设计思想和代码逻辑；第二、能够描述业务含义，使别的程序员能够迅速了解到代码背后的信息。完全没有注释的大段代码对于阅读者形同天书，注释是给自己看的，即使隔很长时间，也能清晰理解当时的思路；注释也是给继任者看的，使其能够快速接替自己的工作。
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
