以TI的一个SimpliciTI(点对点简单无线数传协议)例程为例，说一下重构

辛昕

以TI的一个SimpliciTI(点对点简单无线数传协议)例程为例，说一下重构 [复制链接]

重构，用最简单的说法就是： 在不改变代码现有功能的前提下，优化和改善代码。

对代码而言，它的优化和改善是多方面的，为了避免这个话题过于庞杂，并且超出我们的能力范围。
我们只着重考虑我们所关心的 部分代码质量问题。

这里说的 “代码质量”，是楼主临时想到的一个提法，如字面意思。

现阶段，楼主所考虑的 代码质量 比较简单，只包含：
1.代码以功能为单位，尽可能地模块化，子函数化，更低耦合性，更独立——你可以理解成，一旦达成这样的目的，你可以很轻易地把在某个在PC上使用的代码直接放到51程序里而甚至无需修改数据类型；

2.代码更易于理解，具体而言，楼主关心的是：
   1.注释量少到非注释不可——作为一个关心代码规范，能为其他代码阅读者着想的我们，估计都有过非常认真写大量注释的时期，这种行为属于本意良好，却未必有效果的善意行为。
      相信我，不必要的注释不仅是对注释者的繁琐工作，更是对阅读者的极大困扰。（尤其是那种喜欢 用 /**/ 单行注释的亲，要知道大量这种的注释符号插在代码中，会造成企图通过注释关掉部分代码的操作变得非常麻烦，因为注释符号是不嵌套的。）
      而减少非必要注释量的具体做法可以简单地概括为：   通过更达意的命名取代一句注释，比方说下面这个极端的例子：

1. /* This function use to get a random number */
   
2. char fun1(void)；
   
3. 
   
4. //其实，它可以写成
   
5. char getRandom(void);
   

复制代码

2.良好命名，包括变量，宏，函数，结构体 等等等等，所有可以命名的东西。
     这个话题可以从上一点引申开来。
     我们要集体鄙视 类似于 char  a,b,c; typedef {...}Str1，Str2....... 这一类的命名。
     因为它什么信息都不能告诉我们，如果满世界的人都叫 张三1，张三2，李四1，李四2，你是什么感觉？——是的，上面那两种典型命名给我们的感觉就和这个类似。
     3.前一个问题说到宏的命名，这里再引申说宏，避免使用直接的数值，而把数值定义成宏，它的好处 除了我们众所周知的 “修改一处就可以不漏下任何都用到的地方” 这种浅显的目的以外，更重要的是，它让这个常数带上了自己的意义。
     
     以上谈到的几点属于比较表面的（但是很重要）问题，下面谈的是更深层次的，在软件架构框架上的问题.

3. 减少不必要的宏嵌套层次
         前面我们提到通过宏来避免使用直接数，实际上，宏还有另一种重要的功能：如果是一个带参宏，它在功能上会相当于一个函数（确切地说是相当于一个C++的内联函数）。它的存在，自然是可以提供一些函数实现以外的作用，但这种功能，个人觉得大多数时候其实是被人为夸大，其实没有非要不可的紧张气氛。
然而，我却常看到这种手法的滥用。比如在一些厂商提供的例程里。

        下面我们简单看一个例子：

1. #define IS_BUTTON1() BUTTON1_PORT & BV(3)
   
2. 往下追查这两个宏
   
3. #define BUTTON1_PORT P1
   
4. #define BV(n) (1<
5. 
   
6. 关于这个带参宏，不知道你是怎么看？
   
7. 比如对于 移位操作 它煞费心思弄成一个宏，这个意义到底有多大？
   
8. #define IS_BUTTON1() BUTTON1_PORT &（１<<3）
   
9. 这种写法和上面那种写法在表达这个开关的IO是连在P1口的第3号脚上 这个意思 难道有任何差别吗？
   
10. 答案是没有。不仅表达意义没任何不同，就连编译时的速度也稍优于前者；
    

