如何处理好Javadoc注释

Posted

tags:

篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了如何处理好Javadoc注释相关的知识,希望对你有一定的参考价值。

  在Java程序中Javadoc注释很重要,但是很多时候注释被漏掉,看看项目中的代码就会知道。如果你结对编程的话,你的伙伴一定会说,“哥们,这儿注释丢掉啦,那个函数的Javadoc注释写的不正确!”。项目中有很多的开发人员,水平和习惯都不太一样,但是对程序中javadoc注释来说,这是不能变化的,要规范起来。如何让每一个人都能养成这样的习惯呢?下面我们就IntelliJ IDEA使用向大家介绍一下。
  IDEA默认对Javadoc的支持非常不错,但是这里我们要引入一个插件,那就是JavaDoc Sync Plugin,这两者的结合将非常完美:JavaDoc Sync Plugin会提示你添加javadoc注释及注释同步,而IDEA本身会校验javadoc语法,这样我们的工作就会简单很多。
  首先打开Plugin Manager下载并安装JavaDoc Sync Plugin,重启IDEA后在设置面板中选择“Errors”选项,在“Errors”对话框中的文本过滤栏输入javadoc, 这时就会出现和javadoc相关的设置选项 这里我们想对这些设置项进行说明:

  Declaration has javadoc problem:这个设置项主要是校验javadoc的语法错误,如不必要的javadoc注释,必需的tag丢失等等。这个设置项有很多的参数设定,你可以参考一下;
  Inconsistent Javadoc主要检测javadoc注释冲突,如接口和实行类的javadoc不一致;
  Missing Class Javadoc delcaration等提示你应该添加注释。
  Severity最右边的小按钮可以设置错误级别显示效果。
  有了这些配置,相信你不在会忘记添加javadoc注释啦,因为IDEA会实时地给你指出来(高亮、背景等),这是IDEA的代码审查特性。IDEA同时提供了快速添加和纠错注释功能,只需一个键盘操作,就可以完成注释添加、同步和纠错。
  
  
  总结:通过以上设置,相信每一个人都会养成编写Javadoc的好习惯,格式统一。如在版本控制系统管理下,java类的注释需要@author和@version tag,这样每个人都会加上,对管理代码有很大的帮助。IDEA同时允许你给不同的错误级别设置不同的显示效果,这样你文档中各种问题进行标识,方便管理。
参考技术A 在Java程序中Javadoc注释很重要,但是很多时候注释被漏掉,看看项目中的代码就会知道。如果你结对编程的话,你的伙伴一定会说,“哥们,这儿注释丢掉啦,那个函数的Javadoc注释写的不正确!”。项目中有很多的开发人员,水平和习惯都不太一样,但是对程序中javadoc注释来说,这是不能变化的,要规范起来。如何让每一个人都能养成这样的习惯呢?下面我们就IntelliJ IDEA使用向大家介绍一下。
  IDEA默认对Javadoc的支持非常不错,但是这里我们要引入一个插件,那就是JavaDoc Sync Plugin,这两者的结合将非常完美:JavaDoc Sync Plugin会提示你添加javadoc注释及注释同步,而IDEA本身会校验javadoc语法,这样我们的工作就会简单很多。
  首先打开Plugin Manager下载并安装JavaDoc Sync Plugin,重启IDEA后在设置面板中选择“Errors”选项,在“Errors”对话框中的文本过滤栏输入javadoc, 这时就会出现和javadoc相关的设置选项 这里我们想对这些设置项进行说明:

  Declaration has javadoc problem:这个设置项主要是校验javadoc的语法错误,如不必要的javadoc注释,必需的tag丢失等等。这个设置项有很多的参数设定,你可以参考一下;
  Inconsistent Javadoc主要检测javadoc注释冲突,如接口和实行类的javadoc不一致;
  Missing Class Javadoc delcaration等提示你应该添加注释。
  Severity最右边的小按钮可以设置错误级别显示效果。
  有了这些配置,相信你不在会忘记添加javadoc注释啦,因为IDEA会实时地给你指出来(高亮、背景等),这是IDEA的代码审查特性。IDEA同时提供了快速添加和纠错注释功能,只需一个键盘操作,就可以完成注释添加、同步和纠错。
  
  
  总结:通过以上设置,相信每一个人都会养成编写Javadoc的好习惯,格式统一。如在版本控制系统管理下,java类的注释需要@author和@version tag,这样每个人都会加上,对管理代码有很大的帮助。IDEA同时允许你给不同的错误级别设置不同的显示效果,这样你文档中各种问题进行标识,方便管理。
  本回答被提问者和网友采纳

