On Tue, 13 Nov 2012 14:11:17 -0700 t...@terralogic.net wrote: > This is just a NORMAL way for a programmer to work IMHO. I HATE > comming into undocumented code years after its been written and IMHO > its a big booby trap because its very easy to miss something and that > creates hard to find bugs. Really criptic error messages don't help > this. I've looked in the OOS community and there are attempts to put > together systems and one I looked at was OXYGEN.
I concur. When I was 12, I wrote compact code with only single character variables and no documentation. For some reason I was able to have thousands of code lines all in my head at once and I had no idea why I'd need to add documentation. When I got older, I started to use more descriptive variable and function names, mostly for the purpose of being able to 'grep' (reg.exp) them in large code. At some point I completely did away with abbreviations and only used complete English words, discovering that code is incredibly better to understand when the variable names express exactly what they mean (to the point that it avoids bugs). I still didn't see the point in documentation however: the code explained itself as if it was English. Only when my memory started to get worse and I couldn't remember Megabytes of code anymore, especially when my code became so complex that I had to use Object Orientation because it was impossible to keep an overview, I started to document code. The funny thing is: I did this mostly because I knew that a year later I wouldn't be able to understand it myself anymore if I didn't; not because I thought that anyone else might need it. Now, after more than 30 years of coding experience I have reached the same conclusion as terra wrote: Code is only as useful as it's documentation. Don't bother to write code without good COMPLETE documentation as it's worthless: only you, the developer (with a good memory on top of that) will think it's trivial and usable. Everyone else will not be able to use it. > > http://www.stack.nl/~dimitri/doxygen/ > > > I have no idea at this time how useful this would be. > > > Perhaps the best we might be able to do on the user side is a wiki > and perhaps one exists. > > > I did a google search on this. > > https://help.ubuntu.com/community/OpenSSL > > ^ I did find this and I did not look very hard. Maybe there is > something better. If there is then it doesn't come up in the 1st > hits google finds. > > > So I think we can do much better. > > Just my 2 cents. -- Carlo Wood <ca...@alinoe.com> ______________________________________________________________________ OpenSSL Project http://www.openssl.org User Support Mailing List openssl-users@openssl.org Automated List Manager majord...@openssl.org
