【2012.9.26~2012.10.7】编程规范之注释原则

// // // // // // // //

///2012/9/26

// // // // // // // //
今天的内容是编码规范之注释。
其实主要内容很简单，只有一句话：

别忘了给你的代码加上注释。

恩。。

虽然很简单，不过很多人都会躺枪吧？(笑)

注释主要是给别人看的，
尤其是在团队合作时，

这一点显得尤为关键。

比如说下面的代码：

#if (CC_TARGET_PLATFORM == CC_PLATFORM_IOS)// OpenGLView initialized in testsAppDelegate.mm on ios platform, nothing need to do here.#endif // CC_PLATFORM_IOS

如果没有注释，
里面只是一片空白，

很多人都不知道这块地方是干什么的。

另外，
如果你不想再团队合作时，
别人总是跑过来问你：
"你的这个方法是干什么的"之类的话,
最好加上注释。

这也是提高效率的方法之一。

因此，

要记住：

嘿，别忘了写注释。


// // // // // // // //
///2012/9/27
// // // // // // // //

今天的内容依然是注释。

注释的格式有很多种，
因为文字有限，

在此并不赘述。

那么，
最合适的注释是什么呢？
这个就是我想给大家说的注释最重要的原则：

——没有注释。

没错，
你没有看错。

的确是，没有注释。

为什么？
大家可以看一下前天的这个例子：

float getGravityE();//获取地球重力加速度float getGravityM();//获取火星重力加速度

后面的文字注释其实完全没有必要：

float getGravityOntheEarth();float getGravityOnTheMars();

——你需要做的是把名字写的详细点。
这样，

就够了。

提高效率的前提是要与团队有好的沟通，
而如果能够将沟通直接显式地体现在变量/方法名上，
那还要注释干什么呢？

所以，

要记住：
让你的代码无法添加注释。

// // // // // // // //
///2012/9/29
// // // // // // // //

按照计划继续讲解注释。

今天主要是说一些错误的注释(在最终代码中，而不是编辑时代码)：
(1)自言自语
——我想有些人在敲代码的时候会不自觉的把自己的思考过程也敲下来了吧。。。

if(){//下面的这行代码或许错了，不过我还是试试吧}

(2)废话
——这个还不是最主要的，但是请往下看

class Calculator{//构造函数Calculator(){//TODO}}

(3)日志性注释
——呵呵，我有这个习惯。不过现在我已经重新建立一个Txt来记录了。

//2012-8-29 完成代码的架构//2012-9-30 完成XX方法//...

(4)位置标记
——这个在编辑时可以有，但最终代码可不是给你自己看的。

//我上次思考到这个位置

(5)注释掉的代码
——这类代码在编辑时可以作为测试使用，但是用完建议删除

add(paramOne,paramTwo);//remove(paramOne);//remove(paramTwo);

(6)终极废话
——这个简直可以用来侮辱别人的智商

//The nameString getName();//The addressString getAddress();//The nameString getTelephone();

而且，注意到上面的复制粘贴造成的错误了吗？
请记住，程序员是最聪明的一类人，

不要侮辱他们的智商，

不然，
他们会写个程序来骂你的。
呵呵。


// // // // // // // //
///2012/10/1
// // // // // // // //

今天我们继续前天的内容讲注释。

上一次我们讲了哪些错误的注释不应该有，

那么这次我们来看看正确的注释有哪些~

(1)法律声明
——这个目前我们是用不到的，
但是如果是公司的的话，
这个是必须的。开源也是如此。

/* SCE CONFIDENTIAL* PlayStation(R)Suite SDK 0.98.2* Copyright (C) 2012 Sony Computer Entertainment Inc.* All Rights Reserved.*/

(2)无法用变量名称描述的
——比如说右值

float[] positions = {// top-0.5f, 0.5f, -0.5f,// back0.5f, 0.5f, -0.5f}

(3)警告
——尤其在为程序员们编写程序时要注意这一点，
告诉他们千万不能这么干。

//Do not use unless u have some time to killvoid testNothing(){int i = 1;while(i){cout<<i++<<endl;}}

(4)对于自己意图的解释
——如果自己的程序当中用到了比较晦涩的算法，
这个时候有必要跟读者解释一下，
省的别人浪费时间。

//Here is A* algorithmvoid autoFindWay(){//some algorithm}

(5)TODO
——这个注释我们会经常在网上粘贴过来的代码中见到，
很明显，就是写代码的人希望诸位做的事情，
就该用TODO去注释。

public string getAccessToken(){//TODO//Input your access token...}

最后，

不要忘了我们的原则，

——要按照不写注释的最终目的去写注释。


// // // // // // // //
///2012/10/2
// // // // // // // //

今天我们就注释问题中的法律信息要稍微解释一下。

法律信息其实只要写明由哪个公司所创，
创于什么时候，

并且申明一下版权就可以了。

特别要注意的是，
千万不要著名作者。

即使代码只是你一个人完成的也是如此。

随着时间的流逝，

作者是谁这个问题变得愈发不重要。

所以，要记住，不要署名。


// // // // // // // //
///2012/10/3
// // // // // // // //

今天主要讲的是注释该如何写。

其实对于一般的注释来说，
//就够了
不过对于想要编写API(参考手册)的注释，
应该使用///并且加上相应的标注符,
比如说:

///<summary>///初始化程序///</summary>void initialAll(){//TODO}

这样写出来的注释可以直接通过XML解释器制成文档注释。
大家有时看到的API就是这么完成的。


// // // // // // // //
///2012/10/4
// // // // // // // //
今天我们来讲一下另一种注释写法。
大家从C语言开始，
一直熟悉的/*..*/写法
这种写法最大的优势(相比//)

就是可以多行注释了。

不过其实在程序中有多行需要测试的代码时，

却几乎不怎么用这个。

因为大多编译器都支持快捷注释(顺便一提，大部分快捷键都是Ctrl+Alt+C)
这种形式的注释真正应用的地方是在每个文件的头部，

也就是那一大堆法律声明或是代码解释之类不需要将注释再取消的地方使用，

(也就意味着程序员们就不用多点四下键盘了，要知道，程序猿可都是懒得不行的家伙们)。


// // // // // // // //
///2012/10/5
// // // // // // // //
今天我来跟大家说一下比较常用的编辑器的快捷命令(虽然网上有，
但是估计很多人都还不知道的)

首先,

Eclipse:ctrl+shift+C或者是ctrl+/

VS(测试发现C++不能用的哈):ctrl+K之后再ctrl+C(组合键)或者，更为有效的，

我经常点击上面的那个注释/反注释按钮。

恩，本来想跟大家更多的，但是发现到目前为止，

学校只让用这两个。

其实我还比较喜欢使用Monodeveloper(C# IDE),快捷键是Ctrl+Alt+C
其他的像Notepad啊，控制台啊之类的未知，估计没有吧。


// // // // // // // //
///2012/10/7
// // // // // // // //
今天是注释的最后一讲，
主要来说一下C++与Java各自的注释风格:
其实很简单，
C++更多使用 ///
而Java会偶尔使用/** */