Boas práticas para o desenvolvimento de software – Parte II

Boas práticas para o desenvolvimento de software - Parte II. São apresentadas ideias para organizar e melhorar o seu software.
boas práticas
Este post faz parte da série Boas práticas para o desenvolvimento de software. Leia também os outros posts da série:

Nos segmentos anteriores da série Boas práticas para o desenvolvimento de software, foram apresentados: uma introdução ao assunto, onde é mostrada a necessidade de boas práticas como uma forma de melhorar a produtividade na geração e manutenção de software e de qualidade desse software gerado e a primeira parteonde é abordada a ideia de se desenvolver o software de forma estruturada, porém utilizando alguns métodos de encapsulamento de dados.   

Nessa segunda parte vamos abordar mais alguns aspectos envolvendo ideias para organizar e melhorar o seu software. Aí vão mais algumas sugestões:

Cabeçalho de sub-rotinas

Quando for escrever uma nova sub-rotina para o seu programa, é de grande ajuda você escrever um cabeçalho destacado, conforme se pode ver na Figura 1, listando nos comentários o nome da sub-rotina, uma pequena descrição das operações que ela realiza, uma lista de variáveis de entrada, com descrição se necessário e uma descrição das variáveis de saída.

Figura 1: Exemplo de um cabeçalho de sub-rotina

Esse código é o cabeçalho de uma das sub-rotinas mostradas na primeira parte dessa série. As vantagens são óbvias. Quando no decorrer do desenvolvimento do programa você necessitar de  uma rotina que realiza determinada função, você pode conferir se entre as que você já escreveu tem alguma, só lendo a descrição do cabeçalho. Depois, esse esquema facilita a depuração durante uma eventual manutenção após um longo período. O destaque realizado em torno do cabeçalho, facilita encontrar as rotinas quando se vasculha o programa.

Escolher nomes significativos para variáveis e rotinas

Dar nomes às variáveis, sub-rotinas, constantes, etc. que façam a relação dessas variáveis com sua função, destino, etc. No exemplo que temos no código acima:

  • vEscreveE2PROM (unsigned char nEndereço, unsigned char nDado);
  • bFlagDeErro = DESLIGA.
 
 
No código completo, pode-se reparar que algumas variáveis estão escritas em letras maiúsculas, por exemplo, LIGA, DESLIGA, SDA e SCL.  

 

OBS: Se você quiser ver a sub-rotina completa, abra a janela a seguir:

 

 

No início do programa ou então no arquivo  *.h do projeto, foram definidas as constantes com esses nomes, SCL e SDA fazendo referência aos sinais de controle de uma EEPROM serial com comunicação por dois fios. Isso você pode conferir no extrato do programa exibido na Figura 2 abaixo.
 

 Figura 2: Extrato das definições de mnemônicos

 

Essas constantes também estão associadas a bits específicos de um Port do microcontrolador. Nomear uma variável de SDA é bem mais inteligível do que P2_5, por exemplo (Port 2, bit 5). As constantes LIGA e DESLIGA foram definidas como ’1′ e ’0′ respectivamente. Isso tudo nos leva ao próximo tópico desse artigo: A polêmica notação húngara.

 

Para auxiliar na compreensão você pode consultar a Figura 3, onde se vê as conexões entre a CPU e a EEPROM correspondentes a esse programa.  
 
 
boas-práticas-cpu_eeprom
Figura 3: Detalhes do esquema com as conexões entre a CPU e a EEPROM
 
 
 
Na Figura 4,  está ilustrada a primeira página do manual de uma dessas EEPROMs seriais.
 
boas-práticas- eeprom-comunica-2-fios
Figura 4: Manual de uma EEPROM serial

Boas práticas para o desenvolvimento de software – Notação Húngara

Segundo a definição do Wikipedia:

Notação Húngara, criada por Charles Simonyi, visa a facilitar o reconhecimento do tipo de variável num programa. O nome foi dado a partir de uma brincadeira comum entre os primeiros a conhecer a notação que a achavam estranha, fazendo o seguinte comentário: “É tão estranho que até parece húngaro”. Quando se confronta com a necessidade de dar um novo nome a uma variável num programa, o programador deve tomar alguns cuidados ao tomar essa decisão:

  • Nome mnemônico – é aquele que facilita a lembrança do significado pelo programador;
  • Nome sugestivo – é aquele em que outros podem ler o código;
  • Formato – é sempre visto como uma ideia estética, tendo sempre uma informação eficiente do programa teste;
  • Velocidade de decisão – não se pode perder muito tempo para ponderar um simples nome, pois não haverá tempo para editar e digitar nomes de variáveis longos.

