From 96bcf2a9162646dca8ff48f3c6da4ff12cf36768 Mon Sep 17 00:00:00 2001 From: Laila Los <44241786+ElectronicBlueberry@users.noreply.github.com> Date: Thu, 8 Dec 2022 14:13:23 +0100 Subject: [PATCH 1/9] fix typo --- client/docs/composables.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/client/docs/composables.md b/client/docs/composables.md index 2ba75d898fc..a7a22b5c6d3 100644 --- a/client/docs/composables.md +++ b/client/docs/composables.md @@ -87,7 +87,7 @@ While simpler in this example, you may need to manually mock more return values ## Using Composables for more than Stores -Composables can be of great use to extract any reactive code from your components. For an example of this, take a look at [userFilterObjectArray](https://github.com/galaxyproject/galaxy/blob/dev/client/src/composables/utils/filter.js). +Composables can be of great use to extract any reactive code from your components. For an example of this, take a look at [useFilterObjectArray](https://github.com/galaxyproject/galaxy/blob/dev/client/src/composables/utils/filter.js). Usage: From 97630b6796d432a47c16021cc85d5204d6e002e1 Mon Sep 17 00:00:00 2001 From: Laila Los <44241786+ElectronicBlueberry@users.noreply.github.com> Date: Thu, 8 Dec 2022 16:24:21 +0100 Subject: [PATCH 2/9] write styleguide --- client/docs/styleguide.md | 421 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 421 insertions(+) create mode 100644 client/docs/styleguide.md diff --git a/client/docs/styleguide.md b/client/docs/styleguide.md new file mode 100644 index 00000000000..7a25fcf8320 --- /dev/null +++ b/client/docs/styleguide.md @@ -0,0 +1,421 @@ +# Styleguide + +Most of the clients code style is handled by prettier. Prettier does a good job of keeping an overall consistent code style, however there are some cases it can not account for. +This document serves as a guide on how to style your code in such cases, with explanations as to why. +Treat it more like a set of recommendations, than hard rules. + +## Naming + +Do not abbreviate. This includes naming `variables`, `functions` and `modules`. + +> **Do** +> +> ```js +> function errorMessageTemplate(workflowfName, errorMessage) { +> return `Failed to run ${workflowfName}. ${errorMessage}`; +> } +> ``` +> +> **Don't** +> +> ```js +> function eMsgTmpl(wfName, msg) { +> return `Failed to run ${wfName}. ${msg}`; +> } +> ``` + +> **Reason** +> +> While abbreviation may save you a few keystrokes now, it will make the code harder to understand, and therefore maintain. Even when you think the abbreviations are obvious within this context, consider people looking at your code in the future might not be in the same context at the moment you are in right now. + +## Functions + +There are several ways to define functions in JavaScript. + +```js +// function keyword +function myFunction(param) { + // do stuff +} + +// arrow functions +const myFunction = (param) => { + // do stuff +}; + +// anonymous functions +const myFunction = function(param) { + //do stuff +}; +``` + +Only use the first two. +`anonymous functions` have mostly been superseded by `arrow functions` + +### When to use the function keyword + +Use the function keyword in the top-level module scope and to declare class methods. + +> **Reason** +> +> `function` is easy to process and understand at a glance. In module scope, arrow functions offer no benefit over regular functions, and they are not allowed as class methods. + +### When to use arrow functions + +Use arrow functions when declaring temporary functions within other scopes. This can be within another function, or inside a method that expects a callback function (eg. `array.forEach()`). + +> **Reason** +> +> Arrow functions offer benefits about the ambiguity of the `this` keyword within other scopes, as they do not provide their own `this` context. +> +> Binding them to a variable, also makes it clear that this function only exists within said scope, just like any other scoped variable. + +### When to use anonymous functions + +When possible, use arrow functions instead. + +> **Do** +> +> ```js +> // in myModules.js +> +> export function myFunction(parameter) { +> const addOne = (value) => { +> return value + 1; +> } +> // do more stuff... +> } +> +> ``` +> +> **Don't** +> +> ```js +> // in myModules.js +> +> export const myFunction = (parameter) => { +> const addOne = function(value) { +> return value + 1; +> } +> // do more stuff... +> } +> +> ``` + +## HTML Multi-Line Layout + +Prettier tires to respect whitespace when formatting your HTML templates, even when it doesn't need to. So for example this code: + +```vue +A very Long Button Text +``` + +Might get turned into: + +```vue +A very Long Button Text +``` + +Notice the strange positioning of the `>` brackets. + +In the case of the button, this formatting is equivalent to the much more readable: + +```vue + + A very Long Button Text + +``` + +Prettier does not know if our element has significant whitespace, or not. Check if your element has significant whitespace, and if it does not, reformat the HTML to avoid disjointed brackets. + +[Further reading about significant whitespace](https://developer.mozilla.org/en-US/docs/Web/API/Document_Object_Model/Whitespace) + +## Spacing + +Prettier adds no empty newlines into your code, but they can help in making it more readable. + +### Vue Components + +Add spaces between the `script`, `template` and `style` blocks. + +> **Do** +> +> ```vue +> > >