[Documentation]: Extend the Standard Module Style guide for other decisions we've made

[lydia-duncan]

Michael pointed out that the policy of "use x as a general formal name", while agreed upon as a team, was not documented in the Standard Module Style guide. Having all of the decisions we made as part of the 2.0 push documented in the guide would make it easier to continue to follow them when adding or stabilizing new modules, saving us developer time and effort overall.

In talking about this with the User Support and Stabilization subteam, we thought of a few other things that were missing, though making this update would probably benefit from looking back through the related notes we made over the last couple of years.

Looking through all the old notes sounds like a lot of work, but would be more reliable than trying to notice things that are missing without prompting

Cases to document, or at least get a sense for how to document:

• formal names
  • [x] especially using x for general formals instead of a name that encodes the type into it
  • [ ] using arr for formals that are always expected to be arrays? (this may be an unwritten rule rather than something we formalized as a team, bears investigation)
• [ ] variable names
• [ ] upper-casing arrays in certain situations?
• [x] functions that return should document their return type, at least using a :returns: tag but when possible also in the function declaration (return types that vary are the main exception to when it is appropriate to list the return type in the function declaration. Such functions really should use the documentation tag)
• [x] throwing versus halting decision
  • Sometimes have a halt controlled by a flag, --no-div-by-zero-checks
  • Sometimes throw
  • Generally prefer library functions to throw rather than halt, with the exception being cases where error handling would be burdensome or out of step with other behavior (division by zero, out of memory, etc)

Note: this relates to Cray/chapel-private#6335, which talks about strategy in additional detail

[damianmoz]

A name with arr in it makes no sense. Capitalizing an array name might. Mind you, both are again encoding type information into the name The name should match the algebra, e.g.

A x = b
L x = y
A = U S trn(V)
s = D e
K = int(egral) trn(B) D B dV // a summation
M a + C v + K x = F(t)
x' = H(r, s, t) x

While some of the above won't occur in a Chapel standard module, argument names are often contextual. You want naming conventions which resonate with a user.

Also, to many users over the last few decades, passing an argument called x to a routine returning complex would normally mean one is passing a real number. Trying to use an argument x to be a complex number is the source of many, many bugs and hours of frustration.

After a few years of working with imag(w) numbers, I am still at a loss as to how to name them. I sometimes use u or v but it is not intuitive to people. The only thing which resonates with people is that a a number like

y i  // or  i y

is an imaginary number, or a purely imaginary number, depending on where one went to school/university.

[lydia-duncan]

I wasn't finding any discussion about the unchecked boxes, so I'm leaving them unresolved for now. If we have discussion in favor of them, we can add them to the module documentation then