注释怎么写 注释的作用是什么?
我认为注释最终作用无非就两个。
1.和伪代码一样的作用，为接下来要实现的功能写出一个指导性的算法思路。只是没有伪代码详细。但是也指出了完成此功能的大体算法思路。
2.给看代码的人一个解释性说明。注意看代码的人包括你自己。让看你代码的人可以快速的浏览你的代 码，而不至于每看一行都要一层
一层的方法看下去，才能了解你这个方法到底在干什么。
简单的说注释作用就是:写的时候提供算法思路。读的时候能快速了解你大约是怎么完成这个功能。
注释越多越好？
很多公司或者个人希望开发者注释写的足够详细。以为这样就可以提高可读性。我觉得这个想法是有问题的。
1.首先开发者写注释的时间可能超过了写代码。如果把大把的时间浪费在写注释上了，那么开发者还怎么能设计出足够好的代码呢。
2.看注释的人不得不一边看注释，一边看代码。我觉得没有哪个程序员会在看了足够详细的注释的时候就真的相信了注释而不看
具体的代码了。或者看完代码之后不看下注释确认下自己的理解对不对。那么就会造成老师期末考试的时候划重点的时候说每章
的都 是重点。
注释应该怎么写?
下面是我个人对注释写法的一些见解。
1.其实很简陋啊。就是你实现的时候的伪代码的超级精简版。你要完成一个功能你就是 1.先xxx 2.在xxx 3.在xxx。那就把这个 1,2,3 注释写
上去就好了。如果有其他很重要的步骤的话，也可以写下注释说明。但是主流程 1,2,3必须要清楚。
举个例子:
一个人早上上班的流程。
起床->刷牙->吃早饭->坐公交->刷卡->早会->coding。
/** * 去上班 起床->刷牙->吃早饭->坐公交->刷卡->早会->coding。 * * @param test */ public void goWork( String test ){ //起床 wakeUp(); //刷牙 toothbrushing(); //吃早饭 haveBreakfast(); //坐公交 takeBus(); //刷卡 swipingCard(); //早会 takeMorningMeeting(); //coding coding(); }
看上面的注释部分，相信你会非常快的了解这个人去工作需要哪些步骤。具体的起床穿什么衣服，刷牙用什么牙膏等更细节的问题，本身就不是这个
goWork() 方法应该考虑的了。你想了解你去看具体的代码块就好了。
如果在坐公交的时候出现 bug。那么开发者是不需要慢慢的找坐公交在哪开始的了。你可以直接的找到 takeBus() 开始仔细查找就好了。
2.该暴露的你必须要暴露出来让其他开发者来看到。别人可以一目了然的知道你这个功能时候怎么实现的。
函数不是越短越好，是越简单越好。是算法上的清楚或者说是逻辑上的简单
下面是我 review 代码经常会遇到的问题。
例如我们把 坐公交，刷卡 这两个方法写到 吃早饭方法里。
/** * 去上班 起床->刷牙->吃早饭->坐公交->刷卡->早会->coding。 * * @param test */ public void goWork( String test ){ //起床 wakeUp(); //刷牙 toothbrushing(); //吃早饭 haveBreakfast(); //早会 takeMorningMeeting(); //coding coding(); } //吃早饭 private void haveBreakfast() { //先吃早饭 //坐公交 takeBus(); //刷卡 swipingCard(); }
代码，变短了。从计算机的角度讲没毛病。吃完饭了坐公交然后刷卡。但是程序员只是了解计算机并不是真的是计算机。从 goWork() 函数上很直观看的话，我就以为是起床->刷牙->吃早饭->早会->coding。然后坐公交出现了 bug 那么恭喜你慢慢找吧。
上面那个例子同时违背了方法的责任单一原则。即一个方法只能抽象一件功能。
去上班可以是一个功能，起床可以是一个功能，但是吃早饭，坐公交，刷卡肯定不是一个功能。
实践中的经验。
1.一个步骤下面还有子步骤。
不是说注释下面就是对应一个方法。很多时候因为其他的原则，比如说没有复用性的是没有必要写成方法的。这种时候一个功能会是很多子功能的集合。那么我建议子功能的注释最好和上级功能的注释区分开。以表明这只是一个子流程。
例子:
主流程使用 ===开头
子流程使用 ——————-开头。
样式明确表示了功能级别。长度起到了看起来方便(因为，像伪代码的缩进)。
public final String apLogin(final HttpServletRequest request, HttpServletResponse response) { //===本次请求的原数据写日志================== String parameters = JSON.toJSONString(request.getParameterMap()); //-------------获取 token 做为本次请求的日志 id- String logId = StringUtil.getToken(); //-------------本次请求的数据写日志------------ logger.debug("{}订制终端获取页面参数为:{}", logId, parameters); //===解析参数============================== String deviceId = request.getParameter("dev_id"); String userMac = StringUtil.formatMac(request.getParameter("client_mac")); String gwAddress = request.getParameter("gw_address"); String gwPort = request.getParameter("gw_port"); String url = request.getParameter("url"); String publicUserIp = request.getHeader(Constants.X_FORWARDED_FOR); String publicUserPort = request.getHeader(Constants.X_FORWARDED_PORT); //===校验参数============================== ApPortalServiceDTO apPortalServiceDTO = new ApPortalServiceDTO(deviceId, userMac, gwAddress, gwPort, url, publicUserIp, publicUserPort); String validateResult = validateLoginParameters(apPortalServiceDTO); if ( null != validateResult) { logger.error("{}订制终端获取页面服务参数校验不通过:{},参数为:{}", logId, validateResult, JSON.toJSONString(apPortalServiceDTO)); return JSON.toJSONString(ResultDTO.getParameterErrorResultDTO(validateResult)); } //===去数据中心查询 portal 页信息=============== //-----------写日志需要的信息--------------- GlobalDTO globalDTO = new GlobalDTO( logId, FunctionNameConstants.AP_PORTAL, GlobalDTO.assembleLogValue(deviceId, userMac)); //-----------查询页面信息------------------ ResultDTO resultDTO = apPortalService.getApPortal(globalDTO, apPortalServiceDTO); if (ResultDTO.isResultError(resultDTO.getResultCode())) { return JSON.toJSONString(resultDTO); } try { //===重定向拉去拉取相应的页面==================== response.sendRedirect((String) resultDTO.getData()); logger.info("{}apLogin重定向到{}完成", logId, resultDTO.getData()); //===返回客户端结果 return JSON.toJSONString(new ResultDTO()); } catch (Exception e) { logger.error("{}重定向到:{}发生异常:", JSON.toJSONString(globalDTO), resultDTO.getMessage(), StringUtil.getExceptionStackTrace(e)); return JSON.toJSONString(ResultDTO.SEND_REDIRECT_EXCEPTION); } }