O que pascal e um camêlo tem em comum?

camelcase, pascalcase, snakecase

Fala galera! 👋

Hoje vamos falar de algo que parece coisa de desenvolvedor, mas que tem um impacto enorme nas decisões de produto: as convenções de nomenclatura em APIs. Mesmo que você não esteja codando no dia a dia, entender esses padrões vai te ajudar a se comunicar melhor com o time de engenharia e tomar decisões mais acertadas sobre o design técnico do seu produto.

Por que as Convenções de Nomenclatura importam para o Produto?

Como PMs de produtos técnicos ou plataformas, tomamos decisões que afetam como os desenvolvedores interagem com nossos produtos, especialmente quando se trata de APIs. A forma como nomeamos as coisas impacta:

• A experiência e adoção pelos desenvolvedores

• A clareza da documentação

• A consistência em todo o ecossistema do produto

• A comunicação entre os times

Bora então, olhar mais de perto, os três padrões comuns que você vai encontrar em discussões de produto e planejamento de API.

camelCase: aquele Corcunda

CamelCase se parece com isso:

nomeUsuario, totalPedido, enderecoEntrega

Exemplo do mundo real: Quando você estiver olhando uma especificação de feature para um perfil de usuário, poderá ver campos definidos como:

idUsuario;
emailUsuario;
dataUltimoLogin;
metodoPagamentoPreferido;

Onde você pode encontrar essa info no seu dia a dia como PM:

• Em aplicações web baseadas em JavaScript

• Na maioria dos desenvolvimentos de apps mobile (iOS/Android)

• Documentações de API REST modernas

• Especificações de features para muitos consumers (tipo o exemplo da Orders do Ifood que a Sheila Chang passou no Livro dela)

Dica: Se seus desenvolvedores usam camelCase, certifique-se de que suas especificações de produto, eventos de analytics e documentação seguem o mesmo padrão. Por exemplo, se você estiver definindo um novo fluxo de onboarding, mantenha seus nomes de eventos consistentes: usuarioCadastrado, perfilCompletado, tutorialPulado.

snake_case: famigerado underline

Snake case se parece com isso:

nome_usuario, total_pedido, endereco_entrega

Exemplo do mundo real: Ao revisar esquemas de banco de dados ou exportações de dados, você pode ver:

id_usuario; 
data_compra; 
valor_total; 
metodo_envio;

Onde você pode encontrar essa info no seu dia a dia como PM:

• Nomes de colunas em data warehouses

• Nomes de campos em bancos de dados

• Serviços de backend baseados em Python

• Muitas APIs de processadores de pagamento (como o PagSeguro)

Dica: Ao criar requisitos de dados ou especificações de analytics, combine sua nomenclatura com os sistemas subjacentes. Se sua equipe de dados usa snake_case, defina suas métricas e dimensões da mesma forma: usuarios_ativos_mensais, valor_medio_pedido, taxa_conversao_por_canal.

PascalCase: toda palavra nova tem letra maiúscula

PascalCase se parece com isso:

PerfilUsuario, ConfirmacaoPedido, MetodoPagamento

Exemplo do mundo real: Em um roadmap de produto ou documento de arquitetura, você pode ver componentes ou serviços nomeados:

ServicoIdentidade;
ProcessadorPagamento;
MotorRecomendacao;

Onde você pode encontrar essa info no seu dia a dia como PM:

• Nomes de classes e componentes em docs de arquitetura técnica

• Nomes de microsserviços em diagramas de sistema

• Nomes de componentes React em arquitetura front-end

• Serviços baseados em .NET

Dica: Ao discutir arquitetura de sistema ou definir novos serviços, use PascalCase para os principais componentes. Por exemplo, se você estiver planejando uma nova feature que requer vários serviços, pode nomeá-los: ServicoPreferenciaUsuario, SistemaRecomendacaoConteudo, GerenciadorNotificacoes.

Exemplo Prático: Planejando uma Nova Feature

Digamos que você esteja trabalhando em uma nova feature para seu app de e-commerce: um sistema de recomendação personalizada. Veja como essas convenções de nomenclatura apareceriam em diferentes contextos:

1. Na sua spec de produto (usando camelCase para APIs):

   Novo endpoint de API: GET /recomendacoes/preferenciasUsuario
   Parâmetros de requisição: idUsuario, idCategoria, resultadosMaximos
   Campos de resposta: itensRecomendados, pontuacaoCorrespondencia, ultimaAtualizacao

2. Nos seus requisitos de dados (usando snake_case para dados):

   Novos eventos de analytics:

   1. recomendacao_exibida

   2. recomendacao_clicada

   3. recomendacao_convertida
      

      Métricas para acompanhar:

   4. taxa_clique_recomendacao

   5. receita_media_das_recomendacoes

3. Na discussão de arquitetura (usando PascalCase para serviços):

Novos componentes:

- MotorRecomendacao;
- ServicoPreferenciaUsuario; 
- IntegracaoCatalogoProdutos;

Exemplos de APIs do Mundo Real

Quando você estiver avaliando APIs de terceiros ou planejando algo referente sua própria API, aqui estão alguns exemplos de grandes players do mercado:

API do PagSeguro (usa snake_case):

API do Salesforce (usa camelCase):

API do Microsoft Graph (usa camelCase):

Tomando decisões de Produto sobre Nomenclatura

Como PM, você frequentemente precisará tomar ou influenciar decisões sobre convenções de nomenclatura. Aqui está como abordar isso:

1. Consulte seus líderes de engenharia - Entenda quais convenções já estão em uso

2. Considere seu público de desenvolvedores - Se você está construindo para devs JavaScript, camelCase pode parecer mais natural

3. Seja consistente - Qualquer que seja sua escolha, aplique em todo o produto

4. Documente suas convenções - Inclua diretrizes de nomenclatura na documentação da sua API. Falamos sobre documentação aqui:

   Mini curso - API Integration para Product Managers #3

5. Pense nas integrações - Considere como sua nomenclatura funcionará com ferramentas e plataformas populares

Algumas boas práticas

1. Combine seus mockups com seus dados - Se seu banco de dados usa snake_case, suas especificações de UI devem refletir isso

2. Crie um guia de nomenclatura - Desenvolva uma referência simples para sua equipe garantir consistência

3. Revise para manter consistência - Ao fazer revisões de produto, verifique se as novas features seguem os padrões existentes

Nomes importam para o sucesso do Produto

Enquanto convenções de nomenclatura podem parecer um detalhe técnico, elas impactam a usabilidade do produto, a comunicação da equipe e a manutenção a longo prazo. Ao entender esses padrões e promover consistência, você ajudará a criar uma experiência de produto mais coerente tanto para seus usuários quanto para sua equipe de desenvolvimento.

Lembre-se: Uma boa nomenclatura é invisível quando feita corretamente, mas dolorosa quando feita errada. Acredite: aquele bug p0 ser corrigido com a remoção de um underline é osso! Como PM, você está em uma posição única para defender a consistência em todo o ecossistema do seu produto.

Quais desafios de nomenclatura você encontrou no seu trabalho com produtos? Já teve que conciliar diferentes convenções entre equipes ou sistemas? Compartilha ;)

Bora fazer APIs incríveis! 🚀💻

Referências

1. Documentação do Google API Design Guide

2. Microsoft API Guidelines

3. Documentação da API PagSeguro

4. Convenções de Nomenclatura JavaScript no MDN Web Docs

5. Convenções de Nomenclatura em C# da Microsoft

6. Documentação da API do Stripe

7. Guia de RESTful API da Zalando

8. Documentação da API Salesforce