A adoção deste critério de nomeação é bastante prática e intuitiva, sendo a ideia básica nomear todos os tipos de quantidades, visando-se a simplificar o entendimento do programa. Algumas vantagens deste método:

  • Os nomes em mnemônicos são utilizados num senso muito específico. Se alguém se lembrar da quantidade ou como os nomes foram construídos através de outros tipos, o nome poderá ser lido facilmente.
  • Os nomes sugestivos são muito bons. É capaz de se mapear qualquer nome dentro do seu tipo, tendo as informações necessárias para construir sua interface e utilizar de maneira correta sua quantidade.
  • Os nomes devem ser consistentes, porque eles são construídos pelas mesmas regras.
  • A decisão por um nome deve ser mecânica e rápida.
  • As expressões nos programas devem ser sugestivas, facilitando a leitura e acompanhamento do programa.

Com o objetivo de fazer listas intuitivas de se ler, os programas baseados na plataforma Windows utilizam a Notação húngara para gerar estas listas. As regras para se utilizar a Notação húngara são:

  • Os tipos definidos e/ou criados devem aparecer em letras maiúsculas;
  • constantes e “Macros” que vêm definidas em arquivos inclusos aparecem também em letras maiúsculas;
  • Funções e nomes estruturados começam com letras maiúsculas. Nenhuma marca abaixo são utilizadas para nomes, exceto para os casos que se encontrem nas duas regras anteriores;
  • Nomes de objetos começam com uma ou mais letras maiúsculas, indicando o tipo do objeto.

A tabela abaixo indica os tipos de indicadores mais utilizados na Notação húngara:

NOMEDESCRIÇÃO
sString
szAponta o primeiro caracter da terminação zero da string
stPonteiro da string, o primeiro byte é contado dos caracteres
hhandle (título)
msgMessage
fnfunction (usada com pointer)
cchar (8 bits)
byunsigned char (byte or uchar – 8 bits)
nInt
bBoolean (verdadeiro ou falso)
fFlag (boolean, logical). Se qualificado é usado, pode descrever o estado verdadeiro do flag. Exceção às constantes.
uinteger
wWord
chChar, com texto ASCII
llong int (32 bits)
dwunsigned long int (dword – 32 bits)

Essa notação é um pouco confusa e complicada e é alvo de muita polêmica sobre a sua eficiência e necessidade de uso. Na minha opinião e na minha experiência, essa notação, ou outra qualquer mais simplificada que você queira utilizar, facilita muito o reconhecimento das variáveis e funções, não só pelo nome,  como também o tipo, por exemplo bit, byte, inteiro, float, string, long, etc. Pense no assunto, experimente utilizar, eu tenho certeza que em pouco tempo você vai gostar do resultado final.

Se você tiver sugestões e críticas, por favor faça-as que serão muito bem vindas.

 

Outros artigos da série

<< Boas práticas para o desenvolvimento de software – Parte I
Notificações
Notificar
guest
9 Comentários
recentes
antigos mais votados
Inline Feedbacks
View all comments
Emerson Beserra
Emerson Beserra
19/05/2014 07:48

só uma sugestão, os comentários de cabeçalho poderiam ser feitos no padrão doxygen para geração de documentação dos fontes

Henrique Frank Werner Puhlmann
Reply to  Emerson Beserra
19/05/2014 08:55

É uma ótima sugestão, Emerson.
Eu tenho a impressão que o pessoal do Embarcados já está preparando um artigo especial sobre o Doxygen para o pessoal conhecê-lo melhor. Abraço!

Cesar Junior
Cesar Junior
15/05/2014 11:18

Muito bom o post, dicas muito boas para quem está começando em embarcados agora como eu.
Obrigado!

Marcelo Rodrigo Dos Santos Andriolli
Marcelo Andriolli
14/05/2014 09:18

Bacana o post Henrique! Quem sabe um cabeçalho de subrotina com o formato doxygen, seria interessante!

Henrique Frank Werner Puhlmann
Reply to  Marcelo Andriolli
14/05/2014 09:56

Certamente que sim, Marcelo.

O importante é que se documente o software o suficiente para facilitar tanto seu desenvolvimento quanto sua manutenção. Quem já precisou corrigir problemas depois de alguns anos, sabe como isso faz a diferença.

Abraço!

Marcelo Rodrigo Dos Santos Andriolli
Marcelo Andriolli
Reply to  Henrique Frank W. Puhlmann
17/05/2014 15:09

Com certeza Henrique! É indispensável um código documentado!

trackback
01/06/2015 00:34

[…] Boas práticas para o desenvolvimento de software – Parte II […]

trackback
14/05/2014 17:08

[…] Boas práticas para o desenvolvimento de software – Parte I – É abordada a ideia de desenvolver seu software de forma estruturada, porém utilizando alguns métodos de encapsulamento de dados. […]

trackback
14/05/2014 17:01

[…] e manutenção do seu software . Vou comentar um pouco sobre a notação húngara. Parece grego? (Boas práticas para o desenvolvimento de software – Parte […]

WEBINAR

Visão Computacional para a redução de erros em processos manuais

DATA: 23/09 ÀS 17:00 H