2015061508 - 注释分析(1)

    下面截图是绝大部分接口中类似的一部分

   

    稍好一点的接口如下:

   

    说明接口用途,只要参数名称和实际意义相同.但是依旧有问题

    比如查询获取剩余每日额度,如果额度为0,那么返回值是null还是new BananaQuota()呢.对于方法调用者来说,需要知道方法做什么,方法需要什么,需要注意什么,返回值代表什么.如果方法定义时候无法提供,那么调用者就需要了解方法的实现细节,而对于调用者而言根本就是浪费时间.

   如果方法调用者需要知道的内容无法知晓,那么就需要了解具体的实现细节.对于接手开发或者后期维护人员,除了知道用途,根据参数名称查看参数意义,成功的返回值.特殊实现思路需要自己花费时间阅读,这些都是最初开发者最熟悉的,只完成功能实现,却没有为后来人准备.

   接口作用,参数,以及参数特殊说明,方法的特殊实现思路,特殊情况的返回值介绍,对阅读接口而言足够.