index

means: names

Ten or fifteen minutes spent coming up with exactly the right name for a function is time well spent.

[ hqse, p.42]

Getting the right name is a big part of the work.

A good name is descriptive but not too long. It's distinctive but also a reasonable English word for the item. Ideally it has natural abbreviations for local variables.

The ideal of self documenting code can lead to extremely long names:

It's understandable, but should be resisted. Think hard about a shorter name that says the same thing. It will pay off over time.

prefixes

2 to 4 letters, for example:

GL //openGL.org 
FL //fltk.org, Fast lightweight toolkit 
glm //glm.org, math library 
std //<a <a href="../ref/stl.html">stl</a>>standard template library</a>. 

boo:: // boost? or 
bst:: // boost? unsure.

functions

A felicitous combination of abbreviations and conventions is the translator pattern:

doub       i2x( int); // iterator to spatial coordinate. 
doub dist2time(doub); // distance to time translation. 
doub val2alf  (doub); // function value to alpha channel.

Keep accessors brief where possible:

inline void w(int X) {w_=X; inval();} // set, invalidate. 
inline void h(int X) {h_=X; inval();} 
inline int  w()      {return w_;}     // get. 
inline int  h()      {return h_;}

otherwise prefixed:

void   setMarks(cchar*); // Set metadata from string. 
string getMarks();       // Return metadata as string.

classes

The right name is half the work of factoring.

This is worth spending time thinking about, especially if you plan to be stuck with it for a while. It's a chance to think about what you really want to end up with.

#undef  NWID //####################################################### 
#define NWID                                                    "Path" 
struct PathItem { 
  PathItem() {init();} 
  void mix(const PathItem&, const PathItem&, doub); 
  void init(); 
}; 

class   PathHeader { 
public: PathHeader(): version_(1), fps_(6) {} 
  inline int version() const {return version_;} 
protected: 
  int version_; 
  int fps_; // path granularity, frames per second. 
}; 

class   Path: public PathHeader { 
public: Path() {path_.resize(1);} 
  PathItem before(doub) const; // extrapolate for t > tMax. 
  PathItem  after(doub) const; // extrapolate for t < tMin. 
  inline PathItem &item(int i) {return path_[i];} // actual nth item. 
  inline int  size() const {return path_.size();} 
  inline int  fps()  const {return fps_;} 
  inline void fps(int X) {fps_ = X; inval();} 
  static void save(Path*, cchar*); 
  static void load(Path*, cchar*); 
  void inval() {path_.resize(0);} 
private: 
  vector<PathItem> path_; 
};

nedwaves.com 2017 [171108]