JAVA编程指导

AVA编程指导

从twitter的编程指导翻译过来的。(原文地址)

[TOC]

代码风格

格式化

什么时候应该换行?

有两个理由:

  1. 超过了每行的最大长路
  1. 你需要用换行来表示你的想法的停顿

写代码就像写文章,要用代码来完整表达你的意思。

缩进

我们使用1BTS (1TBS)原则,缩进2个空格。

:::java

// 好的示范.
if (x < 0) {
  negative(x);
} else {
  nonnegative(x);
}

// 不好的示范.
if (x < 0)
  negative(x);

// 也不要这样.
if (x < 0) negative(x);

连续的缩进是4个空格,字符串每一行用4个空格连续。 譬如

:::java
// 不好的示范
//   - 每一层随意换行.
//   - 信息非常难以找到.
throw new IllegalStateException("Failed to process request" + request.getId()
    + " for user " + user.getId() + " query: '" + query.getText()
    + "'");

// 好的示范.
//   - 代码自解释.
//   - 添加代码也比较容易.
throw new IllegalStateException("Failed to process"
    + " request " + request.getId()
    + " for user " + user.getId()
    + " query: '" + query.getText() + "'");

如果方法名字较长时,如何声明呢?

	 :::java
 // 随意摆放各个变量.不在乎每一行的字母数量
 String downloadAnInternet(Internet internet, Tubes tubes,
     Blogosphere blogs, Amount<Long, Data> bandwidth) {
   tubes.download(internet);
   ...
 }

 // 可以接受的.
 String downloadAnInternet(Internet internet, Tubes tubes, Blogosphere blogs,
     Amount<Long, Data> bandwidth) {
   tubes.download(internet);
   ...
 }

 // 好一点, 在声明和代码之间有空格分开.
 String downloadAnInternet(Internet internet, Tubes tubes, Blogosphere blogs,
     Amount<Long, Data> bandwidth) {

   tubes.download(internet);
   ...
 }

 // 也不错,不过如果变量名过长,很容易看不到括号
 public String downloadAnInternet(Internet internet,
                                  Tubes tubes,
                                  Blogosphere blogs,
                                  Amount<Long, Data> bandwidth) {
   tubes.download(internet);
   ...
 }

 // 最推荐的方式,声明和变量分开,有空格区分.
 public String downloadAnInternet(
     Internet internet,
     Tubes tubes,
     Blogosphere blogs,
     Amount<Long, Data> bandwidth) {

   tubes.download(internet);
   ...
 }
链式函数调用
:::java
// 不好.
//   - 代码不讲究.
Iterable<Module> modules = ImmutableList.<Module>builder().add(new LifecycleModule())
    .add(new AppLauncherModule()).addAll(application.getModules()).build();

// 好一点.
//   - 每一层逻辑是分开的.
//   - 不过,点号和方法调用没有放在一起
Iterable<Module> modules = ImmutableList.<Module>builder().
    add(new LifecycleModule()).
    add(new AppLauncherModule()).
    addAll(application.getModules()).
    build();

// Good.
//   - 每一行都是一个完整的逻辑.
//   - 清楚知道每一行代码的调用.
Iterable<Module> modules = ImmutableList.<Module>builder()
    .add(new LifecycleModule())
    .add(new AppLauncherModule())
    .addAll(application.getModules())
    .build();
不用tab

tab 在每个IDE里表现不一样。不要用tab做分割哦

结尾不要无谓的空格

变量,类的名字和方法名字

修饰符的顺序

参考 Java Language Specification 8.1.1,8.3.1 和8.4.3).

:::java
// 不好的顺序.
final volatile private String value;

// 好的顺序.
private final volatile String value;

变量命名

不要用超短的变量名
如果需要,变量名里要包含单位
:::java
// 差的.
long pollInterval;
int fileSize;

// 好的.
long pollIntervalMs;
int fileSizeGb.

// 更好的.
//   - Unit is built in to the type.
//   - The field is easily adaptable between units, readability is high.
Amount<Long, Time> pollInterval;
Amount<Integer, Data> fileSize;
不要再变量里增加源信息(metadata)

