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

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.

• Diretrizes de nomenclatura de método conciso significativas
• Convenções de nomenclatura para variáveis
• A resposta selecionada em https://softwareengineering.stackexchange.com/questions/14169/what-naming-guidelines-do-you-follow

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.

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.

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.

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

Battery.doCharge()

Battery.getCharge()

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

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).

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.