代码的规范化—高质量程序的结构（一）

PS：均总结自前辈经验和自己的个性化心得

1、程序是让人看的，是要分享给队友或者领导，甚至是任何陌生的人共享交流，还有记得大学的时候一次全院大会，院长说，“写代码就和写毛笔字一样，要有书法的规矩，要有美感才可以，这也是区分到底是科班还是非科班的出身，到底这个人平时是严谨的还是大意的，这个人有没有对美的追求，有没有真实团队开发经验的一个考察点”

2、学校里很少有讲这些，只能自己总结和加以注意。

一、程序整体结构排版

1、使用空格分割程序的不同逻辑块或者代码块，比如类的声明之后

class A
{

};
//空

函数定义之后

void print()
{

}
//空

同一个类or函数体内，逻辑块or功能快要空格区分

if (xxx)
{
    xxx;
    //空
    for ()
    {
        xxx;
    }
    //空
    xxx;
}
else
{
    xx;
}
//空

2、做到一行代码只做一个事

//int a, b, c;//不推荐
//a = b = c;
//a = b + 1; a = a + b;

//推荐，容易阅读，方便注释
int a;//a
int b;//b
int c;//c

a = b + c;
a = b - c;

3、任何循环体，判断体等执行语句都使用｛｝

if ()
　　xxxx；//这看着就不爽,还容易让人误判

//推荐
if ()
{

}
//空

4、循环的for，while，do，开关switch，判断语句if等，不要独占一行

//while(){xx;};//不推荐

//推荐
while ()
{
}

5、养成变量定义就初始化的好习惯（尽可能的），防止疏忽而忘记，比如有时候程序很大，前面的变量没有初始化，那么后面忘记了，使用就会出错！

c++可以随用随定义，现在标准C99以后的C也可以这样了。

6、关键字后面留一个空格（突出关键字，识别关键字）

if ()
{
}

//constint a = 10;
const int a = 10;

7、函数名之后紧跟（）区别于关键字

//void print ();
void print();

8、列表里的分号（比如for循环等），列表的逗号（比如函数参数列表等），都要空格分开，不要挤到一起

赋值，比较，移位，算数，逻辑等二元运算符，前后加空格分开
但是，比如圆点. -> [] 运算符 前后不用加空格，只适用具有比较和传递关系的

//for (int i=0;i<100;i++)//丑陋 时间长了还眼疼
for (int i = 0; i < 100 || i > 0; i++)//++是一元的，一元就一个操作数，不空就挺好的了
{
}

//int x=a<b?a:b;//丑陋不堪
int x = a < b ? a : b;

/*空格太多了
int * p = & a;
p -> function();
(*p) . function();*/
int *p = &a;
p->function();
(*p).function();

//int arr [100];//不觉得很别扭么？
int arr[100];

9、程序应该左对齐，包括括号等标记，如果有嵌套，使用缩进！

/*接触过java，貌似都是这么写，包括自动生成的代码，也是习惯问题吧，c和c++里一般不这样写
if (){
    xxxx;
}*/

if ()
{//全部左对齐
}

do 
{
} while ();//末尾的while不另起一行！空一个格，然后沿着本行写while （）；

//嵌套的要缩进！
if ()
{
if ()
{
if ()
{
xxxx;
}
}
}

10、记得看林锐博士的书说，一行代码建议保持在70-80左右个字符，太长不容易看，也不容易打印，长了要拆分，拆分的新行要适当缩进，排版整齐。

/*这样显然看着很不舒适！
if ((long_long_long_long < very_big_high) || (a > b) && (short_short) <= 100000)
{
//
}*/
//拆分长语句，同时如果有运算符，那么要注意突出运算符的存在！一起拆分到下一行开头，类似的还有for语句（）里
if ((long_long_long_long < very_big_high) 
     || (a > b) 
     && (short_short) <= 100000)
{
    //
}

//函数参数也是如此
//void sum(int long_variable, int so_long_variable);
virtual int sum(int long_variable, 
                int so_long_variable);

11、* 和 & 到底应该靠近谁（数据类型 or 变量）的问题，查阅了很多相关资料，我认为应该紧跟变量名！

//int* a;//直观表达了指针是int类型的，但是弊端是
//int* a, b;//虽然a b可以分行，但是不一定每个人都这样做！不注意会认为b也是指针！

int *x, y;
char *name;

 

二、注释和版权，头文件和定义文件的结构
一般情况下，把类、函数、常量的声明写到头文件，定义写到.c or cpp文件

头文件：
1、程序通过头文件来调用标准库的功能，因为有时候源代码不方便公布（绝大多数），那么只需提供头文件和二进制库即可，用户调用接口声明就可以使用这些功能，不用看到和关心具体的实现，编译器自动查找提取。
2、头文件可以使得程序具备良好的层次性和结构性，提高阅读性，加强类型检查！
3、类似于java，如果软件的头文件很多很多（比如类似java里的dao，action，servlet等），可以分目录存放，便于维护。比如头文件保存到include目录，定义文件保存到source目录等等。如果某个头文件也需要保密，那么可以和定义文件放到一起！

 

在头文件和定义文件开头，要写清楚版权信息和作者信息，文件功能简介等（依据团队或者公司要求）

/*
*    Copyright (c) 2014, xxxxxxxx
*    All rights reserved
*    
*    文件名称：
*    主要功能：
*
*    当前版本：
*    作    者：
*    完成时间：
*    
*    //如果有以前版本的话，后面依次写上取代版本，完成时间，作者
*/

头文件结构

