012-尚硅谷-Scala核心编程-文档注释.avi原创

好，那么注释呢，是我们一个程序员的一个良好的编程习惯，这一个小故事给大家分享一下哈，说以前我有带一个学生，两两个学生基础都差不多。呃，接触的差不多，甚至有一个同学呢，他的技术还好一点，结果到了一年以后。那个原先那个基础还比较还看起来还不太好的，结果很快就当这个项目经理了，那个哥们呢，还当程序员，后面我就问他是什么原因，那个那个那个说为什么会这样子呢。就那个成长的比较快的人，他是这样子的，他说我去了过后写代码呢。我首先有个习惯，就是他写代码，因为那个项目比较多嘛，文件很多，有些文件可能是有个项目可能是成成百上千个文件是小的，是经常常见的，他就说我有个习惯，我喜欢把我代码写完了过后呢，我多加几行注释，注释写的比较规范，而另外的那个哥们呢，是一点注释都不写。

那么一点不注释不写会有什么后果呢？就他一点都不写，就是这种代码。除了他自己能看懂，其他人看起来虽然能看懂，但是耗费时间很长，比如说别人看那个爱写注式的同学代码，他可能就是一天能把这个项目看个大概，那个就很难看懂。怎么办呢？那人家那个项目经理，你们将来到公司里面，项目经理每隔一段时间都会看你们的源代码，我记得以前我在新浪上班的时候。上班的时候，我们这个项目经理每隔一周都要检查你的源码。啊，检查你的源代码，你知道为什么要检查你源代码吗？就怕你代码写的有问题，因为当时我们做的是服务器，服务器开发，那服务器开发你如果说这个代码写错了，就会出现什么情况呢？服务器就宕机了，甚至有可能有安全漏洞，人家首先攻击的是你的服务器，说每个。一周都要看源码。看完源码过后，如果你没有写注释，就会批评你说你这个代码写一点注释没有，看起来很吃力，不是看不懂啊，周老师，我不写代码就就像人家看不懂我代码，我觉得很牛啊，对不对？你要看不懂你代码，你看不懂你代码一点都不牛，知道吗？周老师，我的代码只有我一个看懂不是挺好的吗？

特别不好啊，你们以后参加工作就知道了，一个团队，将来你们写的代码都很大的，现在小项目。一个人写项目，现在这个时代已经过去了，我记得在我们那个时代，零三年，零四年，甚至在200几年的时候，还曾经有过这样的这样的一个行为，叫软件英雄。啊，就是个人的软，就是软件叫软件英雄。呃，什么叫软件英雄呢，英英雄。哎，怎么没有声音啊，英雄。软件英雄他是干啥的？就是一个人就能把这个代码给你跑起来就干这事了，你看那个时代出现了一帮，中国出现了一帮特别优秀的程序员，比如像雷军。

对吧，邱伯君，包括王志东。呃，王泽东写代码也是很牛很牛逼的，中国第一款这个中文输入法叫中文竞开，中文之星，就这个我们开发他怎么发家的知道吗？Windows系统刚刚出来，他敏锐感觉到中国的要用Windows，最早是WINDOW95还是九八来着。九五还是九八，反正他出来过后，他马上自己研发了一个中文。输入之星就是那个，其实很简单，写完了过后，他就去跟人家合作，他找那个，他找那个惠普，说你们将来出出产这个出出的每一个那个，呃，计算机功能绑定一个中文之星，你卖的会比较好一点，因为。中国人用这个他肯定要说中文嘛，没有传世英文，那很少有人用啊，于是他那个两家一合作，他就起来了，给他投资，他做自自己公司，知道吗？所以像王志东还有什么呢，丁磊。

马化腾，这些当时就是一个人写东西，写完了过后。把这个东西慢慢慢慢发展起来的，但现在不行了。现在的时代，这个个人写代码已经不行了，如果说你没有一个良好的别人习惯，会出现什么问题呢？别人特别讨厌跟你合作啊，你看这个人111跟你合作就感到很害怕，为什么呢？看你的代码太吃力了，你看你这个写接口的，将来你们参加工作还要写很多接口。你写接口，你做事不写肯定会很吃力的，对吧，还有一个事儿大家可能不知道对吧，京东。这个京东的老大是不是刘强东啊？你们知道刘强东是什么人吗？啊？刘强东其实是程序开发高手。他曾经一个晚上写了一段代码，写一个晚上写代码给我挣了5万块钱。就那个时候写代码噼里啪啦写完了，给我把他代码一代码拿去去一卖，卖了5万块。

