软件设计规范

最后编辑于: 2017-10-16 11:17  |  分类: 软件通用技术  |  标签: 设计规范   |  浏览数: 1770  |  评论数: 0

---

1. code编辑

1.1 文件编码与格式

code文件必须使用UTF-8编码。

行结尾使用dos格式。

1.2 code风格

总的原则，代码一定要排版整齐，有条理。

排版的混乱说明了思维的混乱。

下面，以C语言为例来说明。

1. 缩进不能混乱

必须用空格缩进，不能用tab。

(Makefile等必须用tab的除外)

2. 变量类型的使用应一致。

比喻，定义1byte无符号变量，

如果使用了unsigned char, 就请一直使用。

不要一会用unsigned char，一会用uchar，一会用uint。

3. 代码块之间要加 空行 隔离，让人视觉上容易区分。

比如 2个结构体的定义之间 加上空行。

1.3 关于注释

1.2.1 文件头注释

每个源文件必须要有文件头注释，且必须位于文件最开头。

需要至少说明清楚：

• 本code文件实现的功能，

• 以及版本更替产生的改动，

• 以及必须说明的注意事项。

注释应按照javadoc风格。 并排版明晰有条理。

应至少包含以下标签:

• @author

• @version

• @date

1.3.2 函数头注释

每个函数(特别是 接口函数，必须有注释)都应有函数头注释，按照javadoc风格。

必须包含以下几个标记：

• @brief

• @param

• @return

• @author

• @date

举例如下：

/**
*  @name  uart3_transmit
*  @brief  
*  
*  @param (const char*)s - The send string.
*  @param (unsigned short)len - The length.
*  
*  @return unsigned short - The counter of the actually send bytes.
*  
*  @interface void
*
*  @note   带发前监听
* 
*  @author Leiad
*  @date   15-5-21 17:43:48
*/
unsigned short uart3_transmit(const char *s, unsigned short len)
{
....
}

1.3.3 code内注释

2. 文档

文档允许用Markdown、word、excel三种格式编写。

如果使用Markdown文档，应转换为html格式，并与md源文件一起提交。

---

上一篇: 硬件设计规范v1.1

下一篇: 树莓派上的打印服务器