代码规范¶
我们大致遵循谷歌的 Java 风格指南 <https://google.github.io/styleguide/javaguide.html>’_ 并有一些微小改动。下面介绍了这些改动。
小技巧
你可以使用我们的代码规范文件来让 IDE 为你自动整理代码。详见为开发作准备。
- 行结束符
- 在提交时使用 Unix 风格的行尾 (\n)
- Windows的git用户可以运行
git config --global core.autocrlf true
来让git进行自动转换
- Windows的git用户可以运行
- 在提交时使用 Unix 风格的行尾 (\n)
- 列宽
- Javadoc:80字符
- 代码:150字符
- 能提高可读性时可自由换行
- 缩进
- 使用4个空格来缩进,而不是2个
- 空行
- 在每个类、接口、枚举等的第一个成员前(例如在
class Example {
之后)和最后一个成员后放置一个空行
- 在每个类、接口、枚举等的第一个成员前(例如在
- 文件头
- 文件头必须包含项目的许可头。请使用 gradle 的
licenseFormat
来自动添加。
- 文件头必须包含项目的许可头。请使用 gradle 的
- 引用
- 所有引用必须以下列方式分组,每组之间用一个空白行分隔
- 静态引用
- 所有其他的引用
- 对``java``包的引用
- 对``javax``包的引用
- 和Google风格中把引用以顶层包分组不同,我们将引用全部分在同一组。
- 所有引用必须以下列方式分组,每组之间用一个空白行分隔
- 异常
- 对于被忽略的异常,请将异常变量命名为``ignored``
- 字段访问
- 使用
this
来访问 所有的 字段
- 使用
- Javadocs
- 不要使用
@author
- 用
<p>
和</p>
包裹段落 - 每个@语句的描述部分首字母大写。例如
@param name Player to affect
,不要有句号
- 不要使用
- 文件结尾
- 每个文件结尾均应有一空行。
代码约定¶
- Use 使用 Optional instead of returning
null
in the API - 所有能接受
null
的方法参数必须被标注成@Nullable
(位于 javax.*)。所有的方法和参数默认均为@Nonnull
- 使用 Google Preconditions 来检查 null 和参数。
Gist¶
尽管我们强烈建议你阅读Google的Java代码约定,但是它们实在是太长了。为了帮助你快速开始,下面是一个格式正确的代码样例:
/*
* This file is part of Sponge, licensed under the MIT License (MIT).
*
* Copyright (c) SpongePowered <https://www.spongepowered.org>
* Copyright (c) contributors
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in
* all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
* THE SOFTWARE.
*/
package org.spongepowered.example;
import static com.google.common.base.Preconditions.checkNotNull;
import com.google.inject.Inject;
import org.slf4j.Logger;
import java.util.Optional;
import java.util.Random;
import java.util.concurrent.ThreadLocalRandom;
import javax.annotation.Nullable;
/**
* An example class which generates a new ID based on a specified base string
* and a randomly generated integer.
*
* <p>There is a chance the integer purposely fails to generate, in which case
* you can choose to provide a backup integer.</p>
*/
public class Example {
private static final long SEED = 4815162342L;
@Inject
private Logger logger;
private final String base;
private final Random random;
public Example(String base) {
checkNotNull(base, "The specified base string cannot be null!");
this.base = base;
this.random = ThreadLocalRandom.current();
this.random.setSeed(SEED);
}
/**
* Generates and returns an ID using the base string specified on creation
* or the alternative string if specified as well as a randomly generated
* integer, which purposely fails to generate around 50% of the time.
*
* <p>A {@link ThreadLocalRandom} is used to check if the integer should
* be generated and generates the integer itself if so.</p>
*
* @param alternate An alternate base string which will be used if not null
* @return The generated ID, if available
*/
public Optional<String> generateId(@Nullable String alternate) {
if (this.random.nextBoolean()) {
return Optional.of(alternate == null ? this.base : alternate + " - " + this.random.nextInt());
}
return Optional.empty();
}
/**
* Generates and returns an ID using the base string specified on creation,
* using a randomly generated integer if it was generated successfully, or
* using the backup integer you specify.
*
* <p>A {@link ThreadLocalRandom} is used to check if the integer should
* be generated and generates the integer itself if so. If it was not
* generated, that is when your backup integer will be used.</p>
*
* @param backup A backup integer to use to create the ID with
* @return The generated ID using the generated integer or the ID created
* using the backup integer specified
*/
public String generateId(int backup) {
return generateId(null).orElse(this.base + " - " + backup);
}
}