Agree re: code commenting. When I did my little bit of work with SQLHtml, it had almost no comments that describe the intent of the code. This made it much harder to figure out what affects what. This resulted in a lot of unnecessary unintended results in my code that I only found through the testing process.
Comments in the code I see as the Achilles' heel of this project at the moment. Also, is there a set of design specifications somewhere for this project? One of the first things I remember reading/hearing is that it was built from the ground up... On Dec 2, 10:16 pm, 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.
