Codigo C - Questao de estética e praticidade

Programação C em geral

Moderadores: 51, guest2003

Codigo C - Questao de estética e praticidade

Mensagempor jeanfernandes » 02 Ago 2009 18:30

Prezados

Código: Selecionar todos
/*******************************************************************************
  * Function
      se95_read_device
  * Input Parameters
      addr - register address
         *msg - device struct pointer
  * Return
      ever true
  * Description
      description
  * Revision
      1.0
  * Date
      30/07/2009
  * Author
      Jean P. Fernandes
  * History
      Initial version
*******************************************************************************/
u08
se95_read_device(u08 addr, t_se95 *msg)
{
   data u08       task       = 1;
   data u08       check    = TRUE;
   data u08      value      = 0;
   data u16      temp      = 0;

   msg->error    = TRUE;
   msg->neg      = FALSE;
   msg->value    = 0x0000;

   check = TRUE;
   while ((check == TRUE) && (task < 9))
   {
      switch (task)
      {

         case 1:   // start condition
            check = se95_start();
            task++;
            break;
         case 2:   // send device write addr
            check = se95_write_byte(SE95_ADDR_WR);
            task++;
            break;
         case 3:   // send temp reg addr
            check = se95_write_byte(addr);
            task++;
            break;
         case 4:   // start condition
            se95_start();
            task++;
            break;
         case 5:   // send device read addr
            check = se95_write_byte(SE95_ADDR_RD);
            task++;
            break;
         case 6:   // read the msb byte
            value = se95_read_byte(SE95_ACK);
            temp    = (u16)value << 8;

            task++;
            break;
         case 7:   // read the lsb byte
            value = se95_read_byte(SE95_NAK);
            temp &= 0xFF00;
            temp += value;            
            task++;
            break;
         case 8:   // stop condition
            msg->value = temp;
            check = se95_stop();
            task++;
            break;
      }
   }

   msg->error    = (1 - check);
   msg->neg       = task;

   SE95_SCL_ON;
   SE95_SDA_ON;

   return TRUE;

}


Normalmente eu uso a declaração da função depois do cabeçalho comentado. Entretanto, com as IDE's com os recuros de collapse/expand, para efeito prático, os comentários ficariam melhor depois da declaração da função e antes de abrir a chave de função. Voce esconde todo o codigo e fica só a declaração da função, melhorando o andar da carruagem para as funções resolvidas....

...só fica meio estranho a estética do código com

tipo
funcao(tipo par)
/****.......

...
****/
{

//codigo

....
}

mas para collapse fica legal

tipo
funcao(tipo par)
(+)... <-- indica o bagulho em collapse

E ae ... sei que cada um tem um gosto, mas eh sempre bom ter a opiniao dos amigos....

:lol:

[/code]
Jean P. Fernandes - Eng. Eletrônico - (83) 2102-2116 - APEL - www.apel.com.br - Campina Grande - PB
jeanfernandes
Word
 
Mensagens: 539
Registrado em: 11 Out 2006 15:36
Localização: Campina Grande - PB

Mensagempor jeanfernandes » 02 Ago 2009 18:49

Acho meio que achei o melhor de dois mundos

Código: Selecionar todos
/*******************************************************************************
  * Function
       core_init
   * Input Parameters
       none
   * Return
       none
   * Description
       Core initialization
   * Revision
       1.0
   * Date
       11/03/2008
   * Author
       Jean P. Fernandes
   * History
       none

*******************************************************************************/
void
core_init(void)
{
   core_timer0_init();
   core_timer2_init();
   core_uart_init();
   core_ext1_init();
}



ficando "zipado" em ...

Código: Selecionar todos

/*******************************************************************************
  * Function
       core_init
(+)...
*******************************************************************************/
void
core_init(void)
(+)...



eheheeheh
Jean P. Fernandes - Eng. Eletrônico - (83) 2102-2116 - APEL - www.apel.com.br - Campina Grande - PB
jeanfernandes
Word
 
Mensagens: 539
Registrado em: 11 Out 2006 15:36
Localização: Campina Grande - PB

Mensagempor Sergio38br » 02 Ago 2009 19:17

Cara isto que chamo de monólogo..... :wink:

