之：你的代码别人有耐心看么？
时间：10-02
整理：3721RD
点击：
本文章为【单片机到嵌入式之路】序列之：你的代码别人有耐心看么?我们将从代码格式来审视你的代码，主要是从下面3个方面进行讲解：1.代码格式的重要性2.规范自己的代码格式3.函数设计和变量定义格式
一、代码格式的重要性：
好的代码格式犹如男工程师看见美女，女工程师看见帅哥一样，有种一见钟情的感觉。但是事实上很多人不注重代码的规范性，结果写出来的代码，没有连自己都不想看第二遍，这是工程师的大忌。
不论是硬件工程师还是软件工程师，良好的代码格式是基本功。如果你写的代码别人就看了几行就感觉恶心、呕吐，你说你的代码别人还有耐心全部看完么?
以前看见一个研究生，以为自己多牛逼，写的代码没有一行注释了。变量取名也是莫名其妙的，结果有一个bug。导致他检查了半个月。何必这样害自己呢?不要以为你写的代码多高级，不要加注释，不注重格式，怕别人复制。别人想复制你的代码，说明你的代码有价值。
好了不多少了，直接进入下一个小点吧。O(∩_∩)O~
二、规范自己的代码格式
1.文件结构
a) 版权和版本的声明
这个是每个公司或者个人为了保护自己的代码而写的。格式也不是固定了，主要根据个人的爱好来写的。下面贴出本人喜欢的格式。
/*
* Copyright (c) 2014, 鑫亮电子
* All rights reserved.
* 文件名称：usart.c
* 摘 要：串口驱动函数
* 硬件平台：STM32F030探索套件
* 当前版本：V0.0
* 完成日期：2013-01-09
* 修改记录：
*/
很简单，仅仅作为参考吧。
b) 头文件的结构
头文件由三部分内容组成：
(1)头文件开头处的版权和版本声明。
(2)预处理块。
(3)函数和类结构声明等。
下面主要看头文件的类型，以个人平时的程序为例：
/* Includes ----------------------------*/
#ifndef __EXTI_H //防止重定义
#define __EXTI_H
//个人爱好
#include "STM32F0xx.h" //包含的头文件
void EXTI_KEY_Init(void); //外部中断初始化
//个人爱好
#endif
c) 定义文件的结构
定义文件有三部分内容：
(1) 定义文件开头处的版权和版本声明。
(2) 对一些头文件的引用。
(3) 程序的实现体(包括数据和代码)。
下面以常见的例子为例：
// 全局函数的实现体
void Function1(…)
{
…
}
2.程序的板式
为了更好的讲解程序的版式，下面以一个例子为例来讲解：
/***************************************
* 函数描述：外部中断0服务程序
* 输入参数：No
* 返 回 值：No
* 说 明：无
* 修改记录：无
****************************************/
void EXTI0_1_IRQHandler(void)
{
if(EXTI_GetITStatus(EXTI_Line0) ！= RESET)//判断线0上的中断是否发生，可以理解为标志位
{
/* Toggle LED3 and LED4 */
GPIO_WriteBit(GPIOC,GPIO_Pin_8,
(BitAction)((1-GPIO_ReadOutputDataBit(GPIOC, GPIO_Pin_8))));
GPIO_WriteBit(GPIOC, GPIO_Pin_9,
(BitAction)((1-GPIO_ReadOutputDataBit(GPIOC, GPIO_Pin_9))));
/* Clear the EXTI line 0 pending bit */
EXTI_ClearITPendingBit(EXTI_Line0);//清除LINE0上的中断标志位
}
}
A.注释方式有有两种【//】 和 【/* */】.
B.对齐方式要注意。
C.函数的设计也很重要。
D.变量的定义也很关键。
E.拆行也很重要，关键在其可读性。
F.必要的注释可以让读者理解的更快，对自己以后维护更便捷。
三、变量的定义和函数的设计
1.变量的定义
a) 见名知意
int width; //定义宽度
#define MAX 100; /* 最大值为100*/
等等，上面也是两种注释方式。
2.函数的设计
函数的设计其实很关键，对读者相当重要。一个好的函数设计可以让读者看出设计者别出心裁。下面简单举几个例子来说明：
void Object::SetValue(int width, int height)
{
m_width = width;
m_height = height;
}
下面再讲述一下断言的使用：
程序一般分为Debug版本和Release版本，Debug版本用于内部调试，Release版本发行给用户使用。
断言assert是仅在Debug版本起作用的宏，它用于检查“不应该”发生的情况。下面例子是一个内存复制函数。在运行过程中，如果assert的参数为假，那么程序就会中止(一般地还会出现提示对话，说明在什么地方引发了assert)。
void *memcpy(void *pvTo, const void *pvFrom, size_t size)
{
assert((pvTo ！= NULL) && (pvFrom ！= NULL)); // 使用断言
byte *pbTo = (byte *) pvTo; // 防止改变pvTo的地址
byte *pbFrom = (byte *) pvFrom; // 防止改变pvFrom的地址
while(size -- > 0 )
*pbTo ++ = *pbFrom ++ ;
return pvTo;
}
assert不是一个仓促拼凑起来的宏。为了不在程序的Debug版本和Release版本引起差别，assert不应该产生任何副作用。所以 assert不是函数，而是宏。程序员可以把assert看成一个在任何系统状态下都可以安全使用的无害测试手段。如果程序在assert处终止了，并不 是说含有该assert的函数有错误，而是调用者出了差错，assert可以帮助我们找到发生错误的原因。
很少有比跟踪到程序的断言，却不知道该断言的作用更让人沮丧的事了。你化了很多时间，不是为了排除错误，而只是为了弄清楚这个错误到底是什么。 有的时候，程序员偶尔还会设计出有错误的断言。所以如果搞不清楚断言检查的是什么，就很难判断错误是出现在程序中，还是出现在断言中。幸运的是这个问题很 好解决，只要加上清晰的注释即可。这本是显而易见的事情，可是很少有程序员这样做。这好比一个人在森林里，看到树上钉着一块“危险”的大牌子。但危险到底 是什么?树要倒?有废井?有野兽?除非告诉人们“危险”是什么，否则这个警告牌难以起到积极有效的作用。难以理解的断言常常被程序员忽略，甚至被删除。
【注意】：
A.使用断言捕捉不应该发生的非法情况。不要混淆非法情况与错误情况之间的区别，后者是必然存在的并且是一定要作出处理的。
B.在函数的入口处，使用断言检查参数的有效性(合法性)。
C.在编写函数时，要进行反复的考查，并且自问：“我打算做哪些假定?”一旦确定了的假定，就要使用断言对假定进行检查。
D.一般教科书都鼓励程序员们进行防错设计，但要记住这种编程风格可能会隐瞒错误。当进行防错设计时，如果“不可能发生”的事情的确发生了，则要使用断言进行报警。
以上内容参考了林锐博士的【C/C++ 代码规范参考】一书。
对于代码对齐 和 一些其它的内容，我希望大家可以多阅读别人的代码，多练习，只有多练习了才能掌握于心，才能运用自如。
以上的内容大家可以作为参考，就作为抛砖引玉吧，希望大家能提出更好的方法，共同提高才是王道！ 更多学习交流要以加Q群： 310341439
一、代码格式的重要性：
好的代码格式犹如男工程师看见美女，女工程师看见帅哥一样，有种一见钟情的感觉。但是事实上很多人不注重代码的规范性，结果写出来的代码，没有连自己都不想看第二遍，这是工程师的大忌。
不论是硬件工程师还是软件工程师，良好的代码格式是基本功。如果你写的代码别人就看了几行就感觉恶心、呕吐，你说你的代码别人还有耐心全部看完么?
以前看见一个研究生，以为自己多牛逼，写的代码没有一行注释了。变量取名也是莫名其妙的，结果有一个bug。导致他检查了半个月。何必这样害自己呢?不要以为你写的代码多高级，不要加注释，不注重格式，怕别人复制。别人想复制你的代码，说明你的代码有价值。
好了不多少了，直接进入下一个小点吧。O(∩_∩)O~
二、规范自己的代码格式
1.文件结构
a) 版权和版本的声明
这个是每个公司或者个人为了保护自己的代码而写的。格式也不是固定了，主要根据个人的爱好来写的。下面贴出本人喜欢的格式。
/*
* Copyright (c) 2014, 鑫亮电子
* All rights reserved.
* 文件名称：usart.c
* 摘 要：串口驱动函数
* 硬件平台：STM32F030探索套件
* 当前版本：V0.0
* 完成日期：2013-01-09
* 修改记录：
*/
很简单，仅仅作为参考吧。
b) 头文件的结构
头文件由三部分内容组成：
(1)头文件开头处的版权和版本声明。
(2)预处理块。
(3)函数和类结构声明等。
下面主要看头文件的类型，以个人平时的程序为例：
/* Includes ----------------------------*/
#ifndef __EXTI_H //防止重定义
#define __EXTI_H
//个人爱好
#include "STM32F0xx.h" //包含的头文件
void EXTI_KEY_Init(void); //外部中断初始化
//个人爱好
#endif
c) 定义文件的结构
定义文件有三部分内容：
(1) 定义文件开头处的版权和版本声明。
(2) 对一些头文件的引用。
(3) 程序的实现体(包括数据和代码)。
下面以常见的例子为例：
// 全局函数的实现体
void Function1(…)
{
…
}
2.程序的板式
为了更好的讲解程序的版式，下面以一个例子为例来讲解：
/***************************************
* 函数描述：外部中断0服务程序
* 输入参数：No
* 返 回 值：No
* 说 明：无
* 修改记录：无
****************************************/
void EXTI0_1_IRQHandler(void)
{
if(EXTI_GetITStatus(EXTI_Line0) ！= RESET)//判断线0上的中断是否发生，可以理解为标志位
{
/* Toggle LED3 and LED4 */
GPIO_WriteBit(GPIOC,GPIO_Pin_8,
(BitAction)((1-GPIO_ReadOutputDataBit(GPIOC, GPIO_Pin_8))));
GPIO_WriteBit(GPIOC, GPIO_Pin_9,
(BitAction)((1-GPIO_ReadOutputDataBit(GPIOC, GPIO_Pin_9))));
/* Clear the EXTI line 0 pending bit */
EXTI_ClearITPendingBit(EXTI_Line0);//清除LINE0上的中断标志位
}
}
A.注释方式有有两种【//】 和 【/* */】.
B.对齐方式要注意。
C.函数的设计也很重要。
D.变量的定义也很关键。
E.拆行也很重要，关键在其可读性。
F.必要的注释可以让读者理解的更快，对自己以后维护更便捷。
三、变量的定义和函数的设计
1.变量的定义
a) 见名知意
int width; //定义宽度
#define MAX 100; /* 最大值为100*/
等等，上面也是两种注释方式。
2.函数的设计
函数的设计其实很关键，对读者相当重要。一个好的函数设计可以让读者看出设计者别出心裁。下面简单举几个例子来说明：
void Object::SetValue(int width, int height)
{
m_width = width;
m_height = height;
}
下面再讲述一下断言的使用：
程序一般分为Debug版本和Release版本，Debug版本用于内部调试，Release版本发行给用户使用。
断言assert是仅在Debug版本起作用的宏，它用于检查“不应该”发生的情况。下面例子是一个内存复制函数。在运行过程中，如果assert的参数为假，那么程序就会中止(一般地还会出现提示对话，说明在什么地方引发了assert)。
void *memcpy(void *pvTo, const void *pvFrom, size_t size)
{
assert((pvTo ！= NULL) && (pvFrom ！= NULL)); // 使用断言
byte *pbTo = (byte *) pvTo; // 防止改变pvTo的地址
byte *pbFrom = (byte *) pvFrom; // 防止改变pvFrom的地址
while(size -- > 0 )
*pbTo ++ = *pbFrom ++ ;
return pvTo;
}
assert不是一个仓促拼凑起来的宏。为了不在程序的Debug版本和Release版本引起差别，assert不应该产生任何副作用。所以 assert不是函数，而是宏。程序员可以把assert看成一个在任何系统状态下都可以安全使用的无害测试手段。如果程序在assert处终止了，并不 是说含有该assert的函数有错误，而是调用者出了差错，assert可以帮助我们找到发生错误的原因。
很少有比跟踪到程序的断言，却不知道该断言的作用更让人沮丧的事了。你化了很多时间，不是为了排除错误，而只是为了弄清楚这个错误到底是什么。 有的时候，程序员偶尔还会设计出有错误的断言。所以如果搞不清楚断言检查的是什么，就很难判断错误是出现在程序中，还是出现在断言中。幸运的是这个问题很 好解决，只要加上清晰的注释即可。这本是显而易见的事情，可是很少有程序员这样做。这好比一个人在森林里，看到树上钉着一块“危险”的大牌子。但危险到底 是什么?树要倒?有废井?有野兽?除非告诉人们“危险”是什么，否则这个警告牌难以起到积极有效的作用。难以理解的断言常常被程序员忽略，甚至被删除。
【注意】：
A.使用断言捕捉不应该发生的非法情况。不要混淆非法情况与错误情况之间的区别，后者是必然存在的并且是一定要作出处理的。
B.在函数的入口处，使用断言检查参数的有效性(合法性)。
C.在编写函数时，要进行反复的考查，并且自问：“我打算做哪些假定?”一旦确定了的假定，就要使用断言对假定进行检查。
D.一般教科书都鼓励程序员们进行防错设计，但要记住这种编程风格可能会隐瞒错误。当进行防错设计时，如果“不可能发生”的事情的确发生了，则要使用断言进行报警。
以上内容参考了林锐博士的【C/C++ 代码规范参考】一书。
对于代码对齐 和 一些其它的内容，我希望大家可以多阅读别人的代码，多练习，只有多练习了才能掌握于心，才能运用自如。
以上的内容大家可以作为参考，就作为抛砖引玉吧，希望大家能提出更好的方法，共同提高才是王道！ 更多学习交流要以加Q群： 310341439
排版没有做好，看起来有些累
已加群， 非常认可小编说的， 共同提高方为王道; 之前学习的时候，听到过一句话，代码是写给其他人看的，或者是用的，看小编的文章， 还真的是这么回事。