Good occasion to thank all those who have provided significant help with docstrings.
On Dec 3, 12:16 am, Yarko Tymciurak <resultsinsoftw...@gmail.com> wrote: > On Dec 2, 11:42 pm, mdipierro <mdipie...@cs.depaul.edu> wrote: > > > On Dec 2, 11:11 pm, Yarko Tymciurak <resultsinsoftw...@gmail.com> > > wrote: > > > > On Dec 2, 11:00 pm, mdipierro <mdipie...@cs.depaul.edu> wrote: > > ...... > > Massimo - I snipped your mail, as it was getting so long ..... > hmmm.... > > > Yarko, please try write shorter emails. I find myself spending a > > considerable amount of my life reading your emails. I enjoy it but I > > cannot afford it. ;-) > > Then just don't read them! Good heavens, would you go to Lamborghini > and tell them to not make Lamborghini's because you cannot afford > them? Really! > > I am somewhere between these two: > > [1] All arguments should be made as short as possible (and no > shorter) -- I think this was attributed to Albert Einstein; > [2] If I had more time, I would have made the documentation shorter > -- This I first saw from Jon Bentley of Bell Labs; > > I suppose this "time" thing is why there are so very, very few > comments in gluon? Which makes some of the design .... not always > clear... and sometimes the bugs are because of this... which uses up > more of your time... you get my point => this is a case of failing > #1; > > I tried to put in Sphinx documentation some time ago, and gave up > because there wasn't enough there to quickly capture.... and I failed > because of [2]; > > I'll write shorter notes, if you comment your code more / more > informatively. If I write a tool to extract JUST the comments and > declarations (signatures of classes and functions) I want to be able > to SEE and FEEL the design (and even from this level modify or extend > it). > > Anyone who would like to see this "outline" of principle comments from > web2py let me know - I'll send you a script to extract. > > We used to have, in C code (from kernel code, on up) a convention that > "major" comments were written thus: > > /* > * This is a main comment, in a comment block > */ > > /* this is a minor comment - on a lne by itself, single line, no code > with it */ > > foo = bar(); /* this is a trrivial comment - annotates the code in > a minor way */ > > and so the comment (e.g. structure / logic) extraction tool could pick > out levels for you - major, major+minor, all (not usually desired). > > We could do the same with: > > " > Really major comments - might want to avoid ouput, since they may be > docs, or doctests > " > > ## > # Like main comment above > ## > > # like minor comment above, etc... > > Then I won't have to waste so much time in the debugger figuring out > what some peice is doing from it's behavior - I will be able to read > it's intent (and not have to guess or argue about it - and also then > will be able to write much, much shorter posts). > > Deal? > > Kindly, > - Yarko > > > > > Massimo > > -- You received this message because you are subscribed to the Google Groups "web2py-users" group. To post to this group, send email to web...@googlegroups.com. To unsubscribe from this group, send email to web2py+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/web2py?hl=en.