[ ]`s
Sergio
Avatar do usuário
Sergio38br
Word
 
Mensagens: 759
Registrado em: 22 Nov 2007 13:39
Localização: São Paulo - SP

Mensagempor jeanfernandes » 02 Ago 2009 19:52

Sergio é isso ae...
Por isso pedi a opiniao dos amigos.
Esquenta nao...
Jean P. Fernandes - Eng. Eletrônico - (83) 2102-2116 - APEL - www.apel.com.br - Campina Grande - PB
jeanfernandes
Word
 
Mensagens: 539
Registrado em: 11 Out 2006 15:36
Localização: Campina Grande - PB

Mensagempor chipselect » 03 Ago 2009 07:38

Eu sempre tento usar a sintaxe do javadoc...

Na declaração das funções eu coloco:
/**
* Descrição da Função
*
* @param parametro 1
* @param parametro 2
* @return retorno
*
* @link -> outros tótipos relacionados
**/
<tipo de retorno> <nome da função> (<parâmetros>);


Na implementação da função fica assim:


/**
* @{inheritDoc}
**/
<tipo de retorno> <nome da função> (<parâmetros>){
//corpo da função
}


O javadoc no eclipse funciona perfeito, e tem um recurso que você gera uma página de "help" em html com toda sua documentação. O code assist apresenta esse doc do javadoc, permitindo inclusive navegar entre os links, mas tudo isso é para java.

Ainda tô procurando uma ferramenta tipo javadoc que funcione com c/c++.
chipselect
Word
 
Mensagens: 744
Registrado em: 16 Out 2006 18:50

Mensagempor xultz » 03 Ago 2009 09:16

Eu gosto de documentação bem clara, do tipo
* Description
description

:P
98% das vezes estou certo, e não estou nem aí pros outros 3%.
Avatar do usuário
xultz
Dword
 
Mensagens: 3001
Registrado em: 13 Out 2006 18:41
Localização: Curitiba

Mensagempor Sergio38br » 03 Ago 2009 11:09

Como ficaria um projetos com diversos módulos, arquivos .c, .h, os comentarios seriam no main ou em seus diversos modulos, então quem esta abrindo o projeto é obrigado a abrir cada modulo para verificar?

[ ]'s
Sergio
Avatar do usuário
Sergio38br
Word
 
Mensagens: 759
Registrado em: 22 Nov 2007 13:39
Localização: São Paulo - SP

Mensagempor chipselect » 03 Ago 2009 13:28

Sergio

Eu coloco as doc nos .h e .c.

Se o projeto for em C:
.h recebe os protótipos das "funções públicas" e .c recebe os protótipos das "funções privadas" ou "funções auxiliares".

Também tento seguir uma regra de nomenclatura, para minimizar os conflitos de nomes.

Quando dá tempo, eu tento gerar uma documentação (html, pdf) sobre as funções do "módulo", nisso o javadoc ajuda muito.

Em C++ documentação é tudo no .hpp.

No .cpp fica os comentários para implementação/manutenção do módulo.

Isso obriga o "usuário do módulo" a abrir o .h, caso não esteja disponível nenhuma doc em html, pdf ou outro, mas foi o meio mais prático e rápido que achei.

Também não fico colocando data de alteração em cada função, isso eu deixo pro cvs gerenciar pra mim, pois no commit do cvs, basta colocar a descrição das alterações efetuadas. Isso ajuda a deixar o código mais limpo.
chipselect
Word
 
Mensagens: 744
Registrado em: 16 Out 2006 18:50

Mensagempor msamsoniuk » 03 Ago 2009 14:11

um codigo bem escrito nem precisa de comentarios! :D

xultz escreveu:Eu gosto de documentação bem clara, do tipo
* Description
description

:P
Avatar do usuário
msamsoniuk
Dword
 
Mensagens: 2935
Registrado em: 13 Out 2006 18:04

Mensagempor styg » 04 Ago 2009 09:19

Tao jean, eu tb faço assim no Keil, quando dou o colapse ele fica soh o cabeçalho da função e o protótipo, o código entre as chaves é suprimido.
Lucas
Avatar do usuário
styg
Word
 
Mensagens: 799
Registrado em: 16 Out 2006 08:24
Localização: Floripa abaixo de zero.

Mensagempor chrdcv » 05 Ago 2009 01:59

chipselect escreveu:Ainda tô procurando uma ferramenta tipo javadoc que funcione com c/c++.


Aqui está camarada: http://www.stack.nl/~dimitri/doxygen/

Jean, bacana o header dos seus fontes hein? Parabéns pelo critério e formatação! Geralmente faço meus headers meio que "nasco" usando um
script em awk...

christian
Avatar do usuário
chrdcv
Dword
 
Mensagens: 1580
Registrado em: 13 Out 2006 14:13

DALHE TIO QUICK

Mensagempor bzero » 06 Ago 2009 14:17

:D

Marcelo Samsoniuk escreveu:um codigo bem escrito nem precisa de comentarios! :D

xultz escreveu:Eu gosto de documentação bem clara, do tipo
* Description
description

:P
bzero
Bit
 
Mensagens: 5
Registrado em: 02 Abr 2007 15:22

Re: DALHE TIO QUICK

Mensagempor msamsoniuk » 06 Ago 2009 14:44

codigo bem escrito com controle de versao, entao, fica tao claro que o cara que vai ver o codigo nao precisa nem saber ler e escrever! ele entende o codigo soh pelas figurinhas que formam com as arvores dos branches e merges :)

bzero escreveu::D

Marcelo Samsoniuk escreveu:um codigo bem escrito nem precisa de comentarios! :D

xultz escreveu:Eu gosto de documentação bem clara, do tipo
* Description
description

:P
Avatar do usuário
msamsoniuk
Dword
 
Mensagens: 2935
Registrado em: 13 Out 2006 18:04

Mensagempor proex » 06 Ago 2009 14:56

Doce ilusão ehehhehehheheh


.
proex
Dword
 
Mensagens: 2101
Registrado em: 11 Out 2006 14:05
Localização: São Paulo

Mensagempor msamsoniuk » 06 Ago 2009 17:08

ou será uma triste realidade? :)
Avatar do usuário
msamsoniuk
Dword
 
Mensagens: 2935
Registrado em: 13 Out 2006 18:04

Próximo

Voltar para Visual C++/C/C++/C#

Quem está online

Usuários navegando neste fórum: Nenhum usuário registrado e 0 visitantes

x