标签：tom 部分 width 条件 设计者 ott src 规约 mic
程序的规约（Spec）在一个项目中占有十分重要的地位，一段没有撰写Spec的代码交由他人修改，亦或是一段时间后自己修改，都是一件令人头疼的事情。一个良好的Spec可以省去许多不必要的反复阅读代码的时间。
一个Java方法的Spec包含包括该方法前的文档注释、方法名称以及方法的参数，也就是一个优秀的Java方法应该暴露给用户的全部内容。用户可以通过方法的Spec了解到方法的调用方式、前置条件和后置条件以及可能抛出的异常信息。
如下图。
（1）提高代码的可读性
（2）方便后期代码维护
（3）生成Javadoc
前置条件就是对方法使用者的约束，一般包括输入参数的数量、类型、有效范围等。简单地说，一切对于方法使用方式的约束条件都属于前置条件。
前置条件相当于程序员对于方法作用范围的一个承诺："在承诺范围内出错算我的，承诺范围外出错你别找我"
后置条件就是对程序员的约束，一般规定了方法需要实现的功能。前置条件是后置条件的前提，只有用户的输入符合前置条件时，方法的输出才必须受到后置条件的约束；不符合前置条件的输入不受后置条件保护。
前置条件与后置条件构成了用户和程序设计者直接的协议，规定了每个人的责任范围。
当然，作为一个有着良好职业操守，秉承着为（不）用（想）户（丢）分（饭）忧（碗）的想法的程序员，虽然无需为用户的越界行为买单，但应该及时地做出提醒，减少用户端的损失。
方法前的文档注释中，不同的标签对应记录方法的不同信息，常用标签如下表所示：
|
标签 |
说明 |
使用范围 |
|
@author |
标识作者 |
包、类、接口 |
|
@param |
方法输入参数的范围，属于前置条件 |
方法 |
|
@return |
方法返回值的要求，属于后置条件 |
方法 |
|
@throws |
方法可能抛出的异常 |
方法 |
明白了Spec的重要性和设计方法，我们已经可以自己动手设计Spec了，但写出来的Spec常常大段大段地挤作一团，与Java标准库的文档注释一比，简直惨不忍睹。
Java的文档注释支持部分HTML标签。例如：
熟练使用加粗、换行、斜体、列表等可以为我们的文档注释增色不少
当然还有一些奇怪的东西……
这是个黑科技hh
点开后：
如果链接到相关文档啥的可能有点用……
这个真的只能拿来玩了hh
不常用的还有很多我就不一一列举啦，感兴趣的朋友可以看一下HTML的相关标签介绍
规约、注释对于一个程序、方法而言是十分重要的，但业界仍有部分人认为这些东西无关紧要，不需要写，好的程序应该能够自解释。我认为自解释的代码与写注释的习惯并不矛盾，代码自解释应该做到方法名、参数名能对方法的大致功能进行解释，而文档注释和规约则详细地写了参数范围、错误时的处理方式等，这些是无法通过代码自解释来完成的。但良好的命名习惯还是必须要养成的！
标签：tom 部分 width 条件 设计者 ott src 规约 mic
原文地址：https://www.cnblogs.com/hit1183710107/p/13276082.html
