normes.md

Normes

• noms de variables :
  • formatés :
    • pour les booléens, utiliser un nom qui correspond explicitement à un booléen. ex : isActive (on sait au premier coup d'oeil que la variable contient soit true soit false, pas { name: 'Bob' } ou 51
    • pour les fonctions, un verbe. ex : getFormattedItems
    • pour les listes, item + 's'. ex : users
  • compréhensibles au premier coup d'oeil.
    • la liste de noms des utilisateurs actifs => activeUserNames plutôt que names ou actives
    • pertinence par rapport au contexte. Ex : items.map(item => item.a) plutôt que items.map(x => x.a)
• fonction courtes et lisibles. Voir si on peut factoriser certains blocs de logique en plus petites fonctions. Mieux vaut 1 fonction qui en appelle 5 autres petites aux noms explicites que 1 fonction de 50 lignes dont le périmètre est flou. ex :

function submit(data) {
  loaderIsActive = true
  if (!dataIsValid(data)) { throw new Error('invalid data') }
  saveData(data)
  notify('data updated')
  loaderIsActive = false
}

• retours à la ligne :

Parfois, c'est très bien en une ligne :

userIds = users.map(user => user.id)
adminNames = ['Joe', 'Bob']
const user = new User({ autofill: true })

Parfois c'est mieux avec des alignements logiques :

const activeUserNames = users
  .filter(getIsActive)
  .map(user => 
    user.firstName[0].toUpperCase() +
    user.firstName.slice(1) +
    ' ' +
    user.lastName[0].toUpperCase()
  )

const animals = [
  'butterfly',
  'seal',
  'turtle',
  'lion',
  'monkey',
  'bat',
  'spider',
  'your mom',
  'eagle',
  'worm'
]

const user = new User({
  name: 'Bob',
  sex: 'man',
  hasJob: true,
  workDays: [
    'monday',
    'tuesday',
    'thirsday',
    'friday',
    'saturday'
  ],
  sayHi: () => console.log('hi')
})

Il s'agit de juger ce qui est le plus lisible au cas par cas : généralement en 1 ligne pour des petits bouts de codes simples, et avec des alignements pour des bouts de code plus complexes.

Un objet complexe en 1 ligne :

const user = new User({ name: 'Bob', sex: 'man', hasJob: true, workDays: ['monday', 'tuesday', 'thirsday', 'friday', 'saturday'], sayHi: () => console.log('hi')
})

serait plus lisible avec des alignements logiques.

Un objet simple aligné :

userIds = users.map(user => {
  return user.id
})

serait plus lisible en 1 ligne :

userIds = users.map(user => user.id)

• indentation :
  • chaque fois qu'on rentre dans quelque chose qui s'apparente conceptuellement à un conteneur (un truc qui contient quelque chose), on ajoute un niveau d'indentation, afin que les hiérarchies apparaissent clairement. Par exemple, lorsqu'on rentre dans une fonction, dans un if ou encore lorsqu'on chaîne des fonctions, on indente.

const human = { // on rentre dans le conteneur "human"
  mood: "happy",
  sayHi: () => { // on rentre dans le conteneur "sayHi"
    if (mood) { // on rentre dans le conteneur du if
      human.useBrain()
        .then(() => console.log("hi"))
        .catch(() => console.log("ggghgh...")
    }
  },
  useBrain: () => api.fetchBrainCells()
}

• utilisation des tabs au lieu des espaces pour indenter. tabs = plus logique puisqu'on ne doit rien écrire entre 2 espaces d'indentation, de plus les fichiers sont moins lourds qu'avec des espaces.
• factorisation : le plus possible, tant que le sous-bloc créé a un sens en lui-même. Le but est d'améliorer la lisiblité du code. Il s'agit de s'éloigner d'un mastodonte qui fait pleins de trucs et dont le périmètre est peu clair, et de se rapprocher d'entités claires, bien définies, compréhensibles, et autonomes.
• case JS : on utilise du PascalCase pour les classes et du camelCase pour tout le reste