For a coder, write codes is for his life. But write better codes is mostly for his colleagues’ life :)
If you are an algorithm engineer, performance is the only evaluation criterion. But most of the coder are not working for algorithm, just write some functional codes to solve some problem. In this situation, evaluation criterion become complex. But in most of the cases, the codes can collaborate with others’ codes is the most important factory of evaluation criterion, I think. What’ are the codes can collaborate with others? Within context!
Here I would not repeat the same stuff that others always talk about, like how to name codes, how to comment and etc. I only discuss the context that organize your codes, today.
First of all, what’s context? Let’s think about a talk below and what’s wrong with me?
My friend: What’s temperature?
Me: It’s -30 Celsius.
My friend: No way, it’s hot today. It must beyond 26 Celsius.
Me: I was talking about Arctic temperature just now.
My friend: ……
Everyone will consider me was an odd man and my friend is a normal people. Why? Because context. What’s context? Context is the background information of current situation.
Everybody’s/My friend’s context: Time(now) / Location(current location) / People(Me and My friend)
My context: Time(unknown) / Location(Arctic) / People(unknown)
When my friend ask me question without declare other information, the “other information” are all in the context. Because I’m not using the default context but some random context make everyone consider I’m strange.
But What if I declare this talk happened in Iceland? Different situations have different context.
Obviously, within context let’s make sense. Writing codes is the same. If you write without context, it will make your colleagues confuse. But unfortunately I met that many coders didn’t make sense while coding.
Second, what’s codes are within context. Let’s read two different version codes and judge which’s better.
Hard to judge? Let’s review their context? Remember bundle the context with the call stacks. Every stack is a new situation.
Clear? Left code dig a deep hole for the “send” function. Remember “Every stack is a new situation” and “Context is the background information of current situation”. Inside left code, “recv” and “send” are no longer in the same situation, also in the different Context. In real world, left code will make your colleagues hard to understand what’s the function for. It will make people need to jump functions over and over again to took a full look of this function, although it seem to be cleaner from the outside. It’s a common problem that coders easily make because of following “Clean API” principle. But I think “Clean API” principle should follow the “Coherent context” principle.
“But hey! Why do you need to focus ‘recv’ and ‘send’ to appear in the same situation and the same context? You just paint the ‘recv’ and ‘send’ with the same color to make you ‘make sense’ ”.
Third, what’s the coherent context? “Coherent context” is not context any more. Now it‘s’ the bridge between past and future. Every code need to make sense to the code both before and after. But the actual question is subjective and objective.
“Subjective” comes from we don’t in the same context. Everybody aren’t born in same place. Education and culture aren’t same. But we are human so that we still share same context anyhow, “Objective” still exists at the same time. So there are still some things we can talk.
Imagine coding is just talking to others and every single function is just a sentence. Every time you enter a call stack or exit call stack is change the method talk to others. And “recv” is hello and “send” is goodbye. Would you put “recv” and “send” in different context? One day you go to work in the morning, when you enter your office and say “Good morning” to colleagues and then communicate with your colleagues using email while working. Would you using email to say “bye” to your colleagues when you go home?
So, a coherent context should maintain the “enter” code and “exit” code in the same context. A easy example is you should keep “new” and “delete” in the same scope in C++. It’s why you need to keep “recv” and “send” in the same context.
And extends the theory, if two function is a pair or some function is a group, don’t separate them. But there are so many function, why do you consider two functions are in the same pair or group? This question becomes subjective but is still traceable somehow. Abstract level is the key.
If two function are in the same abstract level, they are in the same group. But I can’t give you the specific definition of abstract level because it’s abstract and also subjective somehow. But you can summarize it from others’ work by yourself. If you working for embedded system, you will hear about HAL(hardware abstract layer) and LL(Low layer). If you have learnt computer network, you must know OSI model (https://en.wikipedia.org/wiki/OSI_model) that separate model 7 different layer. And they all are abstract levels, every layer represent an abstract level. You can also get inspire from some famous framework.
Let’s take a look of a C++ code about ssl client with openssl. (from https://wiki.openssl.org/index.php/SSL/TLS_Client)
It’s a long code, but do you think it’s gross any more? Limit code length is not necessary sometimes. But “context” and “make sense” does.
