Style Guidelines Discussion

Development
1

I thought I’d open a thread for questions and discussion around coding style guidelines throughout the SC code base (all languages included).

There’s already quite a bit of discussion history formalized in the Coding Style Guidelines. But there are some sparse sections, and inevitably more questions will come up, so we can capture them here.

(could also/instead open an RFC as a space for discussion?)

2

In a quick search of the forum, I see one related post:
When updating documentation, should one change example code to match the style guide for code contributions?.

3

.schelp files is one area that could use more guidance.

For example, to encourage more/consistent

  1. use of the inline code:: :: modal tag within body text.
  2. inter-linking of classes. In addition to adding navigability, it adds useful visual emphasis. But how often? Link every mention of a Class? Just the first mention of a Class within a section/description?
  3. inter-linking of methods. This is super useful! (As a reminder you can link directly to methods, e.g. link::Classes/SCDoc#*indexAllDocuments::).

When formatting within method/argument descriptions:

  1. Should capitalization and punctuation be used, even for brief or one-word discriptions? (I think yes)
  2. referring to arguments names, should we prefer the strong:: :: modal tag? Alternatively, should the code:: :: tag be used? I’m in favor of strong:: :: as it’s a visual connection to the argument, which the DocRenderer renders in bold. (Helpful when e.g. an argument’s behavior depends on the state of another arg.)
  3. When referring to a Class, assuming it isn’t hyperlinked, should it be formatted as code?
    E.g. I’m making a passing reference to SinOsc in my description.
  4. Should we prefer a style of specifying argument defaults?
    E.g. amp The amplitude of the oscillator. (Def: 1)
  5. How to format references to methods (if not hyperlinking to it directly)?
    Include the prefixes denoting -instanceMethod or *classMethod?
    When including the class, separate with one or two colons?
    E.g. Complex::squared, Complex::-squared, Complex:squared, Complex:-squared ?

In most cases, especially .schelp files, the guidance will likely be “preferences”, not “rules”, but I think it helps encourage thorough documentation (e.g. documenting arg defaults).

I’m happy to move provisional decisions to the style guidelines wiki if any of the preferences gain traction.

4

This reminds me of two related style points:

  1. when referring to file extensions names, I think it’s common to use the code:: :: or teletype:: :: modal tags. Is this preferred?
  2. But does that extend to full paths? Should we have a preference?
    Have a look in lang/LangPrimSource/PyrListPrim.cpp for examples. (emphasis:: ::)
    Have a look in “lang/LangPrimSource/PyrListPrim.cpp” for examples. (quotes)
    Have a look in <lang/LangPrimSource/PyrListPrim.cpp> for examples. (carrots)
    Have a look in lang/LangPrimSource/PyrListPrim.cpp for examples. (teletype:: ::)
    Have a look in lang/LangPrimSource/PyrListPrim.cpp for examples. (no emphasis :frowning: )
5

While we’re talking about help, one thing that drives me bonkers is when a method just says “does xyz” but…

  • The method has x number of arguments. What types are they expected to be? Are there any restrictions on the values (particularly those that are not obviously guessed)?
  • The method has a return value – what type? At minimum it should say what type!

It might not always be necessary to list absolutely every argument, but IMO there are too many places in the help where you don’t understand what the method does by reading the doc, and it’s necessary to devise tests to discern the real meaning. If you have to run code to see what a method does then maybe the description isn’t quite sufficient.

Ideally anyway… It may also not always be possible to reach the ideal.

hjh

3 Likes