复制代码

这只是楼主凭记忆随便写的一个只有两层的 宏嵌套，实际上，在（比如说前面提到的 TI的CC2530例程）中，诸如这种的嵌套多了去，而且嵌套层次，复杂程度远远超出举例，为了看懂一句宏，我常常要ctrl+F好几次，一层层庖丁解牛 才能看懂。
         
         这个话题引申开去，还包括，减少任何不必要的嵌套。特别是 循环结构 和 条件判断结构 以及更复杂恐怖的 循环+判断（而实际上，这种结构更常见).
     
4.项目文件的组织要层次清晰
         这个原则，是目前为止提到的第一个不以“代码”为着眼点的问题。还记得前面我提到过的“一旦达成这样的目的，你可以很轻易地把在某个在PC上使用的代码直接放到51程序里而甚至无需修改数据类型” 吗？
         这是我在说到 模块化 的时候提到的，没错，层次清晰是实现模块化的必然结果，也是模块化的根本动力。
         
         模块化 这个词经常被提到，甚至在非软件，非IT行业，然而，回到程序代码上，很多声称模块化的代码却一点也不模块化，或者模块化程度很低。举个例子，如果一个最简单的FIFO函数（不是硬件上的FIFO寄存器，而是指一个数组或者什么结构体，数据的存取顺序是 先进去的数据最先被取出。）
         如果一个软FIFO函数，从PC端程序搬到51单片机上使用，要作不小的一番修改，那这叫什么模块化？
        而导致这些的原因可能只是简单到 直接使用int这个数据类型，而不是使用 U32或者uint32_t这一类的重定义类型；（因为这个问题很难再复杂，除非他根本没有单独抽离出这一部分FIFO功能的代码！）

         对于整个项目文件的组织也是一样的。除了我们刚用VC6初学C语言那会，我们大概都不会写那种只有一个c源文件的项目了。
         我们都是按照各种分类的原则和目的（而它们都被统称为“模块化”，虽然有些模块化还不如不模块化）把所有的代码分成好几个甚至十几个，几十个源文件，并为之配备相应的 头文件。

          这样的源文件应该和前面提到的那个 软FIFO函数 一样，理想的情况下，是要做到它们随意搬到一个同种语言的项目里可以几乎不做任何修改就直接使用。
这样一来，下一次，当我们写另外的项目时，如果需要使用到相同的功能，我们至少也可以通过直接复制这个源文件去直接实现，更高端的方法是编译成一个库链接使用；
          另一方面，或者是更重要的目的：因为这些模块，这些源文件是经过长时间的验证，或者严格的测试，使我们对它们足够信任，那么，下次当发现什么bug时，我们就不会轻易怀疑这类通用功能的实现源码，可以大幅度的减轻我们的调试强度。
         

       说得够多了，暂时就这么多——但要做到还是很不容易的，不过不要紧，我们总是在实践中一点一点增进自己对程序代码的掌控能力，一点一点追求更完美的代码。

zqjqq88

好文章，顶一下！:carnation:

辛昕

前面说的内容很容易激动人心，这的确是一项迷人的技术。
不过，最好还是丑话说在前头。
任何事情都有代价，危险，重构也是。

从前面的简单解释就可以知道，重构的一个特征 “不改变任何代码的功能”。
这就是说，对于你的上司，老板，以及客户，这件事情没有任何实际意义。

所以说，你的所有努力，在别人看来都是 浪费时间。
尽管你很清楚，这对于整个开发过程很重要，对于最终完成的代码质量有很大提高。更长远的说，它还会对后期维护带来极大的好处......
只不过，所有这些，都抵不过你现在被指责在干无意义的事情，你要面对的仍然是紧张的进度。
这就是重构的代价。

更加不幸的一个消息是，重构也有危险，重构尽管可以优化代码，但同时也能在事实上恶化代码。
如果你花了很多时间来重构，并且破坏了代码，那你同时付出了不菲的时间代价和承担了不幸的风险。