如何处理Express异常?

译者按:根据墨菲定律:“有可能出错的事情,就会出错”。那么,既然代码必然会出错,我们就应该处理好异常。

为了保证可读性,本文采用意译而非直译。另外,本文版权归原作者所有,翻译仅用于学习。

处理异常是编程非常重要的一点。我们的程序依赖于第三方服务、数据库以及我们的用户,一切都不可预料。数据库可能会宕机,第三方服务可能会崩溃,用户可能会使用错误的参数调用我们的接口。

为了处理各种复杂的情况,我们必须处理好代码异常,下面是代码示例:

app.get(\'/users/:id\', (req, res) => {
  const userId = req.params.id
  if (!userId) {
    return res.sendStatus(400).json({
      error: \'Missing id\'
    })
  }

  Users.get(userId, (err, user) => {
    if (err) {
      return res.sendStatus(500).json(err)
    }

    res.send(users)
  })
})

代码中处理了异常,但是存在问题:

  • 在多处代码处理异常
  • 没有使用Express的异常处理模块来统一处理异常

接下来,我们来一步步优化代码异常处理。

Express异常处理中间件

所有Express的路由处理函数都有第三个参数next,它可以用来调用下一个中间件,也可以将错误传递给错误处理中间件:

app.get(\'/users/:id\', (req, res, next) => {
  const userId = req.params.id
  if (!userId) {
    const error = new Error(\'missing id\')
    error.httpStatusCode = 400
    return next(error)
  }

  Users.get(userId, (err, user) => {
    if (err) {
      err.httpStatusCode = 500
      return next(err)
    }

    res.send(users)
  })
})

使用next(err),Express就知道出错了,并把这个错误传递给错误处理模块。为了处理这些错误,需要添加一个中间件,它有4个参数:

app.use((err, req, res, next) => {
  // log the error...
  res.sendStatus(err.httpStatusCode).json(err)
})

这样,我们就可以使用中间件统一处理错误了。但是,现在的代码有些重复:创建错误,指定HTTP状态码,使用next(err)...

Fundebug是全栈JavaScript错误监控平台,支持各种前端和后端框架,可以帮助您第一时间发现BUG!

boom

boom是一个兼容HTTP的错误对象,他提供了一些标准的HTTP错误,比如400(参数错误)等。

const boom = require(\'boom\')
app.get(\'/users/:id\', (req, res, next) => {
  const userId = req.params.id
  if (!userId) {
    return next(boom.badRequest(\'missing id\'))
  }

  Users.get(userId, (err, user) => {
    if (err) {
      return next(boom.badImplementation(err))
    }

    res.send(users)
  })
})

错误处理中间件需要稍作修改:

app.use((err, req, res, next) => {
  if (err.isServer) {
    // log the error...
    // probably you don\'t want to log unauthorized access
    // or do you?
  }
  return res.status(err.output.statusCode).json(err.output.payload);
})

Async/Await错误处理

使用Async/Await之后,可以这样处理Express异常:

  • 将中间件使用Promise封装起来,使用catch统一处理异常
  • 在中间件中,直接抛出异常就可以了
const boom = require(\'boom\');
// wrapper for our async route handlers
// probably you want to move it to a new file
const asyncMiddleware = fn => (req, res, next) => {
  Promise.resolve(fn(req, res, next)).catch((err) => {
    if (!err.isBoom) {
      return next(boom.badImplementation(err));
    }
    next(err);
  });
};
// the async route handler
app.get(\'/users/:id\', asyncMiddleware(async (req, res) => {
  const userId = req.params.id
  if (!userId) {
    throw boom.badRequest(\'missing id\')
  }

  const user = await Users.get(userId)
  res.json(user)
}))

参考

  • 验证HTTP请求参数可以使用joi模块
  • 打印日志可以使用winston或者pino模块

版权声明:
转载时请注明作者Fundebug以及本文地址:
https://blog.fundebug.com/2017/12/06/handle-express-error/

以上是关于如何处理好Javadoc注释的主要内容,如果未能解决你的问题,请参考以下文章

Javadoc写法和标签总结

Javadoc写法和标签总结

Java基础 | 如何用Javadoc Tool写规范正确的java注释

关于 javadoc

JavaDoc注释

javaDoc 注释规范