suggestions_normes.md

ESLint

Linter = affiche des erreurs ou warnings lorsque certaines normes ne sont pas respectées.

Utiliser es-lint:recommended pour avoir une config de base standard.

Ajouter :

• no-unused-expressions
• no-useless-concat
• no-useless-return
• no-console (car c'est un outil de debug qui ne doit pas subsister dans les commits, au moins pas en front)
• semi: never (car les ; ne servent à rien, sauf dans de rares cas spéciaux.)
• quotes: single ou double, à déterminer, mais pas les 2

https://eslint.org/docs/rules/

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. Plutôt que 50 lignes de code, 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.

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 aligné 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.

• indentation :
  • 2 espaces systématiquement, afin que les hiérarchies apparaissent clairement
  • utilisation des tabs au lieu des espaces. tabs = plus logique puisqu'on ne doit rien écrire entre 2 espaces d'1 tab. Sur GitHub ça affiche 8 espaces pour 1 tab mais il semble que c'est modifiable si le projet contient un fichier .editorconfig (à vérifier)
• 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.
• case identique pour 1 catégorie de code. ex : classes => PascalCase, fonctions => camelCase, CQL => snake_case
• aération du code pour plus de lisibilité. Exemples :
  • let e = { a: [ 1, 2 ] }
  • if ( a && b ) { return }
  • let doThis = ( param ) => {}
  • let str = 'Hello ' + userName + ( 2 / 1 )

Comparaison pour se faire une idée :

if ( { a: [ 1, 2 ] } ) {
  return ( username ) => 'Hello ' + username
}

VS

if({a:[1,2]}){
  return (username)=>'Hello '+username
}

Ce sont des exemples d'aération, personnellement je ne les utilise pas tous mais ce serait l'occasion pour moi aussi d'améliorer mon écriture. A voir si on les utilise tous, ou si on n'en sélectionne que quelques uns.

• ne pas catch si on ne gère pas l'erreur. Sinon, au lieu d'avoir une erreur non gérée et visible, on a une erreur non gérée et invisible, donc difficile à repérer, et qui va potentiellement nous causer des problèmes plus tard. Une erreur DOIT être visible si elle n'est pas gérée. De plus, si l'erreur a un catch mais n'est pas gérée, on aura potentiellement d'autres bugs plus loin dans le code.

il faudrai des exemples précis j'ai un peu la flemme de chercher mais quelque fois les points virgules sont appreciables, mais en règle générale ce n'est pas gênant de ne pas les avoires