Project Style Guide

Version History

Version Policy

Version	Date	Description	Responsable
0.1	22/03/2017	Document creation and adaptation	Luiz Guilherme
0.2	22/03/2017	Adding React Topics	Gustavo Braz

• This is an adapted guide based on the coding standard used by Airbnb and Google Style Guide. It's utilization was adapted for utilization in the project found here. This guide can be used openly, even if is this version, an adaptation of the project cited above.

• The reading and consult of this guide can be somewhat confusing for users that are not acquainted with Java, Javascript, ReactJS, JSX and HTML/CSS. It is recommended that you study them before utilizing this guide.

• It's also recommended the utilization of the Eclipse IDE for Java development during the process of development and for ReactJS development it's recommended a text editor like Atom, Sublime or Webstorm because it is more intuitive, easy to use and well documented. As a web browser, we recommend Google Chrome.

• If you have any doubts in relation of a code pattern, utilize the search function from your browser(CTRL+F on Google Chrome) before start coding!

• Alterations can be made without previous warning.

Index

1. Basic Rules
   1. Glossary
   2. Naming
   3. Formatting
   4. Comments
   5. Programming Practices
2. Java Style Guide
   1. Java Annotations
   2. Javadoc
   3. Instructions
   4. Declarations
   5. Getters and Setters
   6. Switch Statements
3. JavaScript Style Guide
   1. Instructions
   2. Declarations
   3. Policies
   4. JSDoc
4. ReactJS Style Guide
   1. JSX
   2. Instructions
   3. Declarations
   4. Ordering
   5. Props
   6. References
5. HTML and CSS Style Guide
   1. HTML Style Rules
   2. CSS Style Rules
   3. Document Structure

Basic Rules

• Only include one React component per file.
• However, multiple Stateless, or Pure, Components are allowed per file. eslint: react/no-multi-comp.
• Always use JSX syntax.
• Do not use React.createElement unless you're initializing the app from a file that is not JSX.

Glossary

Naming

Formatting

Comments

Programming Practices

Java Style Guide

Java Annotations

Javadoc

Instructions

Declarations

Getters and Setters

Switch Statements

Javascript Style Guide

Instructions

Declarations

Policies

JSDoc

ReactJS Style Guide

JSX

Instructions

Declarations

• Do not use displayName for naming components. Instead, name the component by reference.

// bad
export default React.createClass({
  displayName: 'ReservationCard',
  // stuff goes here
});

// good
export default class ReservationCard extends React.Component {
}

Ordering

• Ordering for class extends React.Component:

1. optional static methods
2. constructor
3. getChildContext
4. componentWillMount
5. componentDidMount
6. componentWillReceiveProps
7. shouldComponentUpdate
8. componentWillUpdate
9. componentDidUpdate
10. componentWillUnmount
11. clickHandlers or eventHandlers like onClickSubmit() or onChangeDescription()
12. getter methods for render like getSelectReason() or getFooterContent()
13. optional render methods like renderNavigation() or renderProfilePicture()
14. render

• How to define propTypes, defaultProps, contextTypes, etc...

import React, { PropTypes } from 'react';

const propTypes = {
  id: PropTypes.number.isRequired,
  url: PropTypes.string.isRequired,
  text: PropTypes.string,
};

const defaultProps = {
  text: 'Hello World',
};

class Link extends React.Component {
  static methodsAreOk() {
    return true;
  }

  render() {
    return <a href={this.props.url} data-id={this.props.id}>{this.props.text}</a>
  }
}

Link.propTypes = propTypes;
Link.defaultProps = defaultProps;

export default Link;

• Ordering for React.createClass: eslint: react/sort-comp :

1. displayName
2. propTypes
3. contextTypes
4. childContextTypes
5. mixins
6. statics
7. defaultProps
8. getDefaultProps
9. getInitialState
10. getChildContext
11. componentWillMount
12. componentDidMount
13. componentWillReceiveProps
14. shouldComponentUpdate
15. componentWillUpdate
16. componentDidUpdate
17. componentWillUnmount
18. clickHandlers or eventHandlers like onClickSubmit() or onChangeDescription()
19. getter methods for render like getSelectReason() or getFooterContent()
20. optional render methods like renderNavigation() or renderProfilePicture()
21. render

Props

• Always use camelCase for prop names.

// bad
<Foo
  UserName="hello"
  phone_number={12345678}
/>

// good
<Foo
  userName="hello"
  phoneNumber={12345678}
/>

• Omit the value of the prop when it is explicitly true. eslint: react/jsx-boolean-value

// bad
<Foo
  hidden={true}
/>

// good
<Foo
  hidden
/>

• Always include an alt prop on tags. If the image is presentational, alt can be an empty string or the must have role="presentation". eslint: jsx-a11y/img-has-alt

// bad
<img src="hello.jpg" />

// good
<img src="hello.jpg" alt="Me waving hello" />

// good
<img src="hello.jpg" alt="" />

// good
<img src="hello.jpg" role="presentation" />

• Do not use words like "image", "photo", or "picture" in alt props. eslint: jsx-a11y/img-redundant-alt

Why? Screenreaders already announce img elements as images, so there is no need to include this information in the alt text.

// bad
<img src="hello.jpg" alt="Picture of me waving hello" />

// good
<img src="hello.jpg" alt="Me waving hello" />

• Use only valid, non-abstract ARIA roles. eslint: jsx-a11y/aria-role

// bad - not an ARIA role
<div role="datepicker" />

// bad - abstract ARIA role
<div role="range" />

// good
<div role="button" />

• Do not use accessKey on elements. eslint: jsx-a11y/no-access-key

Why? Inconsistencies between keyboard shortcuts and keyboard commands used by people using screenreaders and keyboards complicate accessibility.

// bad
<div accessKey="h" />

// good
<div />

• Avoid using an array index as key prop, prefer a unique ID. (why?)

// bad
{todos.map((todo, index) =>
  <Todo
    {...todo}
    key={index}
  />
)}

// good
{todos.map(todo => (
  <Todo
    {...todo}
    key={todo.id}
  />
))}

• Always define explicit defaultProps for all non-required props.

Why? propTypes are a form of documentation, and providing defaultProps means the reader of your code doesn’t have to assume as much. In addition, it can mean that your code can omit certain type checks.

// bad
function SFC({ foo, bar, children }) {
  return <div>{foo}{bar}{children}</div>;
}
SFC.propTypes = {
  foo: PropTypes.number.isRequired,
  bar: PropTypes.string,
  children: PropTypes.node,
};

// good
function SFC({ foo, bar }) {
  return <div>{foo}{bar}</div>;
}
SFC.propTypes = {
  foo: PropTypes.number.isRequired,
  bar: PropTypes.string,
  children: PropTypes.node,
};
SFC.defaultProps = {
  bar: '',
  children: null,
};

References

• Always use ref callbacks. eslint: react/no-string-refs

// bad
<Foo
  ref="myRef"
/>

// good
<Foo
  ref={(ref) => { this.myRef = ref; }}
/>

HTML and CSS Style Guide

HTML Style Rules

CSS Style Rules

Document Structure

⬆ Back to the top