Universidade de So Paulo

Instituto de Cincias Matemticas e de Computao

GUIA DE CODIFICAO

Manual de Boas Prticas de Programao

SCC0202 -Algoritmos e Estruturas de Dados I
Professora: Sandra Maria Alusio
PAE: Arineiza Cristina Pinheiro

So Carlos, 2010.
1

Guia de Codificao
Manual de Boas Prticas de Programao

Sumrio

pg

1. Padronizao de idiomas

03

2. Nomenclatura de Variveis

03

3. Nomenclatura de Funes

04

4. Nomenclatura de Constantes

04

5. Comentrios

05

6. Cabealhos de Funes

05

7. Criao de Construtor/Destrutor

06

8. Definio de Biblioteca de Erros

06

9. Verificao de Ponteiros

07

10.Abstrao e Encapsulamento

07

11.Identao

10

Autoria: Arineiza Cristina Pinheiro

1. Padronizao de idioma
Definir o idioma a ser adotado durante toda a implementao do programa (ingls ou
portugus). Uma vez definido, todo o programa deve refletir a escolha adotada, sendo vlida para:
nome de variveis, funes, constantes, comentrio etc.
Muitas vezes opta-se por usar os nomes em ingls para TADs clssicos como Pilha, Fila, Lista
para ficarem similares aos nomes usados na literatura clssica (veja o caso do TAD pilhas dado em
sala). Entretanto, a prtica de padronizao de idioma, com a utilizao do portugus, poderia ser
adotada, inclusive para apoiar uma poltica de soberania de lngua .
2. Nomenclatura de Variveis
O nome das variveis deve seguir o modelo: iNomeVariavel.

A primeira letra (em minsculo) do nome da varivel corresponde a primeira letra do seu tipo.
No exemplo, a variavl do tipo int. Para os demais tipos, vide Tabela 1.
Tabela 1 Letras que definem o tipo das variveis
Tipo

Letra

int

float

double

char

Quando houver modificadores, concatenar a primeira letra (em minsculo) do modificador

antes da letra que define o tipo. Por exemplo, uiNomeVariavel seria do tipo unsigned int. As
letras para cada modificador so definidas na Tabela 2.
Tabela 2 Letras que definem o modificador aplicado ao tipo da varivel.
Modificadores

Letra

unsigned

short

long

Se a varivel for um ponteiro, adicionar a letra (em minsculo) p antes das letras que definem
seu tipo. Por exemplo, puiNomeVariavel um ponteiro para uma varivel de tipo unsigned
3

int.

As palavras que definem nome propriamente dito da varivel devem ser escritas com a primeira
letra em maisculo e as demais em minsculo. Por exemplo, puiTamanhoVetor.

O nome das variveis no deve conter caracteres especiais, e acentos, para evitar problemas
com diversos editores.

O nome das variveis sempre deve ser SIGNIFICATIVO. Evitar nome de variveis como:
aux ou i. Prefira iIterador para listas e vetores, iLinha e iColuna para matrizes.

Quando o tipo de uma varivel for um novo tipo criado pelo comando typedef, no
necessrio aplicar os modificadores. Apenas aplicar a letra minscula p caso ela seja um
ponteiro.
Ex.: Matriz* pMatriz

3. Nomenclatura de Funes
O nome das funes deve seguir o modelo: NomeBiblioteca_NomeFuncao().

A primeira parte do nome da funo definida pelo nome do arquivo .h em que est inserida,
sendo o padro de primeira letra em maisculo e as demais em minsculo, para cada palavra
que compe o nome da funo.
Essa prtica auxilia o programador e o usurio da biblioteca que utilizam ambientes como
Eclipse e Code-Blocks, uma vez que disponibilizam a funo auto-completar para nome
de variveis e funes, alm de deixar claro a qual biblioteca pertence cada funo.

Separar o nome da biblioteca do nome da funo com um _ (underline).

O nome da funo deve seguir o mesmo padro adotado para o nome da biblioteca, visando ser
auto-explicativo sobre qual a funcionalidade implementada.

Evitar caracteres especiais, e acentos, pelo mesmo motivo descrito anteriormente no tpico
sobre Nomenclatura de Variveis.
Ex.: Matriz.h Matriz_CriaMatrizVazia

4. Nomenclatura de Constantes
O nome das constantes deve ser apresentado todo em maisculo, podendo ser abreviado.

Por exemplo:#defineTAM100//tamanho

