Enum Design

Enums são um tipo especial de valor. Existem dois tipos de enums: enums simples e enums de bandeira.

Enums simples representam pequenos conjuntos fechados de escolhas. Um exemplo comum do enum simples é um conjunto de cores.

Os enums de sinalizador são projetados para suportar operações bitwise nos valores de enum. Um exemplo comum do enum das bandeiras é uma lista de opções.

✔️ DO use um enum para digitar fortemente parâmetros, propriedades e valores de retorno que representam conjuntos de valores.

✔️ DO favor usando um enum em vez de constantes estáticas.

❌ NÃO use um enum para conjuntos abertos (como a versão do sistema operacional, nomes de seus amigos, etc.).

❌ NÃO forneça valores de enum reservados que se destinem a uso futuro.

Você sempre pode simplesmente adicionar valores ao enum existente em um estágio posterior. Consulte Adicionando valores a Enums para obter mais detalhes sobre como adicionar valores a enums. Os valores reservados apenas poluem o conjunto de valores reais e tendem a levar a erros do utilizador.

❌ EVITE expor publicamente enums com apenas um valor.

Uma prática comum para garantir a extensibilidade futura de APIs C é adicionar parâmetros reservados às assinaturas de método. Tais parâmetros reservados podem ser expressos como enums com um único valor padrão. Isso não deve ser feito em APIs gerenciadas. A sobrecarga do método permite adicionar parâmetros em versões futuras.

❌ NÃO inclua valores sentinela em enums.

Embora às vezes sejam úteis para os desenvolvedores da estrutura, os valores sentinela são confusos para os usuários da estrutura. Eles são usados para rastrear o estado do enum, em vez de ser um dos valores do conjunto representado pelo enum.

✔️ DO fornece um valor de zero em enums simples.

Considere chamar o valor de algo como "Nenhum". Se tal valor não for apropriado para este enum específico, o valor padrão mais comum para o enum deve ser atribuído o valor subjacente de zero.

✔️ CONSIDERE usar Int32 (o padrão na maioria das linguagens de programação) como o tipo subjacente de um enum, a menos que qualquer uma das seguintes opções seja verdadeira:

• O enum é um enum de bandeiras e você tem mais de 32 bandeiras, ou espera ter mais no futuro.

• O tipo subjacente precisa ser diferente do que Int32 para facilitar a interoperabilidade com código não gerenciado esperando enums de tamanhos diferentes.

• Um tipo subjacente mais pequeno resultaria em poupanças substanciais de espaço. Se você espera que o enum seja usado principalmente como um argumento para o fluxo de controle, o tamanho faz pouca diferença. A poupança pode ser significativa se:

  • Você espera que o enum seja usado como um campo em uma estrutura ou classe instanciada com muita frequência.

  • Você espera que os usuários criem grandes matrizes ou coleções das instâncias de enum.

  • Você espera que um grande número de instâncias do enum seja serializado.

Para uso na memória, esteja ciente de que os objetos gerenciados estão sempre DWORDalinhados, portanto, você precisa efetivamente de vários enums ou outras estruturas pequenas em uma instância para empacotar um enum menor para fazer a diferença, porque o tamanho total da instância sempre será arredondado para um DWORD.

✔️ Enums de bandeira de nome DO com substantivos plurais ou frases nominais e enums simples com substantivos singulares ou frases nominais.

❌ NÃO se estenda System.Enum diretamente.

System.Enum é um tipo especial usado pelo CLR para criar enumerações definidas pelo usuário. A maioria das linguagens de programação fornece um elemento de programação que lhe dá acesso a essa funcionalidade. Por exemplo, em C# a enum palavra-chave é usada para definir uma enumeração.

Projetando Enums de Bandeira

✔️ NÃO aplique o System.FlagsAttribute para sinalizar enums. Não aplique este atributo a enums simples.

✔️ USE poderes de dois para os valores de enum do sinalizador para que eles possam ser livremente combinados usando a operação OR bit a bit.

✔️ CONSIDERE fornecer valores de enum especiais para combinações de bandeiras comumente usadas.

As operações Bitwise são um conceito avançado e não devem ser necessárias para tarefas simples. ReadWrite é um exemplo desse valor especial.

❌ EVITE criar enums de sinalizador onde certas combinações de valores são inválidas.

❌ EVITE usar valores de enum de sinalizador de zero, a menos que o valor represente "todos os sinalizadores estão limpos" e seja nomeado apropriadamente, conforme prescrito pela próxima diretriz.

✔️ DO nomeie o valor zero de enums Nonede sinalizador . Para um enum de bandeira, o valor deve sempre significar "todas as bandeiras estão limpas".

Agregando Valor à Enums

É muito comum descobrir que você precisa adicionar valores a um enum depois de já tê-lo enviado. Há um potencial problema de compatibilidade de aplicativos quando o valor recém-adicionado é retornado de uma API existente, porque aplicativos mal escritos podem não lidar com o novo valor corretamente.

✔️ CONSIDERE adicionar valores aos enums, apesar de um pequeno risco de compatibilidade.

Se você tiver dados reais sobre incompatibilidades de aplicativos causadas por adições a um enum, considere adicionar uma nova API que retorne os valores novos e antigos e deprecie a API antiga, que deve continuar retornando apenas os valores antigos. Isso garantirá que seus aplicativos existentes permaneçam compatíveis.

© Partes 2005, 2009 Microsoft Corporation. Todos os direitos reservados.

Reimpresso com permissão da Pearson Education, Inc., de Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries, 2nd Edition por Krzysztof Cwalina e Brad Abrams, publicado em 22 de outubro de 2008 por Addison-Wesley Professional como parte da Microsoft Windows Development Series.

Consulte também

• Diretrizes de projeto de tipo
• Diretrizes de design da estrutura