some notes about industrial code

1.about parameters checkout

this is general traditions to check the received parameters . 

for instance , when we want to get  an array of string standing for network internet card(namely , NIC) , we may compose the following interface:

vector<NIC> NIC_query(char *pch);

we need to check the parameters as follows:

if(pch)return 0; //nothing to do , just return with success;

but , this is far from enouth , we should make sure the function can run at any condition!

this is , we should make sure the following points:

1. totoal buffer is less than our buffer given
2. single NIC name is less than our buffer given
3. can NOT contains illegal characters , such as * , = , | and so on
4. the totoal NIC number should less than our buffer number
5. others

2.about operation result

in face , we are easy to return with opertion result when dealing with such interface as :

int setMode(int mode);

but considering the following conditions : 

(1)

int getInputNum();

we have no other IMPOSSIBLE value indicating the operation "get" result , as our result is overlapping with operation result!

(2)

NIC* query(char* pname);

when we want to query the NIC information from database , how to indicating the operation result and query result?

we may fail return with NULL , but is that really work all well ?

consider we just query a NOT EXISTED NIC , that is , we get the query result NULL , but our program may take it as operation failed!

we had better separate the operation result with  process result !

3.about what if operaiton failed

consider the following situation , we need to connect port A with port B , the operation is to call for A's method to pointer to B and call for B's method to pointer to A.

so here give the simple implement code:

int connect(NIC A, NIC B)
{
    　connectto(A,B); 　　//connect A to B
　　　 connectto(B,A);　　　//connect B to A
　　　　return 0;　　　　//success
}

what if one of the function failed?

for instance , we have connectto(A,B) , and it failed while connect(B,A) , should we deal as follows:

int connect(NIC A , NIC B)
{
    if(connectto(A,B)<0)return -1;
　　if(connectot(B,A)<0)return -1;
　　return 0;
}

the above code is treated as general operaiton , but it has flaws !

the connect() function has side effect as it fails but already connectto(A,B) , so when user know the connect() fails , but

he does not known the connectto(A,B) have make effect already!

we need to restore the initial status once any of process failed , on condition that the operation is backward-able .

so what about the recommneded solution?

int connect(NIC A, NIC B)
{
　　if(connectto(A,B)<0)
　　{
　　　　if(disconnectto(A,B)<0)
　　　　{
　　　　　　printf("restore failed!");
　　　　}
　　　　return -1;
　　}
　　if(connectto(B,A)<0)
　　{
　　　　if(disconnect(B,A)<0)
　　　　{
　　　　　　printf("restore failed!");
　　　　}
　　　　if(disconnectto(A,B)<0)
　　　　{
　　　　　　printf("restore failed!");
　　　　}
　　　　return -1;
　　}
　　return 0;
}

yes , this is robost code , if one of opeartion failed , it will restore to the initial status .

some may wonder , what if the restore operation function failed?

actually , we have no good ways to fix the dis-working of restore function , exception for just printf("restore work failed , i am so sorry.").

this is usually enough for general condistion , if not , we can also locate the error message.

However , when a single operation includes a great many steps , and the worst condistion is , the last step fails , so we need to restore all steps!

and you should choose a wise solution to solve the problem  , but not only restore step by step .

4. 0=sucess and -1=fail VS 0=fail , 1=sucess

in fact the above 2 tradition is usually common on nowdays programming.

we can see 1=success on application level , and in linux kernle , 0=sucess is the standard ?

the question , who is better?

i have to admit , 1=sucess is better to understand , consider the following code :

if(read(buff)==1)
{
      printf("%s",buff);  
}

this is easy to understand , here we give another style of code:

if(read(buff)==0)
{
    printf("%s",buff);
}

you will find to understand the code easier when treat the return value as error code , that's 

if the error code of read function is NULL (0) , that's no error occurred.

and consider the following condition : 

if(is_status_on()==1)
{
    printf("current staus is on");
}

the return value is about process result , when dealing with result , the code will look like : 

if(is_status_on(&status)==1)
{
     printf("current status is %s",status);  
}

the correspond code can be implemented as :

if(is_status_on()==1)
{
    printf("current status is on");
}

if(is_status_on(&status)<0)
{
    printf("error occurred during is_status_on() ");
}
printf("current status is %s",status);

so you see , you can find both are easy to understand !