Como Construir o Livro de Códigos da Tese: Dicionário de Variáveis Passo a Passo (2026)

O livro de códigos é o documento que explica o que cada coluna da sua base de dados significa: o nome da variável, a pergunta que lhe deu origem, os valores possíveis e o que cada valor representa. Sem ele, ninguém — incluindo o próprio autor três meses depois — consegue reproduzir a análise. Constrói-se enquanto se prepara os dados, não no fim.

É também a peça que separa uma base de dados utilizável de uma folha de Excel com colunas chamadas P1, P2 e P3a. Este guia leva-o pelos oito passos, na ordem em que se fazem, com as convenções que o SPSS impõe e os erros que custam mais tempo a corrigir depois.

Passo 1 — Decida onde o livro de códigos vai viver

Tem duas opções, e a resposta certa é normalmente as duas ao mesmo tempo.

Dentro do ficheiro de dados. No SPSS, o separador Variable View é um livro de códigos: cada linha é uma variável e as colunas Name, Label, Values, Missing, Measure guardam exactamente a informação que precisa de registar. A vantagem é que viaja com os dados e o output sai já legível. Em R, o equivalente é atribuir atributos ou usar um ficheiro de rótulos separado; em Excel não existe equivalente, o que é a principal razão para não manter só o Excel.

Num documento à parte. Uma folha de cálculo com uma linha por variável, que pode imprimir, anexar à tese e entregar ao júri. É esta versão que vai para os anexos.

Comece pela segunda, porque é onde pensa, e transponha para a primeira à medida que constrói o ficheiro. As colunas mínimas do documento à parte são sete: nome da variável, etiqueta, pergunta original, tipo, nível de medida, valores e códigos de omissão.

Passo 2 — Fixe uma convenção de nomes antes da primeira variável

Os nomes das variáveis são a única coisa deste processo que é penosa mudar depois, porque aparecem na sintaxe, nos outputs guardados e nos gráficos já produzidos. Decida a convenção uma vez e não a altere.

Regras que funcionam bem e são compatíveis com SPSS, R e Stata:

• Minúsculas, sem acentos, sem espaços. satisf_geral, não Satisfação Geral. Acentos em nomes de variáveis causam problemas de codificação ao exportar.
• Comece por uma letra e use apenas letras, dígitos e underscore.
• Prefixo por escala. Todos os itens de uma escala partilham o prefixo e diferem no número: servq01 a servq22. Isto permite seleccioná-los todos de uma vez no SPSS.
• Numere com dois dígitos se a escala tiver dez ou mais itens. item01 ordena correctamente; item1 coloca o item10 antes do item2.
• Marque as variáveis derivadas com um sufixo consistente: _r para itens invertidos, _tot para somatórios, _z para padronizadas, _rec para recodificadas.

Não codifique informação essencial só no nome. O nome é um identificador curto; o significado vive na etiqueta.

Passo 3 — Escreva a etiqueta de cada variável

A etiqueta (Label, no SPSS) é o texto que aparece nas tabelas de resultados em vez do nome críptico. É o que transforma um output ilegível numa tabela que pode quase colar na tese.

Uma etiqueta útil é uma frase curta que identifica o construto e, se necessário, a direcção: «Satisfação global com o serviço (1 = nada satisfeito)». Se a variável for um item de escala, inclua o texto do item — abreviado se for longo. O SPSS aceita etiquetas longas, mas as tabelas ficam mais legíveis abaixo de cerca de sessenta caracteres.

Guarde a pergunta original completa numa coluna separada do documento à parte. É essa que responde à pergunta do júri «o que é que perguntou exactamente?», e é essa que permite a alguém replicar o seu instrumento.

Passo 4 — Defina o tipo e o nível de medida

O SPSS pede duas coisas distintas que se confundem com frequência. O tipo (Type) é técnico: numérico, string, data. O nível de medida (Measure) é estatístico: nominal, ordinal ou escala.

Duas consequências práticas, e ambas causam erros reais:

• Guarde tudo o que puder como numérico. Uma variável de sexo guardada como texto («Feminino», «feminino», «F») cria três categorias em vez de uma. Codifique 1 e 2 e ponha os rótulos nos valores.
• O nível de medida controla o que o software lhe deixa fazer e o que sugere por defeito. Uma escala Likert somada é normalmente tratada como escala; um item Likert isolado é ordinal. Registe a decisão no livro de códigos, porque é uma escolha metodológica que pode ter de defender.

Defina também as casas decimais. Deixar duas casas numa variável que só tem inteiros enche as tabelas de zeros desnecessários.

Passo 5 — Rotule todos os valores das variáveis categóricas

Esta é a coluna Values do SPSS, e é o coração do livro de códigos. Para cada variável nominal ou ordinal, registe o que significa cada número.

Convenções que evitam problemas mais à frente:

• Comece em 1, não em 0, excepto em variáveis binárias que vão entrar numa regressão — aí 0 = não e 1 = sim torna o coeficiente directamente interpretável.
• Mantenha a ordem numérica alinhada com a ordem conceptual nas variáveis ordinais. Se 1 é «discordo totalmente», 5 tem de ser «concordo totalmente» — nunca o inverso em algumas variáveis e não noutras.
• Rotule sempre, mesmo quando parece óbvio. «1 = masculino» é óbvio hoje e não é óbvio daqui a seis meses, quando tiver quatro ficheiros com convenções diferentes.
• Nunca reutilize um código com significados diferentes entre variáveis do mesmo bloco.

Passo 6 — Declare os códigos de omissão (e não os deixe passar por dados)

É aqui que se perde mais tempo em teses quantitativas, e o erro é sempre o mesmo: um código de omissão que o software leu como um valor real.

Se codificar «não responde» como 99 e não declarar o 99 como valor omisso, a média da variável sobe drasticamente e nenhum aviso é emitido. O resultado é um capítulo de resultados inteiro construído sobre médias erradas.

O procedimento correcto tem três partes:

1. Use códigos impossíveis para o intervalo da variável. Numa Likert de 1 a 5, o 9 serve; numa variável de idade, não — use 999.
2. Distinga os tipos de omissão. Não é a mesma coisa não responder, não se aplicar, ou o participante ter abandonado o questionário. Códigos diferentes (por exemplo 97, 98, 99) preservam essa informação e permitem descrever o padrão de omissão no capítulo de método.
3. Declare-os na coluna Missing de cada variável, uma a uma. É este passo que é esquecido — declarar no livro de códigos e não no ficheiro não protege de nada.

Depois de declarados, confirme o número de casos válidos de cada variável com uma tabela de frequências antes de qualquer análise. Sobre o que fazer com as omissões depois de as ter identificado correctamente, veja como lidar com dados em falta.

Passo 7 — Documente todas as variáveis derivadas

Qualquer variável que não venha directamente do instrumento precisa de uma linha própria no livro de códigos e de um registo de como foi criada. São quatro casos típicos:

• Itens invertidos. Registe a fórmula exacta — numa escala de 1 a 5, o item invertido é 6 − valor original — e guarde a variável nova em vez de sobrescrever a original.
• Pontuações de escala. Indique que itens entram, se é soma ou média, e o que faz quando falta um item. «Média dos itens respondidos se pelo menos 80 % estiverem preenchidos» é uma regra explícita; «média» não é.
• Recodificações e agrupamentos. Se agrupou idades em escalões, registe os pontos de corte e se são inclusivos ou exclusivos.
• Variáveis dummy. Registe qual é a categoria de referência — a que fica de fora — porque é dela que depende a leitura de todos os coeficientes.

Guarde a sintaxe. No SPSS, cada transformação feita pelos menus tem um botão Paste que escreve o comando num ficheiro de sintaxe. Um ficheiro .sps com todas as transformações pela ordem em que foram feitas é o complemento natural do livro de códigos: junto, permite reconstruir a base de dados analítica a partir da base bruta. É também a resposta mais forte que existe à pergunta «como chegou a este número?».

Passo 8 — Feche, verifique e anexe

Antes de considerar o livro de códigos terminado, faça três verificações rápidas:

1. Contagem. O número de linhas do livro de códigos é igual ao número de colunas da base de dados? Uma discrepância significa uma variável não documentada ou uma linha a mais.
2. Amplitudes. Corra frequências de todas as variáveis categóricas e mínimos e máximos de todas as contínuas. Qualquer valor fora do intervalo declarado é um erro de introdução — e é mais barato encontrá-lo agora do que quando um valor atípico distorcer um modelo.
3. Teste do estranho. Peça a alguém que não trabalhou nos dados para localizar três variáveis específicas usando só o livro de códigos. Se não conseguir, faltam etiquetas.

Anexe a versão em documento à tese. Muitos regulamentos não a exigem explicitamente, mas nenhum a proíbe, e é um anexo que sinaliza rigor sem custar páginas de argumentação. Se pretende depositar os dados num repositório, o livro de códigos é obrigatório na prática — o enquadramento está em gestão de dados de investigação, FAIR e repositórios.

Os erros que custam mais tempo

Perguntas frequentes

O livro de códigos é obrigatório na tese?

Raramente é exigido por regulamento, mas é frequentemente pedido pelo orientador e é sempre um bom anexo. Onde se torna praticamente obrigatório é no depósito de dados num repositório e em qualquer submissão a revista que exija dados abertos.

Qual é a diferença entre livro de códigos e dicionário de variáveis?

Na prática nenhuma, e os dois termos usam-se como sinónimos. Alguns autores reservam «dicionário de variáveis» para a lista técnica de nomes, tipos e valores, e «livro de códigos» para o documento mais completo que inclui também a pergunta original e as regras de derivação. Use um termo e defina-o na primeira utilização.

Posso fazer o livro de códigos só no fim, quando os dados estiverem prontos?

Pode, e vai custar-lhe muito mais tempo. As decisões que precisa de registar — porque agrupou assim, porque excluiu aquele caso, que regra usou para as omissões parciais — são tomadas ao longo de semanas e esquecem-se depressa. Preencha à medida.

E se usar R em vez de SPSS?

A lógica é idêntica e o registo passa a viver no script. Mantenha na mesma o documento à parte para o anexo, porque um script não é um livro de códigos legível para o júri. Pacotes de rotulagem permitem guardar etiquetas de variável e de valor no próprio objecto de dados.

Como documento perguntas de resposta múltipla?

Cada opção passa a ser uma variável binária própria — motivo_a, motivo_b — com 0 e 1. Registe no livro de códigos que pertencem ao mesmo grupo e se o respondente podia escolher várias. Guardar todas as respostas numa só coluna separada por vírgulas torna a variável inanalisável.

Devo registar as datas de recolha?

Sim, se a recolha decorreu ao longo de semanas ou por vagas. Uma variável de data ou de vaga permite verificar se os primeiros e os últimos respondentes diferem, que é uma verificação relevante quando a taxa de resposta foi baixa.

O que faço se descobrir um erro de codificação já com a análise feita?

Corrija na base bruta, volte a correr a sintaxe completa e refaça a análise. É precisamente para este cenário que serve manter o ficheiro de sintaxe: sem ele, a correcção obriga a repetir manualmente todos os passos e a esperança de não falhar nenhum.

Preciso de um livro de códigos numa tese qualitativa?

Precisa de um equivalente, com outro nome e outra função: o sistema de códigos temáticos, com definição, critérios de inclusão e exemplo para cada código. A lógica é a mesma — tornar explícita uma decisão que de outro modo fica na cabeça do investigador.

Chegue à análise com os dados prontos

O tempo que uma tese quantitativa perde não está nos testes estatísticos — está em descobrir, a meio da análise, que uma variável está mal codificada e que ninguém registou porquê. O Tesify ajuda-o a estruturar o capítulo de método com a descrição das variáveis, a documentar as decisões de codificação e a transformar o livro de códigos num anexo apresentável. Comece agora, gratuitamente.

Com os dados documentados, o passo seguinte é a preparação no software: o percurso completo está em como preparar e analisar o dataset da tese no SPSS.