啊，他是他是很厉害的啊，只是现在出了点事而已啊，那我不管它了，好，那么这个注释呢，单行注释多行注释我就不讲了，单行注释多行注释我就不讲，我重点讲一个文档注释，看一下文档注释怎么写的。好，我们来写一个文档注释来走一个。好的，来走一个文档注释啊，Common。Common啊，我们就写这么一个文档注释，比如说我现在这里面有一个主函数。啊，有可能将来大家会用到这个东西，主函数过后呢，我就写一句话啊，我就简单写一句话。叫。Hello world。好，然后呢，我这再写一个函数，比如说我们叫求和的啊求和的，呃，比如说现在呢，我有个N，就是我写两个值吧，一个是N1。Int类型的N2INT类型的好，最后这个结果呢，也返回一个int类型的好，这就写完了啊哎。

类型的。然后我在这把这个值就return回去，就N1加N2 N1加N2把它返回啊，所以大家经常写的，那么现在我要做一段注释。啊，我们一般来讲呢，这种注释用的比较多的就是在这个函数这写一个里面每一句话不用写了，就是在老师在讲课的时候，会每一句话可能做个注释，你们将来注释只要做做在这个函数这个级别或者方法这个级别就足以，但是有些同学可能会好一点，在这个类也稍微写点东西，这个也很好，那现在比如说N1N22个参数都有了返回值，对吧，返回值比如什么是和。对吧，然后呢，我可以再做点东西，比如说我这里可以加一个，呃，比如说它是过期了啊，比如说写个过期，我可以写到这，比如过期了不能用了，现在比如说过期了。好，再比如说有些好一点负责任的程序员，他喜欢这么写，他会他说诶，我给你来一个example，发现这个特别好。

大家知道就我这怎么用法呢，它可以写一个，比如说诶输入N1等于十，N2等于20返回对吧，他说你就会re一个值，诶就就类似于这么一些小案例吧，类似30等等啊这样子。说老师这个东西有什么用呢，别人一看就很清晰嘛，然后呢，我们把它做成一个文档，大家看，我给大家演示一下怎么做文档啊，保存一下。保存一下好，那现在呢，做成这个文档注释，它是可以这么玩的，首先呢。我们。可以这样来做啊，呃，首先我们要找到这个文件的所在地。就是受大家看源码，它是在这个位置，好，现在呢，我进入到这里面去执行一个指令就可以了，我执行的是什么指令呢？就是SC。

它里面有个dock，这个sky dock是干什么呢？就是专门生成这个文档的。啊，它的指令很多，但是有些指令没啥用，我就不讲了，我就直接讲最管用的啊，杠D。更低价表一个路径，我要把它存在D盘下面的，比如说my dock这个文件夹，然后呢，我要对哪一个文件，哪一个class文件进行这个呃，Dock文文档的注释呢，就look。回车好回车。好，同学们可以看到。好，我们看这里面现在有没有生成呢，在D盘下面有一有没有生成一个my do呢，我进到D盘去。好，再看我这有个文件夹，它会自动给你生成一个文件夹进去，你看有了，我们双击我们打开它。哦，你看这里。是不是这边就就有相应的东西了呀，你看是不是就你的这个这些文档这些都有了，对吧？这这隐藏这些东西都都在这里面，就可以看你的这个注释，注释包括这个函数什么都有对吧，这样就可以来用了，我们把这个注释再重新写一下啊，写到这个主函数这来。

啊，写到这个主函数这来我就呃演示这么一个案例，我把这个主函数写到这上面吧。好，把它放到这上面来演示一下，这个我先这个我先不写了。一样的道理啊，一样道理，我写到上面去，看的更清晰一点，好，再来写到这。好，诶，这个地方注释我改一下斜杠。啊参数，然后呢，再写一个点过期，然后案例。Example。比如说是。写了testsing coding。好，再来生成一下保存。

好，我们再来看一下啊，再来看一下。好，给他更新一下就可以了。好，那么现在呢，我们再来看，这个时候应该就有更多信息在这了，看这。这个为什么没出来呢？看看哪地方写错了啊，再看一下是不是哪个指令没有给对。看一下。呃，Java dock，诶是不是我没写dock那个指令呢。我写的是不是do？Dog杠地地盘下面。啊，杠d hello can，杠D应该是带上了这个参数是吧。杠D。呃，我再来重新生成一下，看看是哪地方写错了吗？D盘直接写到这。是开了回车。

他应该有会出现这些东西才对呀。再打开一下，要更新一下才能看到效果是吧。诶，这个地方很奇怪呢。很奇怪，我这里没有看到这个效果，那待会我再排一下这个错误吧，啊，待会再排一下这个错误。好，这个注释文档方式肯定是这样子，待会我再看一下具体是什么情况，我们上午先讲到这吧，大家先去吃饭，吃完饭过后呢，下午再把这个说一下啊。