5.3 一致性

一致性是好的.一致性减少了你的使用者需要扩展的工作.一致性降低了bug的出现.

一致性的一种形式是规则和函数入参的命名.是你的用户震惊并不是一个好的主意–即使他们是初学者.

一致性的一个相当不错的骚点是它总是给我们正确的结果.为了实现它我们应该给函数合适的入参.为了确保这个,函数应该检查入参,并且有可能也要检查中间结果.这些检查工具包括if,stop和stopifnot.

有时候会出现一个可疑但并不是错误的情况.在这种情况下一个warning是合适的.一个警告会输出但并不会中断程序执行.

然而对于warnings,没有人愿意去认真阅读它们.人们不得不去阅读error信息是因为一旦错误出现,程序将无法继续执行. 但是如果有一个警告出现,计算机也只是瞎比比几句,但是仍旧会继续执行.对于此处可能出现的致命错误从不介意.

对于一个警告我们的正确姿势应该是这样的:

1. 确定这个警告告诉我们了什么.
2. 确定为什么会出现这种错误.
3. 确定这个警告会对返回结果的影响(通过推理或者实验).
4. 通过第三步的结论,判断返回结果的正确性.

你希望你的警告信息尽可能少,这样可以提高警告信息的可靠性.如果你的函数比较复杂,那么函数中也可能会有大量的可疑情形,你就应该考虑提高消除警告的能力了.没有了这样的系统,用户或许期望大量的警告信息和预料之外并且很重要的缺失信息.

suppressWarnings()可以掩盖警告信息:

> log(c(3, -1))[1] 1.098612 NaNWarning message:In log(c(3, -1)) : NaNs produced> suppressWarnings(log(c(3, -1)))[1] 1.098612 Na

我们肯定希望我们的函数是正确的.然而并不是所有的函数都是正确的.函数的调用可以分为以下四种:

1. 正确.
2. 有错误并明确指出.
3. 一个模糊的错误.
4. 一个错误的返回值.

我们喜欢第一种情况.第二种情况,如果输入没有意义的化,这也是正确的返回,但是输入是正确的,那就不正常了.第三种情况对你的用户来说并不受欢迎,如果他们找你麻烦的话估计你也不爽.第四种情况是到目前为止最坏的情况–用户没有理由相信什么都是错误的.所以要避免第四种情况的出现.

你应当习惯于为你的每一个函数书写帮助文档.如果你对你的一个函数的输入输出含糊其辞的话,你就需要改变这个函数了.写出很棒的帮助文档对你调试函数有非常大的帮助.prompt()给你提供了一个帮助文档的模板.

一个示例值得一千个文字,因此在你的帮助文档中带上示例.好的示例千金不换,所以尽可能包含更多的示例.使用datasets包中的数据可以让你的用户很容易的运行你的函数.