Jump to content

Documentar código


terramoto
 Share

Recommended Posts

Boas, nunca documentei embora ache que dê muito jeito e queria saber se alguém me podia explicar a lógica/passos que segue a documentação de um código, se documentam cada linha de código, se documentam a função só, se escrevem o que a função faz por alto ou se explicam cada passo na função, como por ex. "Esta função limpa vidros" "Esta função molha o pano no detergente, extrai a água e passa no vidro", se se identificam em todos os ficheiros ou só no principal. Se puderem pôr um exemplo do que consideram uma documentação exemplar, melhor.

A great truth is a truth whose opposite is also a great truth.

Link to comment
Share on other sites

Depende do uso que dás aos comentários.

Normalmente eu documento bem os .h, para poderem ser facilmente usados por alguém. Isto inclui descrição de estruturas, variáveis globais ou constantes, etc., bem como uma descrição detalhada em cada protótipo de função (incluindo objectivo da função, parâmetros de entrada e retorno). Tento fazer algo à laia do que vês no man (as mais curtas).

Dentro do código em si, documento apenas passos críticos, algo como um mínimo algorítmo, para me guiar a mim próprio.

Link to comment
Share on other sites

Na minha opinião, os comentários devem ser utilizados apenas para explicar processos e workflows.

As funções/métodos e variáveis/classes deverão ter nomes "self-explanatory" o que aliado a uma correta refatorização do código não exigirá comentários adicionais, exceto em casos pontuais.

Link to comment
Share on other sites

Nem mais. No meu caso, todos os métodos e classes têm um nome bastante claro que identifica imediatamente o que aquele pedaço de código faz. E o refactor é muito importante. Antes não ligava muito a isso, mas agora sinto uma enorme necessidade para identificar os pedaços de código.

Link to comment
Share on other sites

/*Força o processo a fazer um sleep de secs segundos e nanosecs nanosegundos
* Usa o relógio monotónico. É reentrante (se o sleep for interrompido antes do tempo, a função volta a dormir o tempo restante).
* Retorna 0 se executada com sucesso, -1 em caso de erro (valores de tempo negativos).
* Caso o campo nanosecs tenha um valor superior a 1 segundo, é convertido correctamente (ClockSleep(0,1100000000) ao equivalente 
* ClockSleep(1,100000000))
* */
int ClockSleep(int secs,long int nanosecs);

Tens aqui um exemplo do que eu faço nas bibliotecas que partilho com outros programadores da empresa. Mais uma vez, só me dou a este trabalho para bibliotecas que sejam partilhadas, o meu código não tem este detalhe porque sei o que faz. Também só o faço no ou nos .h que é suposto serem incluidos pelos outros.

Comecei a fazer isto à conta de andarem sempre a interromper-me, "olha, o que é que esta função retorna? Olha, testas esta condição na função?"... 

Link to comment
Share on other sites

Create an account or sign in to comment

You need to be a member in order to leave a comment

Create an account

Sign up for a new account in our community. It's easy!

Register a new account

Sign in

Already have an account? Sign in here.

Sign In Now
 Share

×
×
  • Create New...

Important Information

By using this site you accept our Terms of Use and Privacy Policy. We have placed cookies on your device to help make this website better. You can adjust your cookie settings, otherwise we'll assume you're okay to continue.