Saros项目开发最佳实践指南

代码结构与设计原则

访问器方法规范

在面向对象编程中，getter和setter方法是封装的重要组成部分。在Saros项目中，我们遵循以下规范：

1. 默认情况下应该使用getter和setter方法，除非有充分的理由不这样做
2. 内部本地实体类可以不使用getter/setter方法（但也可以选择使用）
3. 当类返回内部集合时，必须明确标识返回的值是否可以被修改：
   • 如果集合不能被修改，应该返回不可变视图
   • 如果允许修改集合，类必须确保行为定义明确（例如使用可观察集合）

类成员可见性控制

良好的封装是高质量代码的基础，Saros项目中我们遵循以下可见性规范：

1. 默认情况下所有字段和方法都应该是private
2. 任何高于private可见性的成员（可从外部访问）必须有详细的JavaDoc说明
3. 仅因测试目的提高可见性时：
   • 允许提高到包私有（无修饰符）
   • 不允许提高到protected或public级别

final关键字使用指南

final关键字的使用需要根据上下文灵活处理：

1. 类变量：默认设为final，除非有充分理由不这样做
   • 优点：使代码更易理解，明确知道哪些地方会发生变化
2. 局部变量和参数：原则上与类变量相同，但由于作用域有限，final带来的额外信息价值不大，因此通常不使用
3. 方法：默认不设为final，除非有充分理由
   • 原因：保持面向对象编程的灵活性

类与接口设计原则

1. 设计类与接口时需要深思熟虑，考虑代码环境，避免破坏架构设计
2. 访问外部资源的组件必须实现接口
3. 创建新接口前，确保没有类似实现存在，并考虑如何融入现有架构
4. 多方法监听器接口应提供抽象基类实现（空实现），因为：
   • 大多数情况下实现者不需要实现所有方法
   • 便于后续添加新方法
5. 避免在单个类中实现多个监听器接口（特别是顶级类），建议使用匿名内部类

控制流优化

优化控制流可以提高代码可读性：

1. 优先使用提前返回，而不是嵌套条件判断
2. 避免不必要的else分支，减少代码嵌套层级

参数检查规范

1. 方法可以假设调用者提供正确非空输入，除非方法明确允许空值或错误输入
2. 对于可能为null的参数，使用@param JavaDoc注明
3. 参数检查应抛出IllegalArgumentException
4. 重要组件边界处特别推荐进行检查
5. 复杂运行时检查建议使用assert

用户体验优化

作为Eclipse IDE插件，Saros需要遵循Eclipse用户界面指南。

系统设计启发式原则

改进Saros时，应考虑10项基本用户界面启发式原则，通过少量用户测试（3个左右）即可快速发现主要问题。

进度监控与取消机制

任何可能耗时超过100ms或涉及外部因素（如用户输入/输出）的方法都应提供：

1. 进度跟踪功能
2. 取消操作的能力

基本实现模式

使用SubMonitor类（实现IProgressMonitor接口）：

public Result computeSomething(List input, ..., SubMonitor progress){
  // 初始化任务
  progress.beginTask("Computing Something", input.size());
  
  // 处理过程
  for (Something some : input) {
    ... process input
    progress.worked(1);  // 报告进度
  }
  
  // 任务完成
  progress.done()
}

嵌套进度监控

对于多层操作，使用子进度监控器：

SubMonitor subMonitor = SubMonitor.convert(monitor, "Compute in two steps", 2);
progress.beginTask("Compute in two steps", 2);
computeFirstStep(subMonitor.newChild(1));
computeSecondStep(subMonitor.newChild(1));
progress.done();

用户信息反馈

进度监控提供三种信息反馈方式：

1. 已完成步骤数（worked()方法）
2. 任务名称（beginTask()/setTaskName()）
3. 子任务名称（subTask()）

不确定长度操作处理

对于步骤数不确定的操作：

while (!done()){
  ... do work
  progress.setWorkRemaining(1000);
  progress.worked(1);  // 前进0.1%
}

取消操作实现

频繁检查取消请求：

for (Something some : input){
  if (progress.isCanceled())
    throw new CancellationException();
  ... process input
  progress.worked(1)
}

错误处理机制

基本错误捕获

确保捕获所有可能的RuntimeException：

public static Runnable wrapSafe(final Logger log, final Runnable runnable) {
  return new Runnable() {
    public void run() {
      try {
        runnable.run();
      } catch (RuntimeException e) {
        log.error("Internal Error:", e);
      } catch (Error e) {
        log.error("Internal Fatal Error:", e);
        throw e;  // 重新抛出严重错误
      }
    }
  };
}

用户错误报告

在Eclipse环境中：

1. 使用ErrorDialog向用户报告错误
2. 使用ErrorLog向开发者报告错误

输入验证

1. 用户输入必须经过验证和清理
2. 错误信息必须人类可读
3. 异常处理原则：
   • 程序能处理的异常应该尝试处理
   • 无法处理的异常应抛给调用者

InterruptedException处理

处理阻塞方法时的中断异常：

1. 基本模式（重置中断标志）：

try {
  Thread.sleep(500);
} catch(InterruptedException e){
  Thread.currentThread().interrupt();
}

2. 忙等待特殊情况处理：

boolean interrupted = false;
try {
  while (looping){
    try {
      Thread.sleep(500);
    } catch(InterruptedException e){
      interrupted = true;
    }
  }
} finally {
  if (interrupted)
    Thread.currentThread().interrupt();
}

通过遵循这些最佳实践，可以确保Saros项目保持高质量的代码标准和优秀的用户体验。