Re: Good documentation
- Posted by Shian_Lee Apr 01, 2015
- 2133 views
I frequently find myself writing convoluted code to do something, and all the while having the suspicion that "there must be a better way to do this" - most likely with only one or two lines of code.
True.
To be honest - I usually look at the example before I read the description.
I remember once, 20 years ago, a guy from University called me and asked for help in calculating a communication checksum. This Russian guy told me that he already tried everything - but he can't figure out what's wrong.
I told him the formula on the phone - it was a single short line.
Same thing happened to me with calculating PID (Proportional-Integral-Derivative) for controllers - you can read 10 books and still don't understand how to do it. But it takes 20 lines of Euphoria code to explain everything.
i.e. from my experience, a short example code can describe the behavior of a function much better then a long description. As much as the function is more complicated - a code example is more helpful.
These days I would not be able to use many Euphoria functions without Wikipedia. I don't think it's right. There must be a short code example attached to the description. A real-life example that I may want to copy/paste to my own program...
