编码习惯调整

编写代码，我是半路出家，没有哪位老师给出明确的建议怎么书写代码注释。所以，从来也没形成过自己的代码注释风格，汗颜。这一段时间在写PCI-CAN的驱动接口封装，感觉编写代码时候比较费力，绕路，有些基本性的编码技能需要改善。

1.代码注释

注释的目的是什么呢？代码是给人看的，给自己也给别人看。既然这样，注释应该简单、清晰、有用。这一点可以参加转载的文章编写易于理解代码的六种方式

注释是用中文还是英文呢？看习惯老外写的代码，总觉得中文注释别扭，表述不清晰，而且中文注释总是给你语法错误提示。结合自己的外语水平，还是用简单的英文注释。

什么地方加注释？

函数、全局变量、设计的数据结构、宏定义。其实准则很简单，你觉得，如果不加注释别人就比较费劲的理解时，就加注释。如果代码含义很清楚，变量名字一看就懂，那就没必要增加注释。少的注释不可取，多而乱的注释更加不可取。

编写代码的同时，增加注释。可能要说，编写代码后，很容易发现简单的错误，反过来修改代码，同时又得修改注释。那我认为，如果你没有想清楚自己的代码实现什么样的功能，输入输出关系，就最好在草稿纸上画一画，理清思路。然后再动键盘，这样其实大大的提高代码速度和代码设计能力。

 下边的函数注释风格值得推荐。

/******************************************************************************
*
* Function   :  canActivate
*
* Description:  send 0x20 can command to activate can devices.
*
* Parameters:   portHandle - contain pointers to pciDevice and MSG_BUF.
*
* Return:        V_SUCCESS
*                V_ERR_UNKOWN
*                V_ERR_WRONG_PARAMETER
*
*****************************************************************************/
Vstatus _stdcall canActivate(VportHandle portHandle)
{
    pciHandle* pDev=(pciHandle*)portHandle.pHandle;
    U8 portNum=portHandle.portIndex;
    if (pDev==NULL)
    {
        return V_ERR_WRONG_PARAMETER;
    }

    U8 cmd[5]={0xF0,0x02,0x20,0,0};
    cmd[3]=portNum;
    for (U16 i=0;i++;i<sizeof(cmd)-1)
    {
        cmd[4] = cmd[4] + cmd[i];
    }
    __send_cmd(pDev,cmd,sizeof(cmd));

    Vstatus rt=__wait_for_ack(&portHandle,(U8)0x20);

    return rt;
}

下边的数据结构设计注释风格，值得推荐。

// internal type,real works,input of most functions.
class pciHandle 
{
public:

    PLX_DEVICE_OBJECT plxHandle;    
    
    RV_Thread hThread;
    
    void* VaRAM;    // virtual offset of dual-static ram units in system space.
    
    void* VaSem;    // virtual offset of dual-static ram semaphores in system space.
    
    U8 portUsed;    // bit[0]indicate port1 is in use; bit[1] indicate port2 is in use
    
    MSG_BUF* pBufs[2];    // allocated when pci device opened. free when no port opened.
    
    CRITICAL_SECTION cs;    // can ports exclusively using pci device.
    
    U8 devIndex;    // pci device index,order by (bus,slot,function).

public:
    pciHandle();
    ~pciHandle();
};

2.代码编写风格

代码是给人看的，所以如果你编写了一行非常别扭的代码，连你自己每次看时候都非常小心，那么还是重新写，简单点好。如果是逻辑不清晰，在草稿纸上画一画；如果是语法晦涩，那么你就应该直接用最直白的方式，让别人看懂你的代码是干什么的。不要指望在代码风格上，向别人展现你对编程语言本身的高深理解，代码是给人看的，而不是圣经供人膜拜。

3.代码流程设计

切记，在你没想好你要写什么之前，不要轻易动键盘。很多时候，我们习惯在键盘上实验自己的想法，其实不如在草稿纸上画一画自己的想法。每个模块逐个捋一遍思路，看看关键数据结构的设计，关键函数流程的设计是不是合适。如果不合适，那好，继续在草稿纸上画。犯错误在草稿纸上，比敲击过一堆堆的代码返工好的多，省时间的多。

以上个人理解，待添加。