但我希望你仍然要耐着性子往下看，因为，通过系统的方法和步骤，我们是有办法把 这些代价 和 风险 降到最低，从而达到 收益最大化 的。

辛昕

我非常担心我再啰嗦下去，你们都会失去兴趣。
就好像，在SimpliciTI的例程搞到手以后，我纠结了很久如何把这个例程抽取出来，在别的文件夹下编译和试验以前一样。
最后我花了不少时间，甚至不慎破坏了安装文件，不得不两三次重新安装，重头再来，浪费了不少时间。而此时，我的上司已经开始咨询我进度，并传达了一定的进度压力。
而解决这个事情的关键在于，我下定决心，先在我的开发板上验证这个例程确实起到点对点收发的作用，再考虑其他事情。

而对于重构而言（这里免去解释如何验证这个例程的过程）
我们先考虑要实现的第一个目标是什么？

先观察这个例程，看看它有什么让人不满意的？

打开安装文件夹下的example，我们首先可以观察到它的组成部分。
三个主文件夹 Component  Doc Project
Component包含的是实现SimpliciTI协议的底层库的所有源文件。
Doc是一些说明文档，其中有两个文档对我们来说是最重要的。
Project包含了各类不同芯片不同开发板的例程项目文件。
打开我们的SRF05（因为我使用的是cc2530芯片，在所有的开发版本里，它最接近CC2530EM）。
打开发现了它还分四个文件夹，分别对应四种不同的网络结构。
而我选择了PEER-TO-PEER，因为我只需要一对一传输；

就我而言，这就是第一个不满意的地方。
从TI官方的角度出发，它这么做是必须的。
因为它的这套协议是在它的好几个系列 无线射频 芯片上 都通用的。

而它本身也针对各个芯片系列做了各自的开发板，它们自然有许多来自芯片底层寄存器，操作方式，甚至开发板上配置的不同。
所以，TI官方这么做，是为了让这个例程更加通用。

但是，从我的角度来说就不一样。
首先，我完全不了解这个协议，我也不了解这些芯片之间，这些开发板之间的不同。

我只希望在我自己的2530上面，实现，而且，只是 一对一，也就是peer-to-peer.

那么，这个复杂的项目文件，这些分离的底层库，和上层应用，就会分散我的注意。
而且，对于我的角度来说，那些其他开发板其他芯片的内容，对我来说，都是“多余”的代码。

所以，为了更加集中精神在我要做的 2530 的 peer-to-peer 这唯一的一个点上，我首先要做的事情，就是重新安排项目文件的组织。
——这样做的另一个目的是，我可以随时保存当前工作的最后状态，假设那天我不小心破坏了所有工作，我也可以恢复到最后一个可工作版本，减轻毁灭带来的损失。

——在此之前我就深刻体会一个代价。
因为我的重构有时有一些危险性比较大的动作，造成了好几次破坏了安装文件夹下的源代码，使得我不得不重新来过。

好，现在，第一项工作，单独分离出 针对cc2530的 peer-to-peer.

辛昕

在动手重构以前，一定要记住，重构的原则是，不要改变代码的功能。
那么，首先我们就要先知道代码的功能。

这个例程是 烧录两快cc2530板子，一块作为 监听方，一块作为 发送方。如果成功点对点传输数据，两块板子就会交替闪烁LED。

好，按照 动手1 的要求，我们先来调整 项目文件夹。
我们要把所有必须用到的 源文件，头文件 全部集中在这个文件夹里，但是又不要单纯二三十个文件杂乱无章都和项目文件堆放在一起。

我个人的划分层次是按照 硬件抽象层 功能模块层 公用函数层 应用层（也就是主调层，一般就是main（）函数所在的 主源文件 以及各类 和它同等地位的 比如 中断服务程序。）

这里，由于存在一个独立的simpliciTi库，我们单独给他安排一个文件夹，名字不妨就叫做 Component（确实不要紧，过后我们可以改名字）

