Nomeação: Você deve sacrificar a brevidade pela clareza?

Por exemplo, a função a seguir percorre uma matriz que contém o nome e os erros de um campo de entrada. Isso é feito verificando o nome do campo de validação e enviando as informações de erro para a matriz de campos inválidos.

É melhor ser breve e escrever o seguinte:

addInvalidField (field, message) {
  const foundField = this.invalidFields.find(value => {
    return value.name === field.name
  })
  const errors = foundField.errors
  if (!errors.some(error => error.name === message)) {
    errors.push({ name: message, message })
  }
},

Ou seja mais específico assim?

addInvalidField (validatingField, message) {
  const foundField = this.invalidFields.find(invalidField => {
    return validatingField.name === invalidField.name
  })
  if (!foundField.errors.some(foundFieldError => foundFieldError.name === message)) {
    fouldField.errors.push({ name: message, message })
  }
},

Se a brevidade pode ser sacrificada para maior clareza, deveria. Mas se a verbosidade puder ser sacrificada para maior clareza, melhor ainda.

addInvalidField (field, message) {
  const foundInvalidField = this.invalidFields.find(x => x.name === field.name)
  if (!foundInvalidField.errors.some(x => x.name === message)) {
    foundInvalidField.errors.push({ name: message, message })
  }
},

Quando uma variável vive apenas enquanto uma linha, ela pode ser muito curta. FoundInvalidFieldé usado em três linhas e é o foco deste trabalho. Merece um nome explicativo.

Como sempre, o contexto é rei.

Na verdade, sou a favor do seu primeiro exemplo de código.

É claramente aparente o que o código faz apenas lendo-o. Ao manter os nomes das variáveis ​​o menor possível, você torna o código ainda mais fácil de ler. Nomes de variáveis ​​mais descritivos seriam necessários apenas se suas funções fossem mais longas, suas variáveis ​​fossem mais numerosas e / ou as variáveis ​​fossem usadas em um escopo de código maior.

É porque você manteve suas funções breves que também pode manter breves os nomes das variáveis. Sendo todas as outras coisas iguais, menos código é sempre melhor.

Acho que concordo com o tio Bob em preferir clareza sem incorrer em verbosidade excessiva . Nos exemplos que você mostra, eu diria que a intenção do segundo é mais clara, sem incorrer em verbosidade excessiva . Além disso, seria mais fácil encontrar esse snippet específico ao pesquisar pela base de código do invalidFieldque por value.

Bem, eu estou citando o Código Limpo aqui (pule se você estiver farto da pregação do tio Bob (o que eu não sou)):

Usar nomes reveladores de intenção

É fácil dizer que os nomes devem revelar a intenção. O que queremos impressionar é que levamos a sério isso. Escolher bons nomes leva tempo, mas economiza mais do que leva. Portanto, tome cuidado com seus nomes e altere-os quando encontrar nomes melhores. Todos que lerem seu código (incluindo você) ficarão mais felizes se você ler.

Evitar Desinformação

Os programadores devem evitar deixar pistas falsas que obscurecem o significado do código. Devemos evitar palavras cujos significados entrincheirados variam de nossa

Faça distinções significativas

Os programadores criam problemas para si mesmos quando escrevem código apenas para satisfazer um compilador ou intérprete.

Usar nomes pesquisáveis

Use nomes que o ajudem a fazer um grep -iIR whateveryouaresearching . (não um Código Limpo, aqui o CC falou apenas sobre variáveis ​​de letra única).

Evite o mapeamento mental

Os leitores não precisam traduzir mentalmente seus nomes para outros nomes que já conhecem. Esse problema geralmente surge da escolha de não usar termos de domínio de problemas nem termos de domínio de solução.

Usar nomes de domínio com problemas

Quando não houver "programador-eese" para o que você está fazendo, use o nome do domínio do problema. Pelo menos o programador que mantém seu código pode perguntar a um especialista em domínio o que isso significa.

Eu sempre optaria por ser mais descritivo hoje em dia - a conclusão do código IDE significa que você não precisará escrever nomes descritivos de variáveis ​​para que eu não possa ver uma desvantagem.

Na pré-história, você tinha restrições de nomes de variáveis ​​e o uso de nomes significativos de variáveis ​​poderia incorrer em um custo mensurável (por exemplo, no BBC BASIC usando variáveis ​​estáticas inteiras A% etc. era muito mais barato do que usar um número inteiro significativo - e em um sistema com 1MHz processador, economizando alguns ciclos de relógio em um loop realmente importava)

A segunda variante parece me deixa intrigada. Quando apenas olho para a assinatura, me pergunto se o campo já é conhecido como sendo inválido. Ou será validado primeiro (como é chamado validatingField), para descobrir se é realmente inválido? Portanto, essas informações não são apenas redundantes aqui, as informações extras parecem um pouco enganadoras. Esse tipo de "clareza" não é mais claro, é o contrário.

Na verdade, quando vi sua primeira função, fiquei confusa também. Eu me perguntei por que diabos sua função apenas pega um campo, mas depois não o usa e procura por outro invalidFields? Procurar um campo parece fazer muito mais sentido quando há apenas um nome de campo, assim:

addInvalidField (fieldname, message) {
  const foundField = this.invalidFields.find(value => {
    return value.name === fieldname
  })
  const errors = foundField.errors
  if (!errors.some(error => error.name === message)) {
    errors.push({ name: message, message })
  }
}

No entanto, acho que Bob Martin provavelmente daria um passo adiante e tornaria o código mais detalhado - para maior clareza - em uma direção diferente. Uma refatoração típica ao longo das linhas do livro "Código Limpo" provavelmente se pareceria com isso:

addInvalidField (fieldname, message) {
  const foundField = findInvalidField(fieldName)
  addMessageForInvalidField(foundField,message)
}

com três funções adicionais

  findInvalidField(fieldname){
    return this.invalidFields.find(value => { return value.name === fieldname })
  }

  addMessageForInvalidField(field,message){
    const errors = field.errors
    if (!doesErrorsContain(message)) {
      errors.push({ name: message, message })
    }
  }

  doesErrorsContain(message){
     return errors.some(error => error.name === message)
  }

É discutível se vale a pena ir tão longe com o princípio da responsabilidade única. Na verdade, existem alguns prós e contras. Meu ponto de vista pessoal é que o código original é "suficientemente limpo" para a maioria dos códigos de produção, mas o refatorado é melhor.

Quando soube que tinha que adicionar algo à primeira variante para que crescesse cada vez mais, dividiria anteriormente essas funções menores, para que o código nem sequer começasse a se tornar uma bagunça.

Não existe uma resposta correta em geral na nomeação. Muitas pessoas, quando recebem exatamente o mesmo conjunto de tarefas, nomearão as funções e variáveis ​​resultantes de maneira muito diferente. É claro que você quer que outras pessoas que leem seu código entendam, mas por mais tempo nem sempre significa que algo está mais claro. Se o seu código for mais denso, será necessário, então levará mais tempo para entender que mesmo todas as linhas de suas funções são tão claras e descritivas quanto possível.

Pessoalmente, gosto mais do primeiro exemplo. É direto e direto ao ponto, mesmo com as variáveis ​​que não têm nomes descritivos como no segundo exemplo. Honestamente, os nomes das variáveis ​​no segundo exemplo não são muito mais claros do que o primeiro na minha opinião, e manter a função breve facilita a compreensão da função em si.

No final do dia, o melhor será com você e com quem você estiver trabalhando. Afinal, é quem lerá e manterá.