Instruction file imported from cesar-carlos/flutter-expedicao-app (.cursor/rules/general_rules.mdc). Copyright stays with the author.

Regras Gerais do Projeto

Documentação e Comentários

Documentação Automática

• ❌ NÃO criar documentação automaticamente (comentários ///, README.md, etc.)
• ❌ NÃO criar arquivos de documentação sem solicitação explícita
• ❌ NÃO adicionar comentários desnecessários no código
• ✅ Apenas criar documentação quando explicitamente solicitado pelo usuário
• ✅ Código deve ser autoexplicativo através de nomenclatura clara

Quando Documentar

• ✅ Documente apenas APIs públicas complexas quando solicitado
• ✅ Adicione comentários apenas para explicar "por quê", não "o quê"
• ✅ Use comentários para decisões arquiteturais importantes quando necessário
• ✅ Documente apenas quando o código não é autoexplicativo

Exemplo de Comportamento

❌ NÃO fazer:

/// Service for managing user operations.
///
/// This service provides methods to create, update, and delete users.
class UserService {
  /// Creates a new user with the given [name] and [email].
  ///
  /// Returns the created [User] if successful, or throws an exception.
  Future<User> createUser({
    required String name,
    required String email,
  }) async {
    // Implementação
  }
}

✅ Fazer (sem documentação automática):

class UserService {
  Future<User> createUser({
    required String name,
    required String email,
  }) async {
    // Implementação
  }
}

✅ Fazer apenas quando solicitado:

/// Service for managing user operations.
///
/// This service provides methods to create, update, and delete users.
class UserService {
  // Documentação criada apenas porque foi explicitamente solicitada
}

Arquivos de Documentação

Não Criar Automaticamente

• ❌ NÃO criar README.md automaticamente
• ❌ NÃO criar arquivos .md de documentação
• ❌ NÃO criar arquivos de changelog ou release notes
• ❌ NÃO criar arquivos de exemplo ou guias
• ✅ Apenas criar quando explicitamente solicitado

Comentários no Código

✅ Bom: Comentários apenas quando necessário

// ✅ Bom: explica por quê (decisão importante)
// Usar cache local para reduzir chamadas à API em 80%
final cachedUser = await localCache.getUser(id);

// ✅ Bom: explica decisão arquitetural
// Usar Result ao invés de Exception para manter compatibilidade com Domain Layer
return await repository.getById(id);

❌ Evite: Comentários desnecessários

// ❌ Evite: explica o que (código já faz isso)
// Obter usuário do cache
final user = await cache.getUser(id);

// ❌ Evite: comentário óbvio
// Incrementar contador
_counter++;

Princípios de Código Limpo

Código Autoexplicativo

• ✅ Use nomes descritivos e claros
• ✅ Nomenclatura deve deixar o código autoexplicativo
• ✅ Evite comentários que apenas repetem o código
• ✅ Prefira código claro sobre comentários

Exemplo

❌ Evite:

// Criar usuário
void createUser(String name) {
  // Validar nome
  if (name.isEmpty) {
    // Lançar erro
    throw Exception('Name cannot be empty');
  }
  // Salvar usuário
  _saveUser(name);
}

✅ Prefira:

void createUser(String name) {
  if (name.isEmpty) {
    throw Exception('Name cannot be empty');
  }
  _saveUser(name);
}

Checklist de Regras Gerais

• NÃO criar documentação automaticamente
• NÃO criar arquivos .md sem solicitação explícita
• NÃO adicionar comentários desnecessários
• Código deve ser autoexplicativo
• Documentar apenas quando explicitamente solicitado
• Comentários apenas para explicar "por quê", não "o quê"
• Usar nomenclatura clara ao invés de comentários