变量名应该是说明这个变量干嘛的,不要再变量名里添加额外的信息,譬如变量范围或者变量类型。

:::java
// 不好的. 
// - 因为他包含了使用场景和类型
Map<Integer, User> idToUserMap;
String valueString;

// 好.
Map<Integer, User> usersById;
String value;

也不要在变量里包含变量的作用域。建议如果比较复杂,就把他分成多个函数的部分。 (注:怎么这么严格)

:::java
// Bad.
String _value;
String mValue;

// Good.
String value;

操作符之间要留有空格

如果复杂的操作符之间,记得用括号表示优先级

:::java
// 不好.
return a << 8 * n + 1 | 0xFF;

// 好.
return (a << (8 * n) + 1) | 0xFF;

操作顺序写的越明确越好

:::java
if ((values != null) && (10 > values.size())) {
  ...
}

文档

如果代码想要被用的次数多,好文档必不可少

  1. 明确写出完整的注释。不要只说半句话 

    :::java // Bad. /**
    • 这是一个关于cache的类。他能做缓存 */ class Cache { ... } 

      // Good. /**
    • A volatile storage for objects based on a key, which may be invalidated and discarded. (注:不好翻译) */ class Cache { ... }
如何为类写注释

类的注释的目的是消灭掉你API里可能不好表达的概念性问题,帮助别人快速而又*准确*的使用你的API。 好的类文档通常包含一句话概括,如果有必要的话,也可以详细展开。

:::java
/**
 * RPC里类似于tee的类,能保证每一个RPC的输入,在RPC call返回之前,输出到tee的两端
 *
 * @param <T> The type of the tee'd service.
 */
public class RpcTee<T> {
  ...
}
如何为方法写注释

方法注释应该告诉别人,这个方法是干什么的. 根据方法输入的类型,有时候需要详细描述函数的输入

:::java
  // 不好.
  //   - 说了和没有说一样
  /**
   * Splits a string.
   *
   * @param s A string.
   * @return A list of strings.
   */
  List<String> split(String s);

  // 好一些.
  //   - 能知道这个函数是干嘛的
  //   - 但是仍然有一些不确定的点.
  /**
   * 根据空格分隔字符串.
   *
   * @param s 被分隔的字符串.   {@code null} null串和空串相同的处理逻辑.
   * @return 用空格分隔的字符串形成的list.
   */
  List<String> split(String s);

  // 棒.
  //   -  包含了每一个边界条件.
  /**
   * 根据空格分隔字符串.  重复空格会被当做一个空格.
   *
   * @param s 被分隔的字符串.   {@code null} null串和空串相同的处理逻辑.
   * @return 用空格分隔的字符串形成的list.
   */
  List<String> split(String s);
专业点

不要在注释里写幼稚的话~

不要重复写override里已经写过的话

如果接口里已经描述了这个内容,那么,如果你Overrider这个方法,应该新增一些额外的说明

使用javadoc的特性
不要用author这个标签

commit记录比author标签更靠谱

Import

Import的顺序

先应用高级别的package,用空行分隔。 static的import放在最后

:::java
import java.*
import javax.*

import scala.*

import com.*

import net.*

import org.*

import com.twitter.*

import static *
不要用用星号引用

星号会造成大家看不到引用的来源

:::java
// Bad.
//   - Foo 是从哪里来的呢?
import com.twitter.baz.foo.*;
import com.twitter.*;

interface Bar extends Foo {
  ...
}

// Good.
import com.twitter.baz.foo.BazFoo;
import com.twitter.Foo;

interface Bar extends Foo {
  ...
}

聪明的使用注解

@Nullable

通常来说,默认每个变量都不能是null的。如果允许返回或者输入null,请用这个注解来显示标明

:::java
class Database {
  @Nullable private Connection connection;

  @Nullable
  Connection getConnection() {
    return connection;
  }

  void setConnection(@Nullable Connection connection) {
    this.connection = connection;
  }
}
@VisibleForTesting

使用接口(interface)

接口将实现和声明分离,是一个很好的编程习惯。提供接口出去,然后隐藏你的实现

如果接口数目过多,可以考虑下面的风格