这种重构，会带来一个比较麻烦的技术问题。
我们可以在项目里直接添加散乱在几个文件夹里的c文件，但是编译时却要指定搜索 头文件 的路径。

在有的时候这会是一个很麻烦的问题，不过我们不必要太过于纠结，我们只要能保证在自己使用的编译器或者ide下解决这个问题就可以了——
很多时候，解决问题的方法并不重要，重要的是这个问题的意义和提出这个问题。

因为cc2530开发主要用的是IAR，IAR的option选项中有一个 C compilier下的预处理选项，通过在这里添加相对路径，这个问题会非常容易解决。

具体的细节,请自行搜索引擎。

在其他的IDE下或者编译器，比如说在vc6啊，keil啊，或者你在使用的某个很小众的第三方ide......
我就试过，我直到现在都没想明白怎么做，于是我不得不真的把所有源文件头文件都放在一个文件夹下。

但是，这并不重要，重要的是，至少在这个cc2530，在IAR下，我们可以很轻易解决问题。
考虑得太多，不知取舍，有时会造成更大的麻烦。
完美是拖延的一大温床。

好了，调整好后，重新添加新位置的c文件，修改预编译器路径，然后重新烧写进片子，看看是否还有两个LED在交替闪烁吧。

辛昕

现在，我们要回到代码上来动手了。
重构代码，一定要从 发生调用 的地方开始着手。
这是因为 主调处是最接近用户语境的地方，这里我们根本不关心具体的实现细节，只要知道到底要干什么，到底做了什么。

——程序设计的失误，能引发最严重问题的地方就是这里。
这个道理很简单：我不管你是坐飞机还是坐火车还是走路或者实在很糟糕，要先下山转马车到镇里.......但如果我其实想让你去东边，结果你去了西边，那就南辕北辙了。
假如你只是错误选择了交通方案，再严重也不过是花更多的时间或者钱 而已。

所以，不管是重构某一个部分还是整个程序，都必须从主调的地方开始，对于整个程序，自然是main函数。

这里，楼主使用的是IAR环境。
我们知道这个项目，实际上是两个项目，一个是发送方，LinkTo，一个是监听方，LinkListen。
有两个不一样的main函数，通过工作环境切换来完成。

这首先就是一个很别扭的地方。
因为我们更喜欢用 条件编译 来选择编译不同部分代码；

这笔账先记下。
——重构的一个原则就是，发现让你不爽的地方，就像Kent Beck说的，嗅到坏味道，就要把它干掉。

再看。
这两个main源文件 很长很复杂，而且很令人讨厌。
因为它把所有用到的函数实现都放在这里。

我们看函数总是要首先去找main函数，然而，因为这个主源文件里，散乱放着其它函数，加上无处不在无用啰嗦的注释，我们每次都要费不少时间才能找到main函数，这是一件更加不能容忍的事情。

够了，现在我们要动手了。

辛昕

现在，我们要回到代码上来动手了。
重构代码，一定要从 发生调用 的地方开始着手。
这是因为 主调处是最接近用户语境的地方，这里我们根本不关心具体的实现细节，只要知道到底要干什么，到底做了什么。

——程序设计的失误，能引发最严重问题的地方就是这里。
这个道理很简单：我不管你是坐飞机还是坐火车还是走路或者实在很糟糕，要先下山转马车到镇里.......但如果我其实想让你去东边，结果你去了西边，那就南辕北辙了。
假如你只是错误选择了交通方案，再严重也不过是花更多的时间或者钱 而已。

所以，不管是重构某一个部分还是整个程序，都必须从主调的地方开始，对于整个程序，自然是main函数。

这里，楼主使用的是IAR环境。
我们知道这个项目，实际上是两个项目，一个是发送方，LinkTo，一个是监听方，LinkListen。
有两个不一样的main函数，通过工作环境切换来完成。

