Code documentation

[Leonardo Giordani]

I want to suggest everyone writing code to document it, especially to document 
functions. This is REALLY important not only for a new Krita hacker (like me) 
but always for long time developers.

Documenting things after they are done is, in my personal experience, very 
boring and will never be done. So begin to do it now before Krita becomes 
really big.

I do not know if KOffice or KDE is using some automatic documentation tool: 
I'm using doxygen for my work and it is really a big improvement and help for 
me and my co-workers.

I will also suggest to give some constraints for hand-witten documentation 
(doc/ directory); nothing revolutionary, just a bit of order: all text files 
ending with ".txt" or all text files ending with nothing, author name and 
mail in each document, etc...

I know that documenting is boring, especially when you are not used to it: but 
I experienced that trying to explain to someone what you are doing is a good 
way to better understand it. Not to mention that after 2-3 months common 
people do forget why they wrote that piece of code in that manner.

What do you think about?

-- 
Leonardo Giordani

Tele-Rilevamento Europa - T.R.E. s.r.l.
a POLIMI spin-off company
Via Vittoria Colonna, 7
20149 Milano - Italia
tel.: +39.02.4343.121
fax: +39.02.4343.1230
e-mail: leonardo.giordani (at) treuropa.com
web: www.treuropa.com