1、版权，文件信息说明
2、预处理操作
3、常量，类，函数，结构，联合，枚举等的声明
4、为防止头文件被重复引用，应该用#ifndef #define…… #endif结构产生预处理块
5、头文件只存放声明，不写任何定义！
6、c++的类内成员函数，如果声明的同时就定义，自动inline，不论是效率还是风格都无法保证！不推荐（除非函数特别小的时候）。
7、常量用大写字母标识！区分变量

//如下一个头文件myHeader.h
#ifndef MYHEADER_H //防止本头文件被重复引用
#define MYHEADER_H //编译器检测指定的预处理器变量，是否定义？如果没定义，则其后的全部指示都被处理，直到遇见#endif。若定义，则后面被忽略
//空行
#include <iostream>
#include <string>
#include "zijdingyi.h"//先引用标准库头文件，再引用自定义头文件
const double PI = 3.141592653;//注释常量意义且常量名大写，c里的宏定义 #define PI 3.14
……

//注释
void function();// 全局函数声明
……

//注释
class A
{
    //类声明
};
//空行
#endif //一般放到程序末尾

定义文件的结构

1、也要开头写好版权信息和作者程序信息等
2、头文件引用
3、定义代码

//如下一个定义文件 implementation.cpp
#include "myHeader.h"

//注释 
void function()
{
    //……
}

//注释 类成员函数实现
void A::print()
{
    //……
}

 

c和c++的注释为
单行注释 // 标准c新增
块注释 /* */

注释一般用于：
1、函数接口声明的意义解释
2、头文件和定义文件里，版权，作者，功能等信息说明
3、个人认为重要的代码行，块的提示信息
4、注释如果是为了学习使用，可以当作笔记（个人认为），如果是正式的软件产品，那么不能过多！

int arr[NUM];//声明一个数组 其实这就没有必要注释，是个人都能看懂看出！

不能反客为主，且花样要少，整洁干净！

5、代码一旦修改，相应的注释必须及时更新！
6、注释要负责任，不能瞎写或者想当然，不能模棱两可，要写清楚，写明白，不使用缩略词！不然，不如不写，以免误导别人或者以后自己看了都看不懂，或者以后自己看到这些注释，可能会怀疑自己的知识是不是学错了……
7、注释的位置不能随心所欲！要和被解释的代码靠近，代码的上面，或者后面都行（下面不行）
8、当代码有很多嵌套，那么要在一些嵌套结尾处加上注释，便于阅读，一目了然！

if ()
{
    //……

    while ()
    {
        //……

        for ()
        {
            //……
        }//end of for

        //……
    }//end of while

    //……
}//end of if


……

13、类的结构版式

class A
{
private://个人习惯，把private属性的成员写在最前面，不过有人推荐public接口写在最前面，这样的话重点是关心接口。具体看团队开发的规定了
    int a;
public:
    xxxxx;
};

 

三、变量的命名习惯
推荐匈牙利法或者驼峰命名法（具体还是要服从团队的规定）
匈牙利法：变量或者函数名加入前缀词，提醒用户如何理解。命名比较麻烦，但是直观，易于阅读（微软推荐）

char *chName;//字符变量加ch前缀，下一字母大写。
int iNum;//int i
float fVar;//float f

驼峰命名法：变量名或函式名是由一或多单字连一起而构成唯一识别字，则第一个单词小写，后面的每一个单词的首字母都大写

String myFirstName;
String myLastName;//这样的变量名看上去就像骆驼峰一样此起彼伏

几个共性问题

1、变量名和函数名，类名等要有意义，望文知意！最好是英文单词（可见确实英语很重要，不止体现在此）组合，不能用汉语拼音！！！！！
2、现在的标准C不再具体规定变量名字的长度，但是不是越长越好（不过也不一定，因为比如OC，苹果就是希望方法名越长越好）,一般局部变量使用短的，最好是单个字符，比如i，j，k，p，q等
3、不要把不同风格的命名规则使用在一个程序里，要么用驼峰，要么用匈牙利，要么用其他的
4、不要依靠大小写区分变量（虽然他们不一样）

int sum(int x, int X);//x和X很容易混淆
double SUM(double x, double y);//函数名也是一样

5、对于全局变量和局部变量，虽然可以重名（作用域不同），但是还是避免比较好

6、针对变量名，应该使用名词，或 形容词 + 名词

double preCode;
double nextCode;
int oldNum;
int newNum;
char *redCar;
char *blueCar;

7、全局函数的名字应该用 动词 or 动词 + 名，类成员函数名只用 动词，而类的对象充当名词的角色。

Point point;
point.draw();//类成员函数
drawPoint();//全局函数

8、对于有互斥含义的，使用反义词命名

int minValue;
int maxValue;
void setAge(int age);
int getAge();

9、不论什么名称，都不能混入数字！

int a1;//不推荐，这是偷懒的行为，说明程序员不动脑子，造成无意义的命名
int a2;//除非程序本身需要编号，则在使用编号命名

10、常量名使用大写，且用下划线分割

const int MAX_NUM;
#define MIN_VALUE 10;

11、静态变量声明使用前缀 s_

static int s_minValue;//s_    static

12、全局变量之前，使用前缀 g_

double g_money;//g_     global

13、类的数据成员前，使用前缀 m_

void Point::setAge(int age)
{
    m_age = age;//m_      member     避免类数据成员和成员函数或者参数同名or不好区分
}

 

欢迎关注

dashuai的博客是终身学习践行者，大厂程序员，且专注于工作经验、学习笔记的分享和日常吐槽，包括但不限于互联网行业，附带分享一些PDF电子书，资料，帮忙内推，欢迎拍砖！