Organização e Nomenclatura

1. Por que isso importa mais do que parece

Escrever uma procedure correta é uma coisa; manter 200 delas organizadas, sem duplicação e fáceis de achar, é outra. Este capítulo consolida os hábitos que já apareceram espalhados nos capítulos anteriores num guia único de referência.

2. Convenção de nomenclatura (recapitulando e formalizando)

3. Um cabeçalho padrão de documentação

T-SQL não tem um sistema de documentação embutido como o XML doc do C#, mas um comentário estruturado no topo de cada procedure já resolve 90% do problema de "quem mexeu nisso e por quê":

-- =============================================
-- Procedure:   usp_ClienteAtualizar
-- Descrição:   Atualiza nome e e-mail de um cliente existente.
-- Parâmetros:  @Id     - Id do cliente a atualizar
--              @Nome   - Novo nome
--              @Email  - Novo e-mail
-- Retorno:     0 = sucesso; lança erro se o Id não existir
-- Autor:       Wellington Marunaka
-- Criado em:   2026-01-10
-- Alterado em: —
-- =============================================
CREATE PROCEDURE dbo.usp_ClienteAtualizar
    @Id    INT,
    @Nome  NVARCHAR(100),
    @Email NVARCHAR(150)
AS
BEGIN
    ...
END;
GO

4. Estrutura de pastas do projeto (versionamento)

Procedures deveriam viver em arquivos .sql versionados junto com o código C#, não só "dentro do banco". Uma estrutura comum:

CREATE OR ALTER PROCEDURE dbo.usp_ClienteObter
    @Id INT
AS
BEGIN
    SET NOCOUNT ON;
    SELECT Id, Nome, Email FROM dbo.Cliente WHERE Id = @Id;
END;
GO

5. Uma checklist antes de considerar uma procedure "pronta"

• SET NOCOUNT ON; e SET XACT_ABORT ON; nas duas primeiras linhas (se houver escrita).
• Nome segue usp_<Entidade><Ação>, nunca sp_.
• Cabeçalho de documentação preenchido.
• Parâmetros nomeados de forma clara, tipos com tamanho explícito (NVARCHAR(100), nunca NVARCHAR sem tamanho).
• Escrita protegida por TRY/CATCH + transação quando necessário.
• SQL dinâmico, se houver, usa sp_executesql + QUOTENAME.
• Salva como arquivo .sql versionado, com CREATE OR ALTER.

6. Onde isso te leva

Com organização e nomenclatura fixadas, os dois últimos capítulos deste módulo fecham o ciclo: como chamar tudo isso de dentro do C# de forma limpa, e um projeto prático que junta cada peça vista até aqui.