naming cheatsheet
1.0.0
Nomear as coisas é difícil. Esta folha tenta facilitar.
Embora essas sugestões possam ser aplicadas a qualquer linguagem de programação, usarei o JavaScript para ilustrá -las na prática.
Use o idioma inglês ao nomear suas variáveis e funções.
/* Bad */
const primerNombre = 'Gustavo'
const amigos = [ 'Kate' , 'John' ]
/* Good */
const firstName = 'Gustavo'
const friends = [ 'Kate' , 'John' ]Goste ou não, o inglês é a linguagem dominante na programação: a sintaxe de todas as linguagens de programação está escrita em inglês, além de inúmeras documentações e materiais educacionais. Ao escrever seu código em inglês, você aumenta drasticamente sua coesão.
Escolha uma convenção de nomenclatura e siga -a. Pode ser camelCase , ou snake_case , ou de qualquer maneira, não importa. O que importa é que ele permaneça consistente.
/* 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 Um nome deve ser curto , intuitivo e descritivo :
/* 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ão use contrações. Eles contribuem para nada além de diminuição da legibilidade do código. Encontrar um nome breve e descritivo pode ser difícil, mas a contração não é uma desculpa para não fazê -lo.
/* Bad */
const onItmClk = ( ) => { }
/* Good */
const onItemClick = ( ) => { } Um nome não deve duplicar o contexto em que é definido. Sempre remova o contexto de um nome se isso não diminuir sua legibilidade.
class MenuItem {
/* Method name duplicates the context (which is "MenuItem") */
handleMenuItemClick = ( event ) => { ... }
/* Reads nicely as `MenuItem.handleClick()` */
handleClick = ( event ) => { ... }
} Um nome deve refletir o resultado esperado.
/* Bad */
const isEnabled = itemCount > 3
return < Button disabled = { ! isEnabled } />
/* Good */
const isDisabled = itemCount <= 3
return < Button disabled = { isDisabled } />Há um padrão útil a seguir ao nomear funções:
prefix? + action (A) + high context (HC) + low context? (LC)
Dê uma olhada em como esse padrão pode ser aplicado na tabela abaixo.
| Nome | Prefixo | Ação (a) | Alto contexto (HC) | Contexto baixo (LC) |
|---|---|---|---|---|
getPost | get | Post | ||
getPostData | get | Post | Data | |
handleClickOutside | handle | Click | Outside | |
shouldDisplayMessage | should | Display | Message |
Nota: A ordem do contexto afeta o significado de uma variável. Por exemplo,
shouldUpdateComponentque você esteja prestes a atualizar um componente, enquantoshouldComponentUpdateindica que o componente se atualizará em si mesmo e você está, mas controlando quando deve ser atualizado. Em outras palavras, o alto contexto enfatiza o significado de uma variável .
A parte verbal do seu nome de função. A parte mais importante responsável por descrever o que a função faz .
getAcesse dados imediatamente (ou seja, um getter de dados internos).
function getFruitCount ( ) {
return this . fruits . length
}Veja também compor.
set Define uma variável de maneira declarativa, com o valor A para o valor B .
let fruits = 0
function setFruits ( nextFruits ) {
fruits = nextFruits
}
setFruits ( 5 )
console . log ( fruits ) // 5resetDefine uma variável de volta ao seu valor ou estado inicial.
const initialFruits = 5
let fruits = initialFruits
setFruits ( 10 )
console . log ( fruits ) // 10
function resetFruits ( ) {
fruits = initialFruits
}
resetFruits ( )
console . log ( fruits ) // 5fetchSolicitação de alguns dados, que leva algum tempo indeterminado (ou seja, solicitação assíncrona).
function fetchPosts ( postCount ) {
return fetch ( 'https://api.dev/posts' , { ... } )
}removeRemove algo de algum lugar.
Por exemplo, se você tiver uma coleção de filtros selecionados em uma página de pesquisa, remover um deles da coleção é removeFilter , não deleteFilter (e é assim que você naturalmente o diria em inglês):
function removeFilter ( filterName , filters ) {
return filters . filter ( ( name ) => name !== filterName )
}
const selectedFilters = [ 'price' , 'availability' , 'size' ]
removeFilter ( 'price' , selectedFilters )Veja também Excluir.
deleteApaga completamente algo dos reinos da existência.
Imagine que você é um editor de conteúdo, e há aquele post notório do qual deseja se livrar. Depois de clicar em um botão brilhante "Excluir post", o CMS executou uma ação deletePost , não removePost .
function deletePost ( id ) {
return database . find ( { id } ) . delete ( )
}Veja também Remover.
composeCria novos dados do existente. Aplicável principalmente a cordas, objetos ou funções.
function composePageUrl ( pageName , pageId ) {
return ` ${ pageName . toLowerCase ( ) } - ${ pageId } `
}Veja também Get.
handleLida com uma ação. Frequentemente usado ao nomear um método de retorno de chamada.
function handleLinkClick ( ) {
console . log ( 'Clicked a link!' )
}
link . addEventListener ( 'click' , handleLinkClick ) Um domínio em que uma função opera.
Uma função geralmente é uma ação sobre algo . É importante declarar qual é o seu domínio operável, ou pelo menos um tipo de dados esperado.
/* 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 ( ) )
}Algumas suposições específicas de linguagem podem permitir omitir o contexto. Por exemplo, no JavaScript, é comum que
filteropere na matriz. AdicionarfilterArrayexplícito seria desnecessário.
-
O prefixo aprimora o significado de uma variável. Raramente é usado em nomes de funções.
is Descreve uma característica ou estado do contexto atual (geralmente boolean ).
const color = 'blue'
const isBlue = color === 'blue' // characteristic
const isPresent = true // state
if ( isBlue && isPresent ) {
console . log ( 'Blue is present!' )
}has Descreve se o contexto atual possui um determinado valor ou estado (geralmente boolean ).
/* Bad */
const isProductsExist = productsCount > 0
const areProductsPresent = productsCount > 0
/* Good */
const hasProducts = productsCount > 0should Reflete uma declaração condicional positiva (geralmente boolean ) juntamente com uma certa ação.
function shouldUpdateUrl ( url , expectedUrl ) {
return url !== expectedUrl
}min / maxRepresenta um valor mínimo ou máximo. Usado ao descrever limites ou 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 / nextIndique o estado anterior ou o próximo estado de uma variável no contexto atual. Usado ao descrever transições de estado.
function fetchPosts ( ) {
const prevPosts = this . state . posts
const fetchedPosts = fetch ( '...' )
const nextPosts = concat ( prevPosts , fetchedPosts )
this . setState ( { posts : nextPosts } )
} Como um prefixo, os nomes de variáveis podem ser feitos singulares ou plurais, dependendo se eles mantêm um único valor ou vários valores.
/* Bad */
const friends = 'Bob'
const friend = [ 'Bob' , 'Tony' , 'Tanya' ]
/* Good */
const friend = 'Bob'
const friends = [ 'Bob' , 'Tony' , 'Tanya' ]
