Normas e estilo

Estas indicações não são uma expetativa de que cada contributo cumpra à risca as normas. No entanto, ajuda-nos imenso se não tivermos de editar profundamente cada contributo para que se possa manter alguma integridade e regularidade nos nomes e formatos que usamos na Central de Dados -- o projeto foi criado precisamente para lidar com a dispersão de formatos e estilos nos datasets que usamos regularmente.

Formatos

CSV

Usamos sempre vírgulas como separador, e " como delimitador de texto. Sempre que possível evitamos o uso dos delimitadores em campos com números, datas ou outros valores que não sejam texto nem sejam passíveis de conter vírgulas.

A codificação do ficheiro deve ser Unicode (UTF-8). É frequente encontrarmos ficheiros noutras codificações, como ISO-8859 ou CP-1252. É importante assegurar, normalmente nas opções de exportação, que os ficheiros CSV que criamos saem no formato UTF-8.

Outros formatos de dados

....

Nomenclatura e grafia

Nomes das data packages

Distinguimos entre nome -- o nome do ficheiro ou diretório da data package -- e o título -- o título para seres humanos.

Os nomes das data packages devem ser especificados segundo estes princípios base:

• Apenas minúsculas e números
• Caem acentos e cedilhas
• Omite-se "do", "da", "dos", "das", "de"
• Espaços são substituídos por underscores (_)

Para o nome de cada data package, especificamos primeiro a área a que diz respeito, seguida de um hífen e o assunto ou tema específico do dataset que contém.

Alguns exemplos:

• parlamento-registos_interesse
• eleicoes-regionais_madeira

Nomes das colunas

Os nomes das colunas devem ser formatados segundo estes princípios base:

• Apenas minúsculas e números
• Caem acentos e cedilhas
• Omite-se "do", "da", "dos", "das", "de"
• Espaços são substituídos por underscores (_)

Alguns exemplos:

• "Texto da intervenção" fica texto_intervencao
• "Valor do IVA" fica valor_iva

Sempre que possível, incluímos um indicador do tipo da coluna, para o nome nos dar imediatamente a noção de que valores podemos esperar.

Governo

• Não: gov
• Sim: num_gov

Legislatura

• Não: leg
• Sim: num_leg

Imposto

• Não: imposto
• Sim: valor_imposto

Fim de mandato

• Não: fim_mandato
• Sim: data_fim_mandato
• Melhor: data_fim (apenas se não houver ambiguidades com outros campos)

Abreviações

Este é um assunto que talvez seja melhor debater mais densamente de acordo com os casos ambíguos que surgirem. Entretanto, vamos usando as seguintes abreviações:

• id para "Identificador"
• gov para "Governo"
• leg para "Legislatura"
• sess para "Sessão Legislativa" ou "Sessão"
• num para "Número"
• abrev para "Abreviado" ou "Abreviatura"

Valores Numéricos

Sempre que pudermos usar valores numéricos, fazemo-lo. Assim, convertemos a numeração romana (I, II, III), usada por exemplo nas legislaturas, para numeração cardinal (1, 2, 3).

Da mesma forma, omitimos prefixos, sufixos e zeros à esquerda. Assim, GC02 (2º Governo Constitucional) pode ser expresso numericamente como 2.

Quando um valor não está disponível, deixamos a célula em branco ou usamos o marcador "ND".

Datas e horas

Nas datas aplicamos a norma ISO 8601, no formato AAAA-MM-DD (ex. 1974-04-25). Esta é a norma que elimina qualquer possível ambiguidade no formato da data.

Para horas, há três formatos possíveis:

• HH:MM:SS (ex. 14:07:56)
• HH:MM no caso de não possuírmos a informação dos segundos
• HH:MM:SS.mmm caso queiramos especificar milissegundos

Para mais pormenores sobre a linda norma ISO 8601, a Wikipédia explica e o XKCD também.

Acordo Ortográfico

O critério de qual norma ortográfica aplicar é deixado à discrição de cada pessoa que se encarregar de documentar uma data package.