O nome das constantes de erro deve seguir o modelo: ERRO_NOME (Ver tpico 8 - Definio
de Biblioteca de Erros).

A palavra erro deve aparecer em maisculo no incio do nome da constante, seguida de

_(underline) e o nome que descreve o erro, tambm em maisculo.
Por exemplo: #defineERRO_PONTEIRO_NULO1

5. Comentrios

Criar comentrios para expliar trechos pouco claros do cdigo ou com alta complexidade.
Na dvida? Comente!

Comentrios devem ser feitos no idioma definido no incio do projeto, de modo a manter a
uniformidade do texto.

6. Cabealho de Funes
Definir cabealhos para cada funo da biblioteca, que deveram ser reproduzidos no .h e
tambm no .c . No cabealho deve conter as informaes:

@Nome: copiar o nome da funo

@Descricao: em que descrito rapidamente qual a funcionalidade implementada

@Parametro: descreve quais os parmetros da funo

Para efeito de esclarecimento, sinalizar quais so de entrada, sada, ou entrada/sada,
colocando os indicadores _E_ (_IN_), _S_ (_OUT_) e _ES_ (_IO_) respectivamente, antes
do nome dos parmetros (opcional).

@Retorno: descrevendo qual o tipo de retorno da funo, quando for diferente de void.

@Erro: quando h flags de erro, descrever quais os possveis erros a serem retornados.

/*************************************************************************************/
/*@Nome:Matriz_ZeraElemento(Matriz*matriz,intiLinha,intiColuna,int*piFlagErro)*/
/*@Descricao:funoquezeraoelemento(iLinha,iColuna)damatriz*/
/*@Parametro:_E_*matrizmatrizasermanipulada*/
/*_E_iLinhacorrespondeaonmerodalinhadoelemento*/
/*_E_iColunacorrespondeaonmerodacolunadoelemento*/
/*_S_iFlagErroretornaoestadofinaldafuno*/
/*@Erro:ERRO_SUCESSOfunoexecutadacomsucesso*/
/*ERRO_ENDERECO_INVALIDOelementoforadolimitedamatriz*/
/*************************************************************************************/

Essa prtica auxilia no entendimento da biblioteca e refora a documentao do projeto,

deixando claro ao usurio o contrato de uso da biblioteca.

7. Criao de Construtor/Destrutor
Toda biblioteca necessariamente dever possuir duas funes padro: um Construtor e um
Destrutor.

No Construtor, toda inicializao de varivel da biblioteca (alocao de memria) deve ser

concentrada. Esse procedimento facilita a destruio (desalocao) de variveis, que deve ser
realizada na funo Destrutor.
Para cada chamada do Construtor, necessariamente ao final do uso da varivel ou final do
programa dever ter uma chamada do Destrutor.

O nome das funes Construtor e Destrutor pode ser adaptado ao contexto do programa,
devendo apenas seguir o padro j descrito no tpico 3 Nomenclatura de Funes.
Por exemplo: Matriz_CriaMatrizVazia

No cabealho da funo, no item @Descrio descrever que a funo corresponde ao

Construtor/Destrutor da biblioteca (ver tpico 5 Cabealho de Funes).
Por exemplo:

/*@Nome:Matriz_CriaMatrizVazia(intiLinha,intiColuna,int*piFlagErro)*/
/*@Descrio:Construtorcriaumamatrizvaziadedimenso(iLinhaxiColuna)*/

8. Definio de Biblioteca de Erros

Definir uma biblioteca exclusiva para a difinio de erros para seu programa.

Alguns cdigos de erros (ou estado) so recorrentes na maioria dos programas, como: sucesso,
acesso a ponteiro nulo, espao de memria insuficiente.

Criar um .h geral para todos tipos de erro, e sempre incluir na biblioteca a ser disponibilizada.
Facilita o entendimento do cdigo por parte do desenvolvedor da biblioteca.
Disponibilizado o .h ao usurio, possvel consult-lo como parte da documentao.

Por exemplo:
#ifndefBIBLIOERRO_H_INCLUDED
#defineBIBLIOERRO_H_INCLUDED
/*Bibliotecaquedefineostiposdeerrospossveis*/
/*Disponvelaousuriopartedadocumentao*/
#defineERRO_SUCESSO0
#defineERRO_PONTEIRO_NULO1
#defineERRO_ENDERECO_INVALIDO2
#defineERRO_MEMORIA_INSUFICIENTE3
#endif//BIBLIOERRO_H_INCLUDED

9. Verificao de Ponteiros
Toda varivel ponteiro deve ser verificada antes de ser acessada.

