微服务横行的今天，你的文档跟上节奏了么？

正文

请到「今天看啥」查看全文

优雅的代码风格和注释

推荐技能：Google Java Formatter，maven-javadoc-plugin
难度系数：★★★★★

代码风格

保持良好的代码风格永远是一件很有意义的事情，特别是对于一个协作团队，无法想象彼此混乱的代码风格会导致多大的阅读障碍。

现代化的集成开发环境极大地方便了我们保持整洁的代码。如果你懒得自己去配置，那么这里有个很好的选择Google Java Formatter（https://github.com/google/google-java-format）。装上它，这样你的代码永远都是浓浓的Google风了。

当然永远记得和你的团队保持一致的步调。

如果你的团队有重度强迫症，那么像CheckStyle（https://github.com/checkstyle/checkstyle）之类的工具会比较适合。

除了代码风格，如果你使用Restful，那么设计良好的Restful API也是一门必修课。这里推荐阮一峰老师的RESTful API 设计指南（http://www.ruanyifeng.com/blog/2014/05/restful_api.html）。

关于注释

写注释是痛苦的，但也是很有帮助的。你不一定需要完美地覆盖大部分代码，这样成本太高，也没有太大意义。

图：关于代码注释（来自神秘的程序员们）

1. 自文档
   
   让你的代码无需注释就能让人一眼看出作用。这需要你在编码时注意良好的命名和设计。
   
   比如你需要一个定时器时间参数的方法，如果参数名为 time ，那么调用者会疑惑应该传毫秒还是秒？这时候不妨设计成 timeInSeconds 或者干脆拆成 time + timeUnit 。
   
   比如你的实现类需要带额外的配置项，想想一下如果其结构是个Map，那会是多糟糕的决定，它会让使用者感到迷茫。这时候你可以动手定义一个专有的配置对象，或者初始化过程改造为Builder等等。
   
   总之时刻想着以后会维护你代码的那些兄弟，还有，未来的你。

2. 对外暴露的代码
   
   比如对外暴露的接口，工具类等等。因为经常会被别人调用。在这些地方写明详细的用法，让你的小伙伴们愉快地调用吧。

请到「今天看啥」查看全文