When updating documentation, should one change example code to match the style guide for code contributions?

Of course the point of some of the documentation is to highlight the syntactic options/differences, but outside of those case, i.e. in “run of the mill” examples, should the documentation (try to) use the style guidelines for contributions to SC itself (i.e. applying to classlib etc.)?

The actual style section on help contributions doesn’t say anything about that.

Plenty of examples in the help files use different styles than that suggested in the code-contribution guidelines. Now, I’m not saying one should go on a crusade and change all of them in short period, but when updating some help file, should one defer to the file’s “local style” or use the one for code from the guidelines?

For example, https://doc.sccode.org/Reference/Partial-Application.html doesn’t use an opening space in the functions, but only trailing one i.e. writes {|x| x }, although it does this consistently through the file. (The guidelines recommend writing { |x| x } with a leading space as well.) Similarly, the list comprehension help file mostly doesn’t use space around binary operators, or after comma in arrays, having a “file style” of its own too in that regard.

So if I were to add a new example in those files, should I defer to the “local file style” or use guideline style? And in the latter case, should I e.g. also change the style of the existing examples there? (In that case the updating not being much work, but possibly generating a lot more diff-changes than otherwise would be.)

My opinion is: If you have time and feel like it, it wouldn’t hurt to put style corrections into a separate commit from the substantial changes, but in the same PR.

I’d defer to others if they disagree, though.


1 Like