refactoring chapter for User's Guide

[bob-carpenter]

Summary:

Add a chapter to the Stan User's Guide on refactoring programs for clarity.

Description:

We essentially want to port the non-OO parts of Martin Fowler's book, Refactoring. It's Java-based, but it gives the flavor. Sometimes, there's also an efficiency boost, but we don't want anything about efficiency to only be in the refactoring chapter given that there's an efficiency chapter.

We could also extend this to patterns and anti-patterns, though most of the guide is already about patterns.

Additional Information:

List of refactoring to add.

• [ ] collapse nested conditionals

if (a) {
  s;
} else {
  if (b) {
    t;
  } else {
    u;
  }
}

should be

if (a) {
  s;
} else if (b) {
  t;
} else if (c) {
  u;
}

• [ ] early return

real x;
if (a) {
  // some computation
  x = y1;
} else {
  // some computation
  x = y2;
}
return x;

should be

if (a) {
  // some computation
  return y1;
} else {
  // some computation
  return y2;
}

or if there is no computation

return a ? y1 : y2;

There are a lot more of these we can add, but I just wanted to provide some flavor for the issue. A PR can address this in only a few cases and we can merge it and then add to it as we go.

Current Version:

v2.18.0