这首先就是一个很别扭的地方。
因为我们更喜欢用 条件编译 来选择编译不同部分代码；

这笔账先记下。
——重构的一个原则就是，发现让你不爽的地方，就像Kent Beck说的，嗅到坏味道，就要把它干掉。

再看。
这两个main源文件 很长很复杂，而且很令人讨厌。
因为它把所有用到的函数实现都放在这里。

我们看函数总是要首先去找main函数，然而，因为这个主源文件里，散乱放着其它函数，加上无处不在无用啰嗦的注释，我们每次都要费不少时间才能找到main函数，这是一件更加不能容忍的事情。

够了，现在我们要动手了。

辛昕

照前面分析，我们要实现的最终目标应该是：
main.c模块里不要出现具体的函数实现；
我们不要两个main.c源文件，只要一个，具体手法是通过 条件编译 实现；

我们先实现第一步，也就是把所有函数实现移出去，做一个中间层。
这一步其实没什么太特别的动作；
我个人会考虑把它们放到一个新的文件夹下，这也不要紧，方法和前面一样，除了新建一对 源文件和头文件，把代码移过去，在main文件里添加头文件以外，就是再增加一条头文件搜索路径即可。
实际上，还有部分小问题，就这个具体的代码而言。
首先它两个main里都有toggleLED()的实现，自然我们只需留下一个——当然，我个人的选择是丢弃这个函数，自己写两个分别针对 绿灯 和 红灯 的函数，这取决于个人习惯，你也可以把它放到任何一个合适的模块里。

再烧一次程序，验证一下两个灯是否还像原来那样闪烁。

这一步完成以后，我们将得到两个很干净的 main文件。
接着动手，把两个main变成一个，这一步比上一步稍微要危险一点，因为这实际上是两个项目。
所以，我们的方法是，一个一个改。然后找出 两个项目之间有哪些部分是不一样的。再根据异同的对比情况决定如何加入条件编译选择开关。

最终整理出来，我们发现，由于这个SimpliciTi的操作很简单，总共只有四五步调用。
所以，实际上，两个项目所差别的地方主要是 连接时，一个是link 一个是linkListen，另外的差别主要就是 接收回调函数 和 循环进行的主线程的差别了——这属于用户功能不同而定。

我们先不动函数，我们只是用 条件编译开关 来 选择不同的 回调函数 和 循环进行的主线程函数.....

我们一个一个烧，最后确保两个都可以。
这一步应该不会碰到什么麻烦。

到了这一步，我们至少应该再保存一个备份版本。
因为这可以认为是一个 符合我们自己风格的 项目代码。
而且是百分之百来自原例程。我们以后会在这个基础上不断修改，或者融入我们自己的项目。
但假设我们遇到什么麻烦，我们仍然回到这一步——一个用我们自己可接受的方式组织的例程。

辛昕

照例，下一步是接着考虑我们还要干什么。
我们已经知道这个例程是一个很粗糙的例程。
它可以完成两个cc2530之间的点对点，并通过 LED闪烁来显示工作状态。
然而，这并不符合我们的需求。

我们用它来进行无线数传，首先至少要测试传输质量——在这里，简单地说就是，首先传输的错误率会有多少？
过后还要考虑传输的速度，以及距离等等。

但所有这些都建立在 可以接受的出错率 基础上。
因此，我们需要设计一个东西来验证传输数据的正确与否。
并通过某种方式显示测试结果。
这里，我们不要太关心会采取什么检验数据正确的方法。

我们要传达的信息只是，我们现在要动的是那两个 回调函数（接收到数据后的动作）和主循环线程的动作（确切地说可以认为是主动发送以及程序的其他工作。）

为了确保我们仍然能够正确的接收数据。
我们首先要找一个方式来显示结果。

在这里，楼主选择了串口，一方面它最简单，另一方面，它也是楼主实际项目所需要的功能。

所以，在做任何改动以前，我们还是先加入串口——否则，比方说你先把LED显示干趴了，你从何而知，收发还在正常进行。

