Padrões de Nomenclatura

Para padronizar o código do backend, seguimos um padrão de nomenclatura que combina a PEP8 com nossas convensões de nomenclatura. Nesta documentação você irá encontrar os padrões sobre:

Classes

As nomenclatura das nossas classes segue o padrão de estilos do Python, CamelCase.

API

Na camada de API, o nome da classe deve seguir o padrão <recurso>API, sendo que o nome do recurso deve sempre estar no plural quando os métodos atribuidos a classe trata de um conjunto de itens, e no singular quando a ação é somente sobre um item daquele recurso.

class UsersAPI(RestAPI):
  list_prop = "users"
  auth = True
  read_scopes = [scopes.USERS]
  write_scopes = [scopes.USERS]
  
  ...

Ainda na camada de API, apesar de muita coisa estar encapsulada em nossa classe RestAPI, da qual herdamos, existem situações em que precisamos sobrescrever algumas coisas.

Quando precisamos sobrescrever alguma função da API referente aos métodos HTTP, para fazer algum tratamento especial de dados, ou para realizar alguma operação que a classe RestAPI não é capaz de fazer, devemos seguir o padrão de:

Nome da função deve ser referente ao método, sendo que utilizamos

Método HTTP	Nome do método na classe
GET - Singular	`get`
GET - Multiplos itens	`list`
PUT	`update`
POST	`create`
DELETE	`delete`

Caso de Uso

Para os repos, sempre utilizamos o padrão <recurso>UC, o UC significa Use Cases, tradução pro inglês de Caso de Uso, utilizando o nome do recurso sempre no plural.

Para os métodos de criação, atualização e deleção de itens, seguimos o mesmo padrão dos métodos da API. Não é necessário informar o item no nome do método.

class UsersUseCases(BaseUC):
    def __init__(
        self,
        repo: SQLUsersRepo,
        roles_repo: SQLRolesRepo,
        ssh_repo: SSHUsersRepo,
        events: UsersEvents,
        audit,
    ):
        self.repo = repo
        self.roles_repo = roles_repo
        self.events = events
        self.audit = audit
        self.ssh_repo = ssh_repo

    ...

Repo

Para os repos, sempre utilizamos o padrão SQL<recurso>Repo, com o recurso sempre no plural. Exemplo: SQLRulesRepo

class SQLUsersRepo(SQLRepoBase):
    def __init__(self, sessionmaker: SessionMaker):
        super().__init__(sessionmaker, SQLUser, user_to_db, db_to_user)
        self.sessionmaker = sessionmaker
    
    ...

Funções

As funções sempre devem ser no modo imperativo, informando o que ela faz, ou o tipo de retorno que ela dara.

def get_linux_users():

  ...

Variáveis

Para as variáveis, sempre devemos utilizar o padrão snake_case definido pela PEP8. O nome das variáveis sempre deve remeter o que está sendo atribuído a ela, dentro do seu contexto de uso.

Um exemplo do uso quando instanciamos classes:

audit_events = AuditEvents(events)
users_events = UsersEvents(events)
roles_events = RolesEvents(events)

Módulos

Para a definição da nomenclatura dos módulos do produto, utilizamos o padrão itflex_<módulo>, com o nome do módulo sempre estando em inglês, por exemplo um módulo de auditoria seria traduzido para o inglês como audit e o nome desse módulo seria itflex_audit. O sufixo do nome do módulo deve sempre remeter de forma macro o seu propósito, sendo que seu nome ou ao menos a ideia em português já nos é entregue no título do ticket a respeito do módulo. A baixo segue alguns exemplos de como nomeamos os módulos do FwFlex.

itflex/server/backend/itflex_auth/
itflex/server/backend/itflex_firewall/
itflex/server/backend/itflex_ipsec/
itflex/server/backend/itflex_logs/
itflex/server/backend/itflex_networks/
itflex/server/backend/itflex_packages/

Recursos

Os recursos são os elementos de funcionalidades que compõem o módulo, são mais específicos em seus objetivos. O nome dos recursos dos módulos na maioria das situações é definido pela equipe de desenvolvimento durante reuniões técnicas sobre o módulo ou recurso. Seu nome na grande maioria das vezes deve ser no plural, porém existem exceções quando ao colocar o nome do recurso no plural, perde-se o sentido do seu propósito. Abaixo segue alguns exemplos de como nomeamos os recursos de um módulo do FwFlex.

itflex/server/backend/itflex_auth/usability
itflex/server/backend/itflex_auth/apikeys
itflex/server/backend/itflex_auth/roles
itflex/server/backend/itflex_auth/users
itflex/server/backend/itflex_auth/sshusers
itflex/server/backend/itflex_auth/onboardings