goals: self documenting

The objective: code that is more readable because it's succinct.

Using conventions, short functions, and system wide abbreviations sets the stage. Self-documenting code completes the arcology pattern.


Carefully decoupled small classes.


Using assert() well is an excellent jedi trick.
// Instead of this: 
return 4/step; // step always > 0 

// Use this: 
return 4/step;
It's the specification, documented and enforced-- the mental model of how this code is supposed to work.

Done pervasively it offers relief from bug-hunting, by dropping you right at the problem and telling you what it is.

It's also an insurance policy against future changes. Right now, that pointer may be guaranteed non-null, but if a future change alters that, best to find out right away.

Write asserts as you write the code.

const variables

Bim: Here's that book I borrowed. Thanks, I enjoyed it.
Reader: Did you.. write in my book?
Bim: Only a little.

"const" = "read only."

Lock intermediate results, so Reader can spend attention elsewhere.
const doub rad = sqrt(x*x + y*y); // "rad" not changing.
Combined with short functions it is a powerful element of self documenting code.

const member functions

Separate functions that build from those that consume. Prevent unexpected changes to the data's internal state by consumers.
void  make(); // not const, changes state. 
void  load(); // not const, changes state. 
bool valid() const; 
int   size() const; 
void  save() const; 
void  dump() const;

Isolate code with interior classes

class Threaded { 
  static void Run(ThreadCB, int N, void*v=0); 
  static int numCPUs(); 
  static void* _Run(void*); 
  static int find_free(vector<int>&, vector<pthread_t>&); 
  struct ARGS { 
    ThreadCB CB; 
    int i, N, channel; 
    void *v; 
Placing ARGS inside the class tells the reader (and requires) that it can only be used in a restricted context.

Lined-up columns

The reader can absorb lots of class functionality when it's laid out cleanly:
class   layoutUI: public layoutui_, public plug { 
public: layoutUI(); 
  PCOPY(layoutUI); // plugin copy. 
  GFUNC(layoutUI); // declare geom   CB. 
  OFUNC(layoutUI); // declare origin CB. 
  // ...more implementation. 
}; 2017 [171108]