diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ad8be6efd..dcba8f8ee 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -62,6 +62,10 @@ Before new components and patterns are published into the design system, the tea | [Tested](#tested) | It’s been tested and shown to work with a range of browsers, assistive technologies and devices. | | [Considered](#considered) | Documentation and rationale have been provided. | +When making a new component, we would be very grateful if you post the research, design decisions and use cases for the component. Accessibility considerations should be documented or sourced from the [community forum](https://community.digital.gov.au/c/designsystem) before submitting a pull request. + +This may be in the form of a code snippet, screenshots, sketch files or written text on your research with references. This gives a chance for members of the community to respond and share any work they may have done in the past on a similar component. + ------------------------------------------------------------------------------------------------- ### Useful @@ -164,6 +168,80 @@ Provide rationale; the more the better. We aim to explain design and code decisi ------------------------------------------------------------------------------------------------- +### Code Standard + +As mentioned previously, we try to make our code very easy to understand and readable for the human user. Here are some do's and don'ts + +#### Describe the function + +Make sure to include function and parameter definitions where appropriate. The name of the function should help make clear the intention of the function. This standard applies for any SASS, JS, JQuery or React JS functions. We adhere to [JSDoc](http://usejsdoc.org/about-getting-started.html) styling + +Don't: + +```js +function CalculateSpecs(initialSize,endSize,speed){ + ... +} +``` + +Do + +```js +* @param {integer} initialSize - The initial size of the element to animate +* @param {integer} endSize - The size the element after the animation completes +* @param {string} speed - The speed of the animation in ms +* +* @return {object} - Required steps, stepSize and intervalTime for the animation +*/ +function CalculateAnimationSpecs( initialSize, endSize, speed ) { + ... +} + +``` + +#### Space out the code + +Add space when there is code between round, square or curly brackets. + +Don't: + +```scss +$isBlackBgContrast:AU-color-contrast(#000,$background,true,false)>=$ratio; + +``` + +Do: + +```scss +$isBlackBgContrast: AU-color-contrast( #000, $background, true, false ) >= $ratio; +``` + +#### Use new lines +When HTML or React tags have several attributes (or props), it can be easier to separate these onto a new line. + +Don't: + +```jsx +
+``` + +Do: +```jsx +
+``` + +**[⬆ back to top](#contents)** + + +------------------------------------------------------------------------------------------------- ## Reporting Bugs, Asking Questions, Sending Suggestions