Objetivo do documento

Este documento de diretrizes de desenvolvimento tem como objetivo principal estabelecer um conjunto abrangente e detalhado de práticas, padrões e princípios que devem ser seguidos por todos os desenvolvedores em nossa organização. Ele serve como um guia autoritativo e uma referência central para garantir consistência, qualidade e eficiência em todos os nossos projetos de desenvolvimento de software.

Os objetivos específicos deste documento incluem:

1. Padronização: Estabelecer um conjunto uniforme de práticas de codificação, arquitetura e design em toda a organização.

   Exemplo: Todos os projetos Laravel devem seguir a estrutura de diretórios padrão do Laravel, com controllers em app/Http/Controllers, models em app/Models, e assim por diante.

2. Qualidade: Promover práticas que levem a um código mais limpo, mais testável e mais manutenível.

   Exemplo: Todos os métodos públicos devem ter testes unitários associados, visando uma cobertura de código de pelo menos 80%.

3. Eficiência: Otimizar o processo de desenvolvimento, reduzindo o tempo gasto em decisões de design e implementação repetitivas.

   Exemplo: Utilizar um conjunto predefinido de bibliotecas e frameworks aprovados para tarefas comuns, como logging (ex: Monolog) ou manipulação de datas (ex: Carbon).

4. Segurança: Garantir que as melhores práticas de segurança sejam seguidas em todos os projetos.

   Exemplo: Todas as entradas de usuário devem ser sanitizadas e validadas, utilizando as ferramentas de validação do Laravel para prevenir ataques como SQL Injection e XSS.

5. Escalabilidade: Assegurar que nossos sistemas sejam projetados para crescer e se adaptar às mudanças nas demandas de negócios.

   Exemplo: Utilizar caching (como Redis) para dados frequentemente acessados e implementar filas (como Laravel Queue) para tarefas assíncronas que podem sobrecarregar o sistema.

6. Onboarding: Facilitar a integração de novos desenvolvedores ao fornecer um recurso abrangente que detalha nossas práticas e expectativas.

   Exemplo: Novos desenvolvedores devem completar um programa de onboarding de duas semanas, que inclui a leitura completa destas diretrizes e a conclusão de um projeto de exemplo que demonstra a aderência a elas.

1.2. Visão geral da empresa e seus produtos

Nossa empresa é uma organização de tecnologia líder no mercado, especializada no desenvolvimento de soluções de software inovadoras e escaláveis. Nosso portfólio diversificado de produtos atende a uma ampla gama de necessidades do mercado, desde aplicações empresariais de grande escala até soluções de nicho altamente especializadas.

Produtos principais:

1. Toolzz LMS (LXP)

   • Arquitetura: Monolito Laravel
   • Descrição: Plataforma whitelabel para criação de cursos e plataformas de ensino a distância.
   • Tecnologias principais: Laravel, MySQL e Redis
   
   

2. Toolzz AI

   • Arquitetura: Microserviços
   • Descrição: Uma plataforma avançada de IA que oferece serviços como processamento de linguagem natural, visão computacional e análise preditiva.
   • Tecnologias principais: Node.js, AdonisJS, PostgreSQL, Redis, CloudFlare Workers, NextJS, LangChain
   
   

3. Toolzz Bots

   • Arquitetura: Monolito

   • Descrição: Plataforma para criação de chatbots e aplicações conversacionais de forma visual e intuitiva, sem necessidade de programação.

   • Tecnologias principais: Node.js, Redis, PostgreSQL

     
     

4. Toolzz Chat

   • Arquitetura: Microserviços

   • Descrição: Plataforma de comunicação com clientes que permite a integração de múltiplos canais de atendimento, como chat ao vivo, e-mail, redes sociais e mais, tudo em um único painel.

   • Tecnologias principais: Ruby on Rails, Node.js, Redis, PostgreSQL, React

     
     

5. Toolzz Connect

   • Arquitetura: Microserviços
   • Descrição: Plataforma de automação visual que permite a integração de múltiplos aplicativos, ferramentas e serviços para otimizar processos e fluxos de trabalho sem a necessidade de codificação.
   • Tecnologias principais: Node.js, AWS, Webhooks, GraphQL

