diff --git a/docs/Style-Guide.md b/docs/Style-Guide.md index a84a067ede..8b0930930f 100644 --- a/docs/Style-Guide.md +++ b/docs/Style-Guide.md @@ -5,6 +5,7 @@ Please read all the sections below before writing a single line of code. - **[JavaScript Style Guide](#javascript-style-guide)** - **[Vue.js Style Guide](#vuejs-style-guide)** - **[CSS Style Guide](#css-style-guide)** +- **[User-facing Strings Guide](#user-facing-strings-guide)** - **[Accessibility Style Guide](#css-style-guide)** - **[Testing Style Guide](#testing-style-guide)** - **[Folder Structure Style Guide](#folder-structure-style-guide)** @@ -20,11 +21,14 @@ If you notice any file not properly linted by `standard`, this means there's a b _It is still on you to ensure your code conforms to the `standard` spec, whether or not the linter catches everything._ -### A Note On Classes: Avoid Them +### A Note On Classes: Avoid Them, Usually For this project we've made the very conscious decision to avoid Object Oriented Programming (OOP) as much as possible. Instead, we use [Selector-based Programming (SBP)](#sbp). What this means in practice is that where you'd normally see classes being used, we ask that you use SBP namespaces instead. We do this to avoid many of the pitfalls of OOP, and as a result our code ends up much simpler and more flexible than it otherwise would be. -You may of course use any necessary classes that others have created if it is unavoidable (for example, some of the built-in Node.js classes). However, avoid creating your own class definitions. In the entire project there is only a single class that we have declared that acts as an exception to this rule, and that is `GIMessage`. If there is no way to avoid creating a class definition, it may be permitted, but a strong case must be made first that there is no other way to do it. +You may of course use any necessary classes that others have created if it is unavoidable (for example, some of the built-in Node.js classes). However, avoid creating your own class definitions unless it makes sense when dealing with special types. Here are some examples of exceptions to the "avoid classes" rule: + +- `GIMessage`. This is an example of a very important type for wrapping and handling [`SPMessage`](https://shelterprotocol.net/en/spmessage/) types. +- `GIErrorUIRuntimeError`. A special error type for dealing with exceptions containing user-facing error strings when attempting to perform an action. ### See Also: "Embrace the SBP way of doing things" @@ -68,6 +72,35 @@ When writing the markup make sure its semantics are complete. For example, if th