花5分钟规范代码注释

　　序
　　【注释】从技术上来说没有对错，理论上，你想怎么写就怎么写，你爱怎么写就怎么写！
　　但它确实也会对我们造成影响，尤其是在多人协同开发的系统中。杂乱的注释也会让你或你的队友头疼
　　所以，我们需要规范一下注释。那什么才是好的注释呢？我们先来看看什么是不好的注释！注释冗余
　　我们往往会写一段注释来说明这是什么。比如：FindalltheusersletusersuserHelper。findAll（）；Addscoretoeachuserusers。forEach（（user）｛user。score；｝Returntheusersreturnusers；
　　但是这段代码本身的意思就很清楚了，再附上注释就有点多余了。
　　所以我们应该将其剔除。letusersuserHelper。findAll（）；users。forEach（（user）｛user。score；｝returnusers；
　　那么，这段代码是不是就方便阅读了呢？其实，咱们还能更进一步：letusersuserHelper。findAll（）；userHelper。incrementScoreForAll（users）；returnusers；
　　这样你感觉如何？相比于最开始的那段代码，这段是不是就看得舒舒服服？
　　所以，可读的代码比可读的注释更重要。优先考虑让你的代码说话，实在不行，再附上简短、清晰的注释。注释未更新FindallusersletusersuserHelper。findBanned（）；Giveeachuser100extrascoreusers。forEach（（user）｛user。score0；｝returnusers；
　　我们有时候会发现注释和代码并不匹配，比如这里为用户设置分数的操作。代码中是0分，注释却是100分。
　　导致出现这种情况有多种可能：我们总是在从其它地方复制代码，有时也会一并复制注释，然后在为己所用的过程中，修改了代码却没有修改对应的注释。我们同时也在不断的根据产品需求调整代码（比如此处设置分值），修改代码也可能会忘记修改之前写的注释。
　　怎么办？让我们来看看优解：userHelper。jsfunctionupdateScoreForUsers（score，users）｛users。forEach（（user）｛user。scorescore；｝｝Code1：punishbannedusersletusersuserHelper。findBanned（）；userHelper。updateScoreForUsers（users，100）；returnusers；Code2：giveeverybody1extrascoreletusersuserHelper。findAll（）；userHelper。updateScoreForUsers（users，1）；returnusers；
　　这样写将设置分数的逻辑封装成函数进行了抽离，功能更强了，也更易于阅读了。
　　现在，我们可以在多种情况下重复调用它，且不必担心注释未及时更新的问题了。注释太长
　　请问如果是这样的注释，你还有信心整个完整读下来吗？即使你是一个勇敢坚强的技术人，读下来也会消耗很多时间吧？这样低效率的事肯定不是我们想要的。userHelper。jsMassupdatestheuserscoreforthegivenalistofuserThescorewillbeupdatedbytheamountgivenintheparameterscoreForexample，iftheparameterscoreis5，theuserswillallreceive5extrascoreButifthescoreisnegative，itcanalsobeused。Inthatcase，thescorewillbedecreasedby5。Ifyousetscoreas0，thenthismethodwillbeuselessasnothingwillbeupdated。Ifyousetthescoreasanonnumbervalue，thefunctionwillnotdoanythingandreturnfalsejusttoensurethescoreisnotmessedupafterupdatingitwithanonnumbervalueTrytoavoidusingnonnumbervaluesinthescoreparameterasthisshouldnotbeusedlikethatIfyoudohoweverchoosetouseInfinityinthescoreargument，itwillwork，becauseInfinityisconsideredasanumberinJavaScriptIfyousetthescoretoInfinity，alltheusersscorewillbecomeInifinity，becausenInfinitywherenisanumber，willalwaysresultinInfinityRegardingtheusers，makesurethisisanarray！Ifitisnotanarray，wewillnotprocesstheusersscore，thenourmethodwillsimplyreturnfalseinsteadandstopprocessingAlsomakesuretheusersarrayisalistofactualuserobjects，wedonotcheckthis，butmakesuretheobjecthasalltherequiredfieldsasexpectedespeciallythescoreobjectisimportantinthiscase。returns｛boolean｝Returnstrueifsuccessful，falseifnotprocessed。functionupdateScoreForUsers（score，users）｛if（isNaN（score）typeofusers！array）｛returnfalse；｝users。forEach（（user）｛user。scorescore；｝returntrue；｝
　　所以，请确保你的注释不要太长。有那么多想说的，可以写文档、可以写文章，不要写注释
　　简单直接是最迷人的！注释太短
　　这是另一个极端的例子，但是它确实源自于现实的开发项目中。userHelper。jsUpdatescorereturns｛boolean｝resultfunctionupdateScoreForUsers（score，users）｛if（isNaN（score）typeofusers！array）｛returnfalse；｝users。forEach（（user）｛user。scorescore；｝returntrue；｝
　　此段代码注释只是说明了返回值，但是更为关键的传参并未作出释义。显得有些尴尬
　　如果你决定注释，那就不要只写一半。请尽量准确、完整、干净的将其写出。从长期来看，你一定会从中受益。好的注释
　　好的注释就是告诉大家你为什么要进行注释！
　　比如：userHelper。jsfunctionupdateScoreForUsers（score，users）｛users。forEach（（user）｛user。scorescore；VIPsarepromised500extrascoreontopif（user。typeVIP）｛user。score500；｝｝returntrue；｝
　　此例中我们可以明白VIP用户是被产品要求多加500分值的。这样其它开发就不会对此产生疑惑。
　　如果代码由多个团队维护，简单直接的小标注就更为必要了！小结
　　注释在代码中扮演很重要的角色。本瓜还记得大学老师说：注释应该占代码的三分之一。
　　我们都有不同的注释习惯，但是也应该有一个基本的指导：注释应当简短、清晰，长篇大论稍边边。告诉大家你为什么写这个注释，而不是告诉大家这段代码是什么！是什么应该交给代码本身去解释。这个最为关键！保持你的注释持久维护，也就是记得及时更新和与代码匹配。
　　代码可读就是最好的注释。我是掘金安东尼：一名人气前端技术博主（文章100w阅读量）
　　终身写作者（INFP写作人格）
　　坚持与热爱（简书打卡1000日）
　　我能陪你一起度过漫长技术岁月吗（以梦为马）
　　觉得不错，给个三连吧（这是我最大的动力）