+1 to more comments in code :) Didn't some smart programmer guy write that at least 50%, if not more, of lines of code should be comments describing what the code does and WHY it does it ?
-Thadeus On Thu, Dec 3, 2009 at 12:46 AM, mdipierro <mdipie...@cs.depaul.edu> wrote: > 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<web2py%2bunsubscr...@googlegroups.com> > . > For more options, visit this group at > http://groups.google.com/group/web2py?hl=en. > > > -- 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.
