Como nomear uma variável quando a palavra é um substantivo e um verbo

48

Encontrei um problema de esquina com a orientação geral de:

  • substantivos para variáveis
  • verbos para funções

Especificamente, tenho um caso em que a palavra é ambígua - pode ser um verbo ou um substantivo. E, em alguns casos, quando estamos discutindo o aplicativo, ele será usado nos dois sentidos na mesma frase.

Minha intenção é garantir que o programa permaneça legível para futuros desenvolvedores e para mim quando voltar às seções do código meses depois.

Um dos exemplos é com a battery. A batterytem um chargee você também pode ter charge()uma bateria.

Eu acho que ter os dois Battery.Chargee Battery.Charge(value)será confuso para futuros desenvolvedores.

Minha solução atual é simplesmente escolher uma palavra diferente para um ou ambos os casos (a variável e a função). Meu problema com essa abordagem é a Batteryvariável e a função do objeto, pois chargenão se alinhará às discussões de design envolvendo o Battery.

Minha pergunta é se existe outra / melhor maneira de lidar com esse conflito na convenção de nomenclatura?


Algumas leituras adicionais sobre o assunto. Ninguém realmente abordou o particular da minha pergunta.

Comunidade
fonte
3
tornar a função de carregamento addCharge fácil e clara o suficiente
ratchet freak
2
Você poderia prefixar a variável substantiva com "Atual-"? Então, "CurrentCharge" vs "Charge ()"?
Brian Neve
6
ou apenas ChargeLevel para obter a corrente de carga
aberração catraca
5
Faça uma palavra. O WordNet não pensa que enqueueé uma palavra, mas é um verbo em Java. Que tal doCharge? Ele ainda vai falhar teste de simetria porque seus outros métodos não terá este prefixo
Variable Miserable
5
"Atual" = agora, ou "atual" = fluxo de carga. A única solução real é substituir o inglês por um idioma mais sensato!
precisa saber é o seguinte

Respostas:

38

Em situações semelhantes, tento encontrar sinônimos. Nesse caso, eu usaria "recarga" para o verbo. O "re" é um pouco redundante, mas o significado é claro. O uso da "carga" simples para a carga restante na bateria é ambíguo porque não especifica nenhuma unidade física. Eu preferiria "availableAmpHours", "hoursUntilRecharge" ou algo semelhante. As unidades dependerão do que for conveniente para a aplicação.

Minha preferência pessoal é usar verbos apenas para funções que mudam de estado. Uso substantivos para funções não mutantes. Suponho que depende do seu ponto de vista. No nível da máquina, funções não mutantes fazem alguma coisa, mas no nível do modelo, elas não fazem.

Kevin Cline
fonte
2
Excelente ponto nas unidades. As unidades são explicitamente deixadas de fora nesse caso, pois podem mudar dependendo da análise que estamos executando. Ou seja, estamos usando diferentes escalas de tempo e a Bateria ajusta suas operações em termos da escala da análise.
11
Prefiro verbos para funções caras e não mutantes. Por exemplo, funções que executam uma consulta em um banco de dados.
22713 Brian As
20

Apenas divulgando isso, mas talvez a solução para essa instância de nomeação de ambiguidade seja remover completamente essa funcionalidade da bateria. Eu nunca vi uma bateria com carregamento automático e faria mais sentido para mim ter uma classe BatteryCharger. Isso ajudaria a manter suas preocupações mais dissociadas e tornar a ação mais explícita.

battery.Charge(50) vs batteryCharger.Charge(battery, 50)

Para mim, o segundo formulário é muito mais compreensível e mantém todo o seu código de "Carregamento" em um só lugar, em vez de espalhá-lo por todas as classes de bateria.

mortalapeman
fonte
6
Não é um pensamento ruim, mas neste caso Batteryé uma abstração para o sistema de carregamento da bateria +. Nosso aplicativo não exige que os dois aspectos sejam divididos em objetos separados; portanto, eles são agrupados em um (aka Battery) por conveniência. Por fim, a física de uma bateria recarregável determina que ela tenha algum tipo de função para aceitar uma carga.
Nesse caso, afirmo que a resposta de Kevin Cline é o que você está procurando. Para maior clareza, eu usaria Recharge and Discharge para as funções de mutação e Charge para o nome da propriedade. Talvez o ChargePercent também fosse bom.
mortalapeman
Você é talvez um programador Java? Isso é claramente uma violação de Não se repita. De fato, você está repetindo TUDO, exceto o parâmetro "50". Eu não poderia ter um exemplo pior de uma violação DRY se tentasse.
encaixotado
@ boxed Você está aceitando meu exemplo? Porque não tenho certeza de como você pode alegar que estou violando o DRY quando não tenho implementação. Sou um grande defensor dos princípios do SOLID e simplesmente não estou vendo como você chegou a essa conclusão.
mortalapeman
Você está violando o DRY criando uma classe BatteryCharger desnecessária que, de alguma forma, causará uma alteração de estado na bateria. Portanto, o BatteryCharger aceita algumas entradas que serão repassadas imediatamente para a bateria.
precisa
9

Evite significados duplos

Você selecionou deliberadamente uma palavra que tem mais de um significado e essa primeira decisão é o problema. Há muitas palavras problemáticas para os programadores. Outro exemplo seria phone. Você pode phonealguém, ou você pode ter um phoneno seu bolso.

Use Getters e Setters

A nomeação padrão para a maioria dos objetos são os métodos getters / settings para propriedades.

Battery.Charge            // would be a property
Battery.setCharge(value)  // would set the property
Battery.getCharge()       // would get the property

Propriedades são estados não substantivos

Eu acho que você está enganado ao classificar propriedades de objetos como substantivos, e variáveis ​​também podem ser pensadas em estados. São estados relevantes para o escopo local de sua existência.