:::java
interface FileFetcher {
  File getFile(String name);

  // 既使用了interface的优点,又不会造成类膨胀
  // 如果某个interface只有一个实现时,可以考虑这种方法
  static class HdfsFileFetcher implements FileFetcher {
    @Override File getFile(String name) {
      ...
    }
  }
}
考虑使用现有的interface

有时候,使用现有的接口可以让你的类更加容易被人使用。

:::java
// 没有过多的考虑。如果别人想用Blobs,还需要写胶水代码(glue code)
class Blobs {
  byte[] nextBlob() {
    ...
  }
}

// Much better.  
// 调用者可以用标准的collection函数来声明,也可以做类似于filtering这种复杂的操作
class Blobs implements Iterable<byte[]> {
  @Override
  Iterator<byte[]> iterator() {
    ...
  }
}

注意: 不要在已经正常工作的接口上扩展接口哦。

最佳实践

防御式编程

不要用assert

assert可以在执行时被关闭。推荐使用guava的preconditions

Preconditions

按照常规来说,公共(public)方法或者构造函数,都需要检查输入是否为null(除非显示标明这个输入可以是nullable)

:::java
// Bad.
//   - 如果callback为null,或者file为null,我们会很晚才发现这个异常
class AsyncFileReader {
  void readLater(File file, Closure<String> callback) {
    scheduledExecutor.schedule(new Runnable() {
      @Override public void run() {
        callback.execute(readSync(file));
      }
    }, 1L, TimeUnit.HOURS);
  }
}

// Good.
class AsyncFileReader {
  void readLater(File file, Closure<String> callback) {
    checkNotNull(file);
    checkArgument(file.exists() && file.canRead(), "File must exist and be readable.");
    checkNotNull(callback);

    scheduledExecutor.schedule(new Runnable() {
      @Override public void run() {
        callback.execute(readSync(file));
      }
    }, 1L, TimeUnit.HOURS);
  }
}
最小化代码的可见性

只把想让别人使用的接口或者变量暴露出去。如果你想写一个线程安全的代码,这一点尤其重要。

善用imutable

Mutable的变量经常会给你带来负担,你需要小心你传给别人的mutable对象是不是被人修改了。

:::java
// Bad.
//   - 所有人可以修改生日
//   - 调用getAttributes,就可以获得底层的map,就可以任意修改.
public class User {
  public Date birthday;
  private final Map<String, String> attributes = Maps.newHashMap();

  ...

  public Map<String, String> getAttributes() {
    return attributes;
  }
}

// Good.
public class User {
  private final Date birthday;
  private final Map<String, String> attributes = Maps.newHashMap();

  ...

  public Map<String, String> getAttributes() {
    return ImmutableMap.copyOf(attributes);
  }

  // 如果你觉得别人不需要知道所有的map里的信息,那么你就可以考虑单独返回一些对象.
  @Nullable
  public String getAttribute(String attributeName) {
    return attributes.get(attributeName);
  }
}
小心null

最好是使用Optional, 不太推荐使用null

 
try catch之后,记得finally
  1. Clean code
    1. 不要让人误导

如果是Long型,那么就写成100L,而不是100l。

移除dead 代码
使用更加general的类型

声明变量或者函数时, 更可能声明更general的类型。可以避免在你接口里暴露细节

:::java
// Bad.
//   - Implementations of Database must match the ArrayList return type.
//   - Changing return type to Set<User> or List<User> could break implementations and users.
interface Database {
  ArrayList<User> fetchUsers(String query);
}

// Good.
//   - Iterable defines the minimal functionality required of the return.
interface Database {
  Iterable<User> fetchUsers(String query);
}
避免类型转换

类型转换(typecasting)是poor代码的表现。

::: java
// Bad
Person person = (Person)boy;
多使用final的变量
  1. 异常处理
    1. 只捕获应该捕获的异常

不要一次捕获所有的异常。这是偷懒

:::java
// Bad.
//   - If a RuntimeException happens, the program continues rather than aborting.
try {
  storage.insertUser(user);
} catch (Exception e) {
  LOG.error("Failed to insert user.");
}

