naming cheatsheet
1.0.0
Nommer les choses est difficile. Cette feuille tente de faciliter la tâche.
Bien que ces suggestions puissent être appliquées à n'importe quel langage de programmation, j'utiliserai JavaScript pour les illustrer dans la pratique.
Utilisez la langue anglaise lorsque vous nommez vos variables et vos fonctions.
/* Bad */
const primerNombre = 'Gustavo'
const amigos = [ 'Kate' , 'John' ]
/* Good */
const firstName = 'Gustavo'
const friends = [ 'Kate' , 'John' ]Qu'on le veuille ou non, l'anglais est la langue dominante de la programmation: la syntaxe de toutes les langues de programmation est écrite en anglais, ainsi que d'innombrables documentations et matériels éducatifs. En écrivant votre code en anglais, vous augmentez considérablement sa cohésion.
Choisissez une convention de dénomination et suivez-la. Il peut s'agir camelCase , ou snake_case , ou de toute façon, cela n'a pas d'importance. Ce qui compte, c'est qu'il reste cohérent.
/* Bad */
const pages_count = 5
const shouldUpdate = true
/* Good */
const pageCount = 5
const shouldUpdate = true
/* Good as well */
const page_count = 5
const should_update = true Un nom doit être court , intuitif et descriptif :
/* Bad */
const a = 5 // "a" could mean anything
const isPaginatable = a > 10 // "Paginatable" sounds extremely unnatural
const shouldPaginatize = a > 10 // Made up verbs are so much fun!
/* Good */
const postCount = 5
const hasPagination = postCount > 10
const shouldDisplayPagination = postCount > 10 // alternatively N'utilisez pas les contractions. Ils ne contribuent à rien d'autre que la réduction de la lisibilité du code. Trouver un court nom descriptif peut être difficile, mais la contraction n'est pas une excuse pour ne pas le faire.
/* Bad */
const onItmClk = ( ) => { }
/* Good */
const onItemClick = ( ) => { } Un nom ne doit pas dupliquer le contexte dans lequel il est défini. Supprimez toujours le contexte d'un nom si cela ne diminue pas sa lisibilité.
class MenuItem {
/* Method name duplicates the context (which is "MenuItem") */
handleMenuItemClick = ( event ) => { ... }
/* Reads nicely as `MenuItem.handleClick()` */
handleClick = ( event ) => { ... }
} Un nom doit refléter le résultat attendu.
/* Bad */
const isEnabled = itemCount > 3
return < Button disabled = { ! isEnabled } />
/* Good */
const isDisabled = itemCount <= 3
return < Button disabled = { isDisabled } />Il existe un modèle utile à suivre lors des fonctions de dénomination:
prefix? + action (A) + high context (HC) + low context? (LC)
Jetez un œil à la façon dont ce modèle peut être appliqué dans le tableau ci-dessous.
| Nom | Préfixe | Action (a) | Contexte élevé (HC) | Contexte bas (LC) |
|---|---|---|---|---|
getPost | get | Post | ||
getPostData | get | Post | Data | |
handleClickOutside | handle | Click | Outside | |
shouldDisplayMessage | should | Display | Message |
Remarque: L'ordre de contexte affecte la signification d'une variable. Par exemple,
shouldUpdateComponentsignifie que vous êtes sur le point de mettre à jour un composant, tandis queshouldComponentUpdatevous indique que le composant se mettra à jour sur lui-même, et que vous contrôlez quand il devrait être mis à jour. En d'autres termes, un contexte élevé met l'accent sur la signification d'une variable .
La partie verbe de votre nom de fonction. La partie la plus importante responsable de décrire ce que fait la fonction.
getAccède immédiatement aux données (c.-à-d. Getter des données internes).
function getFruitCount ( ) {
return this . fruits . length
}Voir aussi Compose.
set Définit une variable de manière déclarative, avec la valeur A à la valeur B .
let fruits = 0
function setFruits ( nextFruits ) {
fruits = nextFruits
}
setFruits ( 5 )
console . log ( fruits ) // 5resetDéfinit une variable à sa valeur ou à son état initial.
const initialFruits = 5
let fruits = initialFruits
setFruits ( 10 )
console . log ( fruits ) // 10
function resetFruits ( ) {
fruits = initialFruits
}
resetFruits ( )
console . log ( fruits ) // 5fetchDemande de données, ce qui prend un temps indéterminé (c.-à-d. Demande asynchrone).
function fetchPosts ( postCount ) {
return fetch ( 'https://api.dev/posts' , { ... } )
}removeSupprime quelque chose de quelque part.
Par exemple, si vous avez une collection de filtres sélectionnés sur une page de recherche, en supprimant l'un d'eux de la collection est removeFilter , pas deleteFilter (et c'est ainsi que vous le diriez naturellement en anglais également):
function removeFilter ( filterName , filters ) {
return filters . filter ( ( name ) => name !== filterName )
}
const selectedFilters = [ 'price' , 'availability' , 'size' ]
removeFilter ( 'price' , selectedFilters )Voir aussi Supprimer.
deleteEfface complètement quelque chose des domaines de l'existence.
Imaginez que vous êtes un éditeur de contenu, et il y a ce message notoire dont vous souhaitez vous débarrasser. Une fois que vous avez cliqué sur un bouton brillant "Supprimer la publication", le CMS a effectué une action deletePost , pas removePost .
function deletePost ( id ) {
return database . find ( { id } ) . delete ( )
}Voir aussi supprimer.
composeCrée de nouvelles données à partir de celle existante. Principalement applicable aux chaînes, objets ou fonctions.
function composePageUrl ( pageName , pageId ) {
return ` ${ pageName . toLowerCase ( ) } - ${ pageId } `
}Voir aussi Get.
handleGère une action. Souvent utilisé lors du nom d'une méthode de rappel.
function handleLinkClick ( ) {
console . log ( 'Clicked a link!' )
}
link . addEventListener ( 'click' , handleLinkClick ) Un domaine sur lequel une fonction fonctionne.
Une fonction est souvent une action sur quelque chose . Il est important d'indiquer quel est son domaine opérable, ou du moins un type de données attendu.
/* A pure function operating with primitives */
function filter ( predicate , list ) {
return list . filter ( predicate )
}
/* Function operating exactly on posts */
function getRecentPosts ( posts ) {
return filter ( posts , ( post ) => post . date === Date . now ( ) )
}Certaines hypothèses spécifiques à la langue peuvent permettre d'omettre le contexte. Par exemple, dans JavaScript, il est courant que
filterfonctionne sur le tableau. L'ajoutfilterArrayexplicite ne serait pas nécessaire.
-
Le préfixe améliore la signification d'une variable. Il est rarement utilisé dans les noms de fonction.
is Décrit une caractéristique ou un état du contexte actuel (généralement boolean ).
const color = 'blue'
const isBlue = color === 'blue' // characteristic
const isPresent = true // state
if ( isBlue && isPresent ) {
console . log ( 'Blue is present!' )
}has Décrit si le contexte actuel possède une certaine valeur ou état (généralement boolean ).
/* Bad */
const isProductsExist = productsCount > 0
const areProductsPresent = productsCount > 0
/* Good */
const hasProducts = productsCount > 0should Reflète une déclaration conditionnelle positive (généralement boolean ) couplée à une certaine action.
function shouldUpdateUrl ( url , expectedUrl ) {
return url !== expectedUrl
}min / maxReprésente une valeur minimale ou maximale. Utilisé lorsque vous décrivez les limites ou les limites.
/**
* Renders a random amount of posts within
* the given min/max boundaries.
*/
function renderPosts ( posts , minPosts , maxPosts ) {
return posts . slice ( 0 , randomBetween ( minPosts , maxPosts ) )
}prev / nextIndiquez l'état précédent ou suivant d'une variable dans le contexte actuel. Utilisé lors de la description des transitions d'état.
function fetchPosts ( ) {
const prevPosts = this . state . posts
const fetchedPosts = fetch ( '...' )
const nextPosts = concat ( prevPosts , fetchedPosts )
this . setState ( { posts : nextPosts } )
} Comme un préfixe, les noms de variables peuvent être rendus singuliers ou pluriels selon qu'ils détiennent une seule valeur ou plusieurs valeurs.
/* Bad */
const friends = 'Bob'
const friend = [ 'Bob' , 'Tony' , 'Tanya' ]
/* Good */
const friend = 'Bob'
const friends = [ 'Bob' , 'Tony' , 'Tanya' ]