Exceto no Construtor, quando a primeira operao for uma alocao de memria (malloc,
calloc...). Porm, verificar aps a alocao se o ponteiro diferente de nulo.
Caso seja nulo, retornar o erro ERRO_MEMORIA_INSUFICIENTE.

Todo parmetro passado biblioteca deve ser verificado se diferente de NULL, isso evita que
o usurio utilize errado as funcionalidades disponibilizadas e garante maior robustez
biblioteca.
Caso o usurio passe um ponteiro nulo, retornar o erro ERRO_PONTEIRO_NULO.

10. Abstrao e Encapsulamento

Na linguagem C, uma forma de se fazer abstrao e encapsulamento de dados a utilizao de
ponteiros opacos para tipos abstratos de dados (TADs). Um ponteiro opaco um caso especial de tipo
de dados opaco, um tipo de dados que declarado como um ponteiro para um registro ou estrutura de
dados de algum tipo no especificado.
Ponteiros opacos representam uma forma de esconder os detalhes da implementao de uma
interface de clientes normais, de modo que a lgica da biblioteca poder ser alterada sem a necessidade
de recompilar os mdulos que a utilizam. Esta caracterstica importante por fornecer compatibilidade,
uma vez que diferentes verses de um biblioteca compartilhada fornecem uma mesma interface ao
usurio final.
Para implementar um ponteiro opaco, define-se a interface da biblioteca em um arquivo .h
que ser desponibilizada ao usurio. Por exemplo:

/*Matriz.h*/
typedefstructMatriz*tMatriz;
/************************************************************************************/
/*@Nome:Matriz_CriaMatrizVazia(intiLinha,intiColuna,int*piFlagErro)*/
/*@Descricao:Construtorcriaumamatrizvaziadedimenso(iLinhaxiColuna)*/
/*@Parametro:_E_iLinhacorrespondeaonmerodalinhadoelemento*/
/*_E_iColunacorrespondeaonmerodacolunadoelemento*/
/*_S_piFlagErroretornaoestadofinaldafuno*/
/*@Retorno:*tMatrizmatrizasermanipulada*/
/*@Erro:ERRO_SUCESSOfunoexecutadacomsucesso*/
/*ERRO_MEMORIA_INSUFICIENTEsemmemriaparaalocaramatriz*/
/************************************************************************************/
*tMatrizMatriz_CriaMatrizVazia(intiLinha,intiColuna,int*piFlagErro);

/************************************************************************************/
/*@Nome:Matriz_Destroi(Matriz*pMatriz,int*piFlagErro)*/
/*@Descricao:Destrutorfunoquedestroiaestruturadamatriz*/
/*@Parametro:_E_pMatrizmatrizaserdestruida*/
/*_S_piFlagErroretornaoestadofinaldafuno*/
/*@Erro:ERRO_SUCESSOfunoexecutadacomsucesso*/
/*ERRO_PONTEIRO_NULOponteiropMatriznulo*/
/************************************************************************************/
voidMatriz_Destroi(tMatriz*pMatriz);

/**************************************************************************************/
/*@Nome:Matriz_ZeraElemento(Matriz*pMatriz,intiLinha,intiColuna,int*piFlagErro)*/
/*@Descricao:funoquezeraoelemento(iLinha,iColuna)damatriz*/
/*@Parametro:_E_pMatrizmatrizasermanipulada*/
/*_E_iLinhacorrespondeaonmerodalinhadoelemento*/
/*_E_iColunacorrespondeaonmerodacolunadoelemento*/
/*_S_piFlagErroretornaoestadofinaldafuno*/
/*@Erro:ERRO_SUCESSOfunoexecutadacomsucesso*/
/*ERRO_ENDERECO_INVALIDOelementoforadolimitedamatriz*/
/*ERRO_PONTEIRO_NULOponteiropMatriznulo*/
/**************************************************************************************/
voidMatriz_ZeraElemento(tMatriz*pMatriz, intiLinha,intiColuna,int*piFlagErro);

A lgica e a definio explcita do tipo devem ser implementadas no arquivo .c:

/*Matriz.c*/
#include<stdlib.h>
#includeBiblioErro.h
#includeMatriz.h
structMatriz{
intiLin;
intiCol;
float*fVet;
};
/************************************************************************************/
/*@Nome:Matriz_CriaMatrizVazia(intiLinha,intiColuna,int*piFlagErro)*/
/*@Descricao:Construtorcriaumamatrizvaziadedimenso(iLinhaxiColuna)*/
/*@Parametro:_E_iLinhacorrespondeaonmerodalinhadoelemento*/
/*_E_iColunacorrespondeaonmerodacolunadoelemento*/
/*_S_piFlagErroretornaoestadofinaldafuno*/
/*@Retorno:*tMatrizmatrizasermanipulada*/
/*@Erro:ERRO_SUCESSOfunoexecutadacomsucesso*/
/*ERRO_MEMORIA_INSUFICIENTEsemmemriaparaalocaramatriz*/
/************************************************************************************/
*tMatrizMatriz_CriaMatrizVazia(intiLinha,intiColuna,int*piFlagErro){
Matriz*pMatriz=(tMatriz*)malloc(sizeof(tMatriz));
if(pMatriz==NULL){
*piFlagErro=ERRO_MEMORIA_INSUFICIENTE;
returnNULL;
}
pMatriz>iLin=iLinha;
pMatriz>iCol=iColuna;
pMatriz>fVet=(float*)malloc(iLinha*iColuna*sizeof(float));
if(pMatriz>fVet==NULL){
/*Senohmemriasuficienteparamatriz,
desalocaramemriaanteriormentealocada*/
free(pMatriz);
*piFlagErro=ERRO_MEMORIA_INSUFICIENTE;
returnNULL;
}
*piFlagErro=ERRO_SUCESSO;
returnpMatriz;
}

/************************************************************************************/
/*@Nome:Matriz_Destroi(Matriz*pMatriz,int*piFlagErro)*/
/*@Descricao:Destrutorfunoquedestroiaestruturadamatriz*/
/*@Parametro:_E_pMatrizmatrizaserdestruida*/
/*_S_piFlagErroretornaoestadofinaldafuno*/
/*@Erro:ERRO_SUCESSOfunoexecutadacomsucesso*/
/*ERRO_PONTEIRO_NULOponteiropMatriznulo*/
/************************************************************************************/
voidMatriz_Destroi(tMatriz*pMatriz,int*piFlagErro){
if((pMatriz>fVet!=NULL)&&(pMatriz!=NULL)){
free(pMatriz>fVet);
free(pMatriz);
*piFlagErro=ERRO_SUCESSO;
}

else{
*piFlagErro=ERRO_PONTEIRO_NULO;
}
}

/**************************************************************************************/
/*@Nome:Matriz_ZeraElemento(Matriz*pMatriz,intiLinha,intiColuna,int*piFlagErro)*/
/*@Descricao:funoquezeraoelemento(iLinha,iColuna)damatriz*/
/*@Parametro:_E_pMatrizmatrizasermanipulada*/
/*_E_iLinhacorrespondeaonmerodalinhadoelemento*/
/*_E_iColunacorrespondeaonmerodacolunadoelemento*/
/*_S_iFlagErroretornaoestadofinaldafuno*/
/*@Erro:ERRO_SUCESSOfunoexecutadacomsucesso*/
/*ERRO_ENDERECO_INVALIDOelementoforadolimitedamatriz*/
/*ERRO_PONTEIRO_NULOponteiropMatriznulo*/
/**************************************************************************************/
voidMatriz_ZeraElemento(tMatriz*pMatriz,intiLinha,intiColuna,int*piFlagErro){
intiIndice;/*ndicedoelementonovetor*/
if(pMatriz!=NULL){
if(iLinha<0||iLinha>=pMatriz>iLin||iColuna<0||iColuna>=pMatriz>iCol){
*piFlagErro=ERRO_ENDERECO_INVALIDO;
}
else{
iIndice=(iLinha1)*pMatriz>iCol+iColuna;
pMatriz>fVet[iIndice]=0;
*piFlagErro=ERRO_SUCESSO;
}
}
else{
*piFlagErro=ERRO_PONTEIRO_NULO;
}
}

Desta forma, o usurio receber a biblioteca compilada (arquivo .o) e ter acesso apenas ao
arquivo .h onde foi definido o ponteiro opaco para o TAD Matriz. Essa prtica proporciona abstrao
e encapsulamento de dados e, portanto, deve ser adotada.
11. Identao
Identar o cdigo com espaos (e no tab) preferencialmente.

Alguns editores identam de forma ruim quando utiliza-se a tecla tab.

Preferir utilizar quatro espaos em branco (sugesto).

Evitar muito nveis de identao. No mximo 5, contando do nvel inicial da funo.

Verificar se no possvel quebrar em mais de uma rotina (funo).

10