try {
  storage.insertUser(user);
} catch (StorageException e) {
  LOG.error("Failed to insert user.");
}
不要吞掉异常

绝不要catch里,什么都不处理。

When interrupted, reset thread interrupted state

有一些block的操作时,会抛出InterruptedException。 如果你接收到InterruptedException,最佳实践是保留线程的interrupted state

IBM有一篇关于这个很好的文章

:::java
// Bad.
//   - 周围或者高层级的代码不知道这个线程被中断了
try {
  lock.tryLock(1L, TimeUnit.SECONDS)
} catch (InterruptedException e) {
  LOG.info("Interrupted while doing x");
}

// Good.
//   -  保留线程的中断状态
try {
  lock.tryLock(1L, TimeUnit.SECONDS)
} catch (InterruptedException e) {
  LOG.info("Interrupted while doing x");
  Thread.currentThread().interrupt();
}
抛出合适的异常

让你的API用户捕获异常,而不要只是抛出最高级别的Exception。
即使你调用的代码里,抛出的异常是Exception,你也需要注意不要让这个Exception到过于上层。你要努力让你的调用者不需要太关心你的异常

:::java
// Bad.
//   - 抛出一个Exception,让别人很难受
interface DataStore {
  String fetchValue(String key) throws Exception;
}

// Better.
//   - 让上层知道了你的具体实现细节.
interface DataStore {
  String fetchValue(String key) throws SQLException, UnknownHostException;
}

// Good.
//   - 封装了你的实现.
//   - 不需要让别人针对你的异常做不同的处理
interface DataStore {
  String fetchValue(String key) throws StorageException;

  static class StorageException extends Exception {
    ...
  }
}

使用新的api和新的库

用StringBuilder 代替 StringBuffer

StringBuffer is 线程安全的,但是很多时候不需要线程安全

使用ScheduledExecutorService ,而不用 Timer

参考<Java Concurrency in Practice> 和stackoverflow上的这个
问题).

  • Timer 只有一个线程,如果有个任务执行时间太长,就会影响下面的线程执行
  • ScheduledThreadPoolExecutor 可以配置成多个线程和一个ThreadFactory.
  • TimerTask 的异常会杀掉这个线程, 这样Timer 就挂了。
  • ThreadPoolExecutor 还提供 afterExceute方法,可以让你方便的处理定时任务的结果.
用List ,不用 Vector

Vector 是同步的。你一般也用不到. 如果要用同步的集合,jdk7里也有很多 替代品)

equals() and hashCode()

如果你覆盖了某个类里equals() and hashCode()中一个方法,那么不要忘了覆盖另外一个
*equals/hashCode 相关文献参考
contract)*

Objects.equal())
and
Objects.hashCode())

不要过早优化

参考Donald Knuth 关于过早优化 的意见

通常情况下,最好的办法是先上一个性能不一定那么好的版本,除非你有强烈的预感,必须要做这个优化。

关于TODOs

尽早写todo

TODO不是一个坏习惯。留下TODO可以告诉别人这里有什么问题,你当时是怎么考虑的。

每个TODO都要留下相关人的名字

如果没有名字,估计这个TODO永远不会再DO了

:::java
// Bad.
//   - TODO 没有留下名字.
// TODO: Implement request backoff.

// Good.
// TODO(George Washington): Implement request backoff.
领养 TODOs

如果TODO的owner已经离开这个公司/项目啦, 或者如果你已经根据TODO做了一些修改,那么这个TODO就归你啦。

遵守迪米特法则(迪米特法则)

迪米特法则又叫最少知道原则,就是说一个对象应当对其他对象有尽可能少的了解。

在类里面

只关心你要的东西,不要牵扯太多。核心点是,推迟代码层面的实现,只要能满足你要求的最少的接口。

:::java
// Bad.
//   - Weigher要了hosts 和 port,但是这两个参数只用来传递给别的service.
class Weigher {
  private final double defaultInitialRate;

  Weigher(Iterable<String> hosts, int port, double defaultInitialRate) {
    this.defaultInitialRate = validateRate(defaultInitialRate);
    this.weightingService = createWeightingServiceClient(hosts, port);
  }
}

