I was reading this numpy script and got this line which makes a good case for how unnecessary comments arise:
sp = 0.5-np.mod(jj,2)# even number of band,1/2; odd band, -1/2 to distinguish upspin and downspin
The coder wrote a clever succinct expression, then he find the need to explain. The explaination essentially in code:
$if jj % 2 == 0
sp = 1/2.
$else
sp = -1/2.
It is all about how human mind works. We let things go smoothly when it fits our expectation. When things start to fit out expectations in a row, we even kick into an auto-pilot mode where we spend almost no effort at all.
However, out mind gets alerted when sense inconsistency from our expectations. When that happens, our train of thoughts slows down or even halts, and we have to figure out the inconsistency, develop new understanding and build up new sets of expectations. Afterwards, we will continue, but always start slow, and only accelerates when our expectation fits what we receive for a couple consecutive episodes.
When we read some code, we always need to build up some expectations first -- that is to figure out what the code is supposed to do. If there is no comments, we will simply trying to figure that out from the code directly. If there is such comment exist that explains what the code is supposed to do, we will read it; but then we don't simply cruise along the code, we always read the code an
Let's say we want to do interpolation of an array. Two persons claim they know how to do it. One knows to use an interp function from a familiar library, e.g. numpy in Python. The other uses a source code routine.
The former knows the action by name while its details are opaque. Even he understands what interpolation is he does not know or can't be sure what the library routine actually does.
The latter know the action also by name but within sight, he knows exactly what is going on.
With an analogy to real life, let's say, go to school. The former gets on a bus. The bus has a name and he knows which bus to get on. And on the bus there are descriptions (documentations) that explain what the bus supposed to do (get the person to school and maybe what the school is). However, the bus does not have windows, and the riders have little idea how the bus gets them to school.
The latter walks to school. He also refers to the action by name -- go to school -- but he has clear idea what that phrase means in gory d
I implemented a simple macro (in MyDef) today:
$(for:a,b,c and 1,2,3)
a = 1;
It soothed a long-time sore spot of mine. Feels good, has to post somewhere :)
Let's say we write a program called simple-application-1, which has straight forward logic.
Then we may write another program called slightly-complicated-application-2, which shares the logic with simple-application-1 at a more or less abstract level -- details vary but overall logic is the same.
Now as we start to write yet another program, complicated-application-3, we get lazy and would like to refactor the abstract logic out. After some struggle, we have --
Note that the code:
$call go_to_school
subcode: go_to_school
$call get_bag
$call put_on_shoes
$call get_out_of_door
$call wark_toward, school
We often will write code in a way that optimize for the performance, in the meantime, sacrifices readability. In one example, we may insert low level tweaks such as inline assembly code. In another example, we may use some complicated algorithm to replace a simple one. L et's say in the code we need a sorting function, we may write a simple insertion code, but that performs poorly when the data size gets big. So we may use quick sort instead, but quick sort does not perform as well for small data set which often are the frequent use case s, and further, quick sort performs poorly when the data is already roughly in order. So to optimize, we need add certain pre-checking code and choose algorithm based on the checking result. Before long, we have several hundered lines of code to do sorting and they are a ll necessary -- but now the task of comprehending the program just expanded by several hundered lines and they are several hundered logic intensive code.
This is not desirable because the complicated sorting
Tim Daly on literate programming: we write down code which is what we do, but we didn't write down why and this why is super important.
Consider the action of "go to school". It is getting the bag, puting on shoes, getting out of the doors, and walking toward the location called school. If we drescibe it action by action, later when we read it it will be a puzzle on what we are doing -- we are missing th e why. So consider following code:
$call go_to_school
subcode: go_to_school
$call get_bag
$call put_on_shoes
The first page of your main code is very important. This file is what first opened and read by reviewers who are not familiar with your code and they open your first source file to orient themselves. Consider following examples when they open your main file:
20 lines of copyright/license disclaimer
10 lines of #include ...
10 lines of constant definition
100 lines of data structure definitions
The key of ambiguous language is to facilitate the receiver (listener/reader/reviewer)'s ability to guess. The base of our ability to guess is logic, and we only can track logic within 5 plus or minus 2 items of context. For example, logically a start requires an end. So if the start and end are all within 5-7 items or at least within a single glancable block, then we perceive a complete context. Whthin that context, we are very good at guessing the role of individual items -- they must belong to one of the stages -- initialization, development, further development, cleaning up, and exiting. Because of this increased guessablility, we can exercise more flexibility in the other elements such as the naming of each items.