Você pode descrever o valor que eles possuem como substantivo, mas não tenho certeza se isso é verdade em todos os casos.

Na terminologia OOP, as propriedades do objeto descrevem o estado desse objeto. No seu caso, Batteryé um objeto e Chargeé um estado. Portanto, isso seria uma propriedade do objeto, mas isso depende do contexto de como ele é usado.

Se você precisa ser capaz de Chargecarregar a bateria e também saber o que é atual Charge, então você tem um problema.

Usando o escopo para aplicar o contexto

Contexto é o que esclarecerá qual significado de uma palavra você pretende que um método ou propriedade transmita. O escopo é definir a acessibilidade de uma propriedade / método de fora do objeto.

Batter._charge            // a hidden private property
Battery.setCharge(value)  // would set the private property
Battery.getCharge()       // would get the private property
Battery.Charge()          // would perform the Charge action

Métodos são verbos

Você pode descrever o método de um objeto como um verbo, mas a palavra ação é mais adequada. Na terminologia OOP, você executa ações em objetos usando seus métodos. É uma má forma modificar a propriedade de um objeto de fora do objeto. É preferível chamar um método que execute as ações necessárias que fazem com que seu estado mude.

A palavra Chargeé um verbo, mas também é um substantivo. Quando usado para chamar o método de uma ação, fica claro que o verbo está sendo usado Battery.Charge(....).

Mas, o contexto é muito importante. Embora a palavra Charge()seja um verbo, não é tão significativa quanto startCharging().

Os métodos válidos para Batterypoderiam incluir Charging, Discharging, setCharge, getCharge, hasCharge, Dischargee Charged.

Métodos simples de uma palavra geralmente não explicitam claramente suas ações, mas existem alguns casos como opene closeonde pouca explicação é necessária.

Portanto, não há realmente uma resposta correta sobre como nomear esses tipos de propriedades / métodos. Exceto que você precisa usar as técnicas acima com sabedoria para garantir que não haja confusão.

Reactgular
fonte
2
Para o registro, o cliente é quem está usando a terminologia ambígua. Eu não criei essa bagunça. :-) Eu levantei a questão, pois pensei que talvez não fosse a única pessoa que passava por essa situação. Você tem alguns pontos válidos na sua resposta. Neste caso particular, nós não estamos trabalhando na granularidade de tempo que StartCharge()e EndCharge()implicaria. De fato, essa terminologia acrescentaria uma sobrecarga significativa ao manuseio do sistema de bateria. A cada intervalo, ele pode Charge()ou Discharge().
11
O principal problema é manter a semântica da programação interna sincronizada com a terminologia que o cliente está usando. Chargepassa a ser a palavra ambígua mais facilmente compreendida para esse domínio. Existem vários outros.
6

Anexe-os com verbos que os tornarão um verbo ou um substantivo.

Battery.doCharge()

Battery.getCharge()
Jürgen Paul
fonte
4

Para o caso do verbo, acho que Chargeestá bem. Para o caso substantivo, getCurrentChargeLevelfuncionaria para você?

FrustratedWithFormsDesigner
fonte
Não tenho certeza disso. Como estamos usando C #, podemos declarar o get e o conjunto na propriedade em vez de precisar de funções separadas. Independentemente disso, estou preocupado com a manutenção e como ela ficará depois de esquecer o que escrevi. getCurrentChargeLevel()Ainda não precisaria se referir a uma variável interna de Battery, e qual seria o nome dessa variável?
é cobrar uma voltagem ou uma porcentagem?
mhoran_psprep
11
@ GlenH7: Ah, entendo. Você não especificou C # e meu cérebro está no modo Java. Bem, de qualquer maneira, acho que, para o substantivo que representa a quantidade de carga atualmente na bateria, algo como esse Battery.currentChargeLevelpode funcionar. Você pode tentar usar Battery.coloumbsou Battery.ampereHoursmas que pode não ser tão óbvio ...
FrustratedWithFormsDesigner
11
@mhoran_psprep - nem. ;-) Chargeé o Energyque é Power(Volts * Amperes == Watts) multiplicado pelo tempo. Portanto, neste caso, a cobrança é um número. Há também um estado de carga que passa a ser um percentual.
@FrustratedWithFormsDesigner - sim, deixei o C # de fora, pois achei que o caso de canto mais amplo era aplicável independentemente do idioma. Watt*timedefinitivamente não se alinharia com as conversas de design, mas ChargeLevelsim.
0

Na maioria dos casos, adicionar um verbo auxiliar, advérbio ou adjetivo é bom o suficiente para distingui-los e pode realmente ajudar na compreensão. Com o seu caso de Carga e Carga () em uma bateria, o DeltaCharge () pode mostrar que é uma função que pode lidar com carga ou descarga.

Delta (nos casos em que há uma alteração, mas ambígua) é um modificador que eu uso e recomendo a outras pessoas o tempo todo para entregar mudanças de estado (mesmo que o verbo seja semi-óbvio).

Jeff Langemeier
fonte
0

Notação húngara em socorro. Você pode ter intChargee fcnCharge(value), assim, evitar confusão e não adicionar um nome longo e louco quando três letras funcionarem perfeitamente.

Ou você pode simplesmente usar o mesmo nome e deixar o IDE lidar com isso. Criar um nome mais longo ou diferente pode ser igualmente confuso a longo prazo.

Ryathal
fonte
+1 para a perspectiva exclusiva da resposta. Lamentavelmente, a notação húngara é explicitamente verboten de acordo com nossas diretrizes de estilo de código. Isso não altera o mérito potencial da sua resposta, apenas que eu não posso usá-la como minha solução real.