串口相对来说比较简单，在这里本无需多说。
不过，作为一个理想模块化的简单例子，有值得简单说说的地方。

不管你和我一样，是先调通了串口的例程，还是说现在想到了才去调（对我而言，其实我更希望我是后者，因为，我是用到了才去做，并且，在我面对的问题里，点对点 比串口更重要，凡事总该是要事优先。）

假设我们已经调好了串口。
我们要检查一下它是否满足我们的要求：
它无需做任何改动，只要直接把相应的源代码复制出去，就可以在那个地方直接使用。

这句话我直到我罗唆了很多次，我们换个角度来说，如果要这样，这个模块应该长什么样？
它的所有函数都应该存在一个独立的源文件里，不和其他任何无关串口的混淆在一起。
它所用到的重定义数据类型，基本的单片机机型对应的头文件，因为有需要，也要一并复制过来——当然，在更理想的情况下，我们应该追求一个这样的目标：对于任何一个特定的机型特定的开发环境下，我们应该写一个基本的项目文件模板。

如此，我们每一次都用同一套模板来写程序，则直接复制一个要使用到的源文件，就可以无缝复用。

辛昕

好，这一步完成以后。
我们就可以改变点对点例程，让它更符合我们的实际应用情形。

然而我们可以观察到，无论是回调函数，还是主循环线程都显得非常麻烦臃肿。
按我的理解，它的实现手法相当的猥琐。

比如说隔一秒发送一次，逢3归0的做法。
我们有两种方式，第一，按照我们的理解一点一点把这种繁琐的做法改的更简练。
还有另一种做法，我们干脆放弃它的原有代码，重新设计我们自己的流程。

在这个事情里，我决定选择第二种做法，因为它的原功能实在太过无用。
一种很安全的办法是，我们可以复制它的原函数，改个名字，然后在它的基础上对它大动干戈。
我们一点一点删除没必要的按键操作，LED显示，以及乱七八糟的运算。

最终我们会得到一个非常简练的收发---转发函数。

这个时候我们可以很清晰的看到 它的数据流向。
也就是 发送方一秒一秒发出数据，在接收方进行一定规则的运算后返回来。

这个基本的数据 发送-转发 是我们的需要的。

现在为了让人展示，我们可以实现2530之间点对点的数传。

我们设计了以下的流程
发送方在接收到串口发送的数据后，将数据发出，接收方接到后，取反返回，发送方接收到返回的数据后，通过串口送出。

于是，我们可以看到，我们所要做的改变其实很少。
增加串口接收；
用取反代替原来莫名其妙的运算规则；


这个重构的例子暂时说到这里。
我必须承认，写着写着我都觉得这纯粹成了我过去一周工作的一个简单回顾。和重构的关系其实不算很贴切。

majianghua

你好  我有看到你调试的cc2530的SimpliciTI 协议栈  我现在在调试    可是一直都调试不通   就简单的点对点都没有通    老板给的两块板子也不知道有没有问题   你能把你调试好了的点对点程序发一份给我试试看啊   谢谢了     415419974@qq.com

子霖II

好东西

子霖II

楼主能否分享一下你的程序，2072286120@qq.com

书小叶

楼主能否给我发一份SimpliciTI协议栈的例程，万分感谢1982776405@qq.com

辛昕

书小叶 发表于 2016-4-12 22:00
楼主能否给我发一份SimpliciTI协议栈的例程，万分感谢

直接到TI官网下吧，搜一下CC2530或者直接搜 SimpliciTi
这都是两三年前的事情了，很多东西我电脑上也不复存在了

辛昕

majianghua 发表于 2014-2-19 18:03
你好  我有看到你调试的cc2530的SimpliciTI 协议栈  我现在在调试    可是一直都调试不通   就简单的点对点 ...

时间太久远了，当初也没备份好。不好意思。

宜搜

谢谢楼主的分享，内容特别特别好，学习到了。