On Thu, Nov 15, 2012 at 09:52:49AM -0500, Sanford Staab(Gmail) wrote: > In the case of openssl, a big gain would be to simply document the command > line interface better and create a doc centric forum for people to add their > lessons learned filed around the particular feature area of openssl. > WORKING EXAMPLES would be REAL cool. Does anyone on this alias want to let > me or others know how we can update the docs somehow?
I concurr. Life is too short for each of us to have to plod the same ugly goat trail to make it work. > > -----Original Message----- > From: Carlo Wood > Sent: Thursday, November 15, 2012 8:31 AM > To: openssl-users@openssl.org > Subject: Re: I can't believe how much this sucks > > 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 > > ______________________________________________________________________ > OpenSSL Project http://www.openssl.org > User Support Mailing List openssl-users@openssl.org > Automated List Manager majord...@openssl.org ______________________________________________________________________ OpenSSL Project http://www.openssl.org User Support Mailing List openssl-users@openssl.org Automated List Manager majord...@openssl.org