Esta diversidade de produtos e arquiteturas demonstra a necessidade de diretrizes de desenvolvimento abrangentes e flexíveis que possam ser aplicadas em diferentes contextos tecnológicos.

1.3. Importância das diretrizes de desenvolvimento

As diretrizes de desenvolvimento desempenham um papel crucial no sucesso de nossa organização e na qualidade de nossos produtos. Sua importância se manifesta em vários aspectos:

1. Consistência As diretrizes garantem que todos os desenvolvedores, independentemente de sua experiência ou background, sigam as mesmas práticas e padrões. Isso resulta em um código mais uniforme e previsível em todos os projetos.

   Exemplo: Ao definir um padrão para nomenclatura de variáveis (como camelCase para variáveis e PascalCase para classes), garantimos que todo o código seja consistente e fácil de ler, independentemente de quem o escreveu.

2. Qualidade Ao estabelecer padrões elevados e melhores práticas, as diretrizes contribuem diretamente para a melhoria da qualidade geral do código e dos produtos.

   Exemplo: A exigência de testes unitários para todas as novas funcionalidades ajuda a identificar bugs precocemente e garante que o código funcione conforme o esperado.

3. Eficiência As diretrizes eliminam a necessidade de debates recorrentes sobre práticas de codificação e design, permitindo que os desenvolvedores se concentrem na resolução de problemas de negócios.

   Exemplo: Ao definir uma estrutura padrão para projetos Laravel, eliminamos discussões repetitivas sobre onde colocar diferentes tipos de arquivos, acelerando o início de novos projetos.

4. Manutenibilidade Código que segue diretrizes consistentes é mais fácil de entender, manter e atualizar, reduzindo o custo total de propriedade do software ao longo do tempo.

   Exemplo: A prática de escrever comentários significativos e manter uma documentação atualizada facilita a compreensão do código por outros desenvolvedores no futuro.

5. Escalabilidade As diretrizes ajudam a garantir que nossos sistemas sejam projetados com escalabilidade em mente desde o início.

   Exemplo: A recomendação de usar padrões de design como Repository e Service Layer no Laravel ajuda a criar uma separação clara de responsabilidades, facilitando a escalabilidade do código.

6. Segurança Ao incorporar práticas de segurança em nossas diretrizes, garantimos que a segurança seja uma consideração em todas as fases do desenvolvimento.

   Exemplo: A exigência de usar prepared statements para todas as consultas SQL ajuda a prevenir vulnerabilidades de injeção de SQL.

7. Onboarding As diretrizes servem como um recurso valioso para novos membros da equipe, acelerando o processo de integração e garantindo que eles se alinhem rapidamente com as práticas da equipe.

   Exemplo: Um novo desenvolvedor pode consultar as diretrizes para entender como estruturar testes em um projeto Laravel, sem necessidade de orientação direta constante.

8. Colaboração Com práticas padronizadas, é mais fácil para os desenvolvedores colaborarem em diferentes projetos e entenderem o código uns dos outros.

   Exemplo: O uso consistente de ferramentas de análise estática de código (como PHPStan para PHP) em todos os projetos permite que os desenvolvedores identifiquem e corrijam problemas de qualidade de código de forma consistente.

9. Inovação Controlada Enquanto as diretrizes estabelecem padrões, elas também devem permitir flexibilidade para inovação quando justificada.

   Exemplo: As diretrizes podem incluir um processo para propor e avaliar novas tecnologias ou práticas, permitindo que a equipe evolua suas práticas de forma controlada.

10. Conformidade e Auditoria Em muitos setores, a conformidade com certos padrões é obrigatória. As diretrizes ajudam a garantir que essas exigências sejam atendidas consistentemente.

    Exemplo: Para projetos que lidam com dados pessoais, as diretrizes devem incluir práticas específicas de proteção de dados para garantir conformidade com a LGPD.

Em resumo, as diretrizes de desenvolvimento são a espinha dorsal de nossa prática de engenharia de software. Elas não são apenas um conjunto de regras, mas um reflexo de nossa cultura de excelência técnica e nosso compromisso com a entrega de produtos de alta qualidade. Ao aderir a estas diretrizes, cada desenvolvedor contribui para o sucesso coletivo de nossa organização e para a satisfação de nossos clientes.