drazik / cozy-guidelines

Cozy Code Guidelines

Cozy Code Guidelines

Generic code style

"eslintConfig": {
    "extends": ["eslint-config-cozy-app"]
  },
  "prettier": {
    "semi": false,
    "singleQuote": true
  },

Let the formatters do their jobs.

JavaScript

Return value

Avoid using undefined and prefer returning null.

Why ? undefined is used for variable that have not been assigned yet. null is for a variable with no value. See http://www.ecma-international.org/ecma-262/6.0/#sec-undefined-value, http://www.ecma-international.org/ecma-262/6.0/#sec-null-value

Promises vs async/await

Always use async / await when applicable, instead of Promises and then() chains.

Why ? Cleaner, Clearer, more readable, easier for handling errors See https://hackernoon.com/6-reasons-why-javascripts-async-await-blows-promises-away-tutorial-c7ec10518dd9

Comments

Only comments things that have business logic complexity.

Why ? Comments are an apology, not a requirement. Good code mostly documents itself. See https://github.com/ryanmcdermott/clean-code-javascript#comments

❌ Bad :

// Initiate API UserData object, for checkFormLogin token
const req1 = await request({
  url: `https://www.deezer.com/ajax/gw-light.php?method=deezer.getUserData&input=3&api_version=1.0&api_token=&cid=`
})

✅ Good

function initiateAPIForToken () {
  return request({
    url: `https://www.deezer.com/ajax/gw-light.php?method=deezer.getUserData&input=3&api_version=1.0&api_token=&cid=`
  })
}

React

Class constructors

Avoid constructor if you can by leveraging transform-class-properties.

Why ? Less lines, easier to read, no need to call super().

❌ Bad :

class MyComponent extends Component {
  constructor () {
    super()
    this.state = { counter: 0 }
  }
}

✅ Good

class MyComponent extends Component {
  state = { counter: 0 }
}

Binding event handlers

Avoid binding event handlers in constructor, leverage transform-class-properties and arrow functions.

Why ? The transform-class-properties way makes it easy to see, when the method is defined, that it is bound to the class (whereas when using the constructor, you have to check the constructor to see if it is correctly bound).

❌ Bad :

class MyComponent extends Component {
  constructor () {
    super()
    this.onClick = this.onClick.bind(this)
  }

  onClick (ev) {
    ...
  }
}

✅ Good

class MyComponent extends Component {
  onClick = ev => {
    ...
  }
}

Code organization

Modules

Actions, reducers, and potential helpers supporting the same functionality should be regrouped in a module folder.

Why ? Action and reducers are by their very nature tightly coupled. When separated, refactoring and adding new features leads to editing of several files with tiny changes. With modules, this is simplified since changes are made in one file instead of several.

If you develop functionalities related to greetings, here is how you can structure your folders :

src
├── greetings
│   └── components
│        └── __tests__
│        └── Greeting.jsx
│    └── redux
│        └── index.js

See more

Dumb component

src/greetings/components/Greeting.jsx

export default ({ name }) => <div>Hello { name }!</div>

Redux related

src/greetings/redux/index.js

import Greeting from '../components/Greeting'

const initialState = {}

// Actions
...

// Reducers
const reducer = (state, action = {}) => state

// Connected
const mapStateToProps =  ({ name }) => name
const connect = connect(mapStateToProps)
export {
  connect,
  /* actions */
  /* reducers */
}

export default reducer

Export both dumb and connected components with the index

src/greetings/index.js

import { connect } from 'redux'
import Greeting from './Greeting'
import ConnectedGreeting from './redux'

export {
  Greeting,
  ConnectedGreeting: connect(Greeting)
}

Usage in application

import { Provider } from 'react-redux'
import { createStore } from 'redux'
import { Greeting, ConnectedGreeting, reducer } from './greetings'

const store = createStore(reducer)

const App = props => (
  <Greeting name={Jon Snow} />
  <Provider store={store}>
    <ConnectedGreeting />
  </Provider>
)

Read more : https://github.com/erikras/ducks-modular-redux

Commit messages

A git repository lives with an history that let developers or automatic procedure to find useful information.

They have to look like that:

type: Subject

optional body

footer with references to issue tracker IDS

See more

Type

One of:

• feat: a new feature
• fix: a bug fix
• docs: changes to documentation
• style: formatting, missing semi colons, etc; no code change
• refactor: refactoring production code; no behavior change
• test: adding tests, refactoring test; no production code change
• chore: updating build tasks, package manager configs, etc; no production code change

Subject

Subjects should be no greater than 50 characters

❌ Bad :

fix: When a list contains more than 50 items, the scroll is broken

✅ Good

fix: A too long list breaks the scrolling

Subjects should begin with a capital letter

❌ Bad :

fix: a too long list breaks the scrolling

✅ Good

fix: A too long list breaks the scrolling

Subjects do not end with a period.

❌ Bad :

fix: A too long list breaks the scrolling.

✅ Good

fix: A too long list breaks the scrolling

Use an imperative tone to describe what a commit does, rather than what it did

❌ Bad :

fix: A List that were too large would break the scroll.

✅ Good

fix: A too long list breaks the scrolling

Body

Not all commits are complex enough to warrant a body, therefore it is optional and only used when a commit requires a bit of explanation and context. Use the body to explain the what and why of a commit, not the how.

When writing a body, the blank line between the title and the body is required and you should limit the length of each line to no more than 72 characters.

Footer

The footer is optional and is used to reference issue tracker IDs.

Example

feat: Summarize changes in around 50 characters or less

More detailed explanatory text, if necessary. Wrap it to about 72
characters or so. In some contexts, the first line is treated as the
subject of the commit and the rest of the text as the body. The
blank line separating the summary from the body is critical (unless
you omit the body entirely); various tools like `log`, `shortlog`
and `rebase` can get confused if you run the two together.

Explain the problem that this commit is solving. Focus on why you
are making this change as opposed to how (the code explains that).
Are there side effects or other unintuitive consequenses of this
change? Here's the place to explain them.

Further paragraphs come after blank lines.

 - Bullet points are okay, too

 - Typically a hyphen or asterisk is used for the bullet, preceded
   by a single space, with blank lines in between, but conventions
   vary here

If you use an issue tracker, put references to them at the bottom,
like this:

Resolves: #123
See also: #456, #789

Cozy Logo

What is Cozy?

Cozy is a platform that brings all your web services in the same private space. With it, your web apps and your devices can share data easily, providing you with a new experience. You can install Cozy on your own hardware where no one profiles you.

Community

You can reach the Cozy Community by:

• Chatting with us on IRC #cozycloud on irc.freenode.net
• Posting on our Forum
• Posting issues on the Github repos
• Mentioning us on Twitter