// Good.
class Weigher {
  private final double defaultInitialRate;

  Weigher(WeightingService weightingService, double defaultInitialRate) {
    this.defaultInitialRate = validateRate(defaultInitialRate);
    this.weightingService = checkNotNull(weightingService);
  }
}

(注:不知道这句话怎么翻译,大概意思是说,好的构造函数可以使用工厂方法或者builder,但是传递一个底层的service进去,更加有利于你做单元测试,如果代码发生变更,也可以做到对你透明)
If you want to provide a convenience constructor, a factory method or an external factory
in the form of a builder you still can, but by making the fundamental constructor of a
Weigher only take the things it actually uses it becomes easier to unit-test and adapt as
the system involves.

方法

如果一个方法有多个块,可以考虑把他们抽取出来,让每个块只做一件事情。这么做的好处是,可以让人看到你的代码时,更像是在读一篇文章。抽取出来的块也更加适合人类阅读。
下面这个是一个很典型的坏代码

:::java
void calculate(Subject subject) {
  double weight;
  if (useWeightingService(subject)) {
    try {
      weight = weightingService.weight(subject.id);
    } catch (RemoteException e) {
      throw new LayerSpecificException("Failed to look up weight for " + subject, e)
    }
  } else {
    weight = defaultInitialRate * (1 + onlineLearnedBoost);
  }

  // Use weight here for further calculations
}

推荐写法是:

:::java
void calculate(Subject subject) {
  double weight = calculateWeight(subject);

  // Use weight here for further calculations
}

private double calculateWeight(Subject subject) throws LayerSpecificException {
  if (useWeightingService(subject)) {
    return fetchSubjectWeight(subject.id)
  } else {
    return currentDefaultRate();
  }
}

private double fetchSubjectWeight(long subjectId) {
  try {
    return weightingService.weight(subjectId);
  } catch (RemoteException e) {
    throw new LayerSpecificException("Failed to look up weight for " + subject, e)
  }
}

private double currentDefaultRate() {
  defaultInitialRate * (1 + onlineLearnedBoost);
}

看你代码的人,可以很清楚的看到你是怎么计算重量的。如果他想要看具体实现,代码往下拖就行啦

不要重复自己 (DRY)

写代码的一个重要原则是,不要重复自己。可以参考这个
文章.

如果这个常量是有意义的,一定要提取出来
重复的代码,要提取出来

管理好你的线程

开启一个新线程时,需要特别关心这个线程的生命周期。自己要熟悉守护线程(daemon thread)和 非守护线程的区别(可以参考这篇文章 Thread。
如果不了解这些概念,可能会让你的代码在shutdown时被hang住。

当正在运行的线程都是守护线程时,Java 虚拟机退出。
必须在启动线程前调用,调用setDaemon方法,将线程置为守护线程

Shutting down ExecutorService 是一个有点tricky的过程。如果你用非守护线程管理executor service,那么你至少需要遵守这种方法。(注:ExecutorService关闭时,先调用shutdown(),不再接受所有新的任务,然后调用shutdownNow()来去掉还遗留的任务)

如果你想vm在shutdown 时,自动给你进行清理工作,可以考虑调用ShutdownRegistry进行注册.

  1. 删掉没用的代码
    1. 删掉完全没用的临时变量 

      :::java // Bad. List<String> strings = fetchStrings(); return strings; 

      // Good. return fetchStrings();
删掉没意义的赋值
:::java
// Bad.
//   - 这个null从来没有用过.
String value = null;
try {
  value = "The value is " + parse(foo);
} catch (BadException e) {
  throw new IllegalStateException(e);
}

// Good
String value;
try {
  value = "The value is " + parse(foo);
} catch (BadException e) {
  throw new IllegalStateException(e);
}

不要用fast 或者 optimized作为命名

你的API里的fast 或者 optimized 只能迷惑人,不能起到任何作用
Don't bewilder your API users with a 'fast' or 'optimized' implementation of a method.

:::java
int fastAdd(Iterable<Integer> ints);

// 有fastAdd啦,还用add干嘛。。
int add(Iterable<Integer> ints);

你可能感兴趣的:(java,编程规范)