apache / apache/dubbo

[Enhancement] 改善代码文档化设计

Open
#5,628 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Java
Stars
41.6k
Forks
26.4k
Avg merge
15h 13m
Merged PRs (30d)
4

Description

### 背景

* Dubbo在JavaDoc方面对代码质量检查工具的支持较少

* JSR-305以及其他同类思想提出了一套改善代码检查的机制

### 收益

* 提供更好的兼容性保护

* 更好的支持java代码质量检查工具

* 更好地帮助开发者理解dubbo内部模型

### 建议新增4类注解

#### 1. null值安全类

* [@Nonnull](https://github.com/amaembo/jsr-305/blob/master/ri/src/main/java/javax/annotation/Nonnull.java)

* [@Nullable](https://github.com/amaembo/jsr-305/blob/master/ri/src/main/java/javax/annotation/Nullable.java)

#### 2. 并发类

* [NotThreadSafe](https://github.com/amaembo/jsr-305/blob/master/ri/src/main/java/javax/annotation/concurrent/NotThreadSafe.java)

* [ThreadSafe](https://github.com/amaembo/jsr-305/blob/master/ri/src/main/java/javax/annotation/concurrent/ThreadSafe.java)

* [Immutable](https://github.com/amaembo/jsr-305/blob/master/ri/src/main/java/javax/annotation/concurrent/Immutable.java)

* [GuardedBy](https://github.com/amaembo/jsr-305/blob/master/ri/src/main/java/javax/annotation/concurrent/GuardedBy.java)

```
用法是@GuardedBy(lock),这意味着有保护的字段或方法只能在线程持有锁时被某些线程访问
```

#### 3. 资源管理类

* [WillClose](https://github.com/amaembo/jsr-305/blob/master/ri/src/main/java/javax/annotation/WillClose.java)

* [WillNotClose](https://github.com/amaembo/jsr-305/blob/master/ri/src/main/java/javax/annotation/WillNotClose.java)

#### 4. 元数据类

* [Beta](https://github.com/google/guava/blob/master/android/guava/src/com/google/common/annotations/Beta.java)

```
@Beta表明一个公用API的未来版本是受不兼容变更或删除限制的
拥有这个注释标志的API不受任何兼容性保证
```

### 建议为核心模块增加package-info

例如:Guava的[package-info](https://github.com/google/guava/blob/master/android/guava/src/com/google/common/annotations/package-info.java)

### 建议适当拆分 公用API 和 厂商实现逻辑

问题:

目前 API域 和 实现域 的代码在同一个平面上,并无明确的分界特征。

使用者容易在业务代码中引用 厂商逻辑,厂商逻辑 代码随着升级而改变,就会带来兼容问题。

举个正例:

sun公司把内部逻辑放在 sun包下,把外部逻辑放在 java包 下。

这样,就能提供更好的兼容性保护。

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.