[seek-dev] Re: [kepler-dev] Query Builder Code Review

Mon Aug 16 13:52:20 PDT 2004

Indeed, email is not always such a great forum for discussion...
I had read your message as divisive as well...  I think we both
feel strongly about this issue, and I apologize if my tone came
across as aggressive.

In the Ptolemy Project, we've had quite a struggle to get a style
guide adhered to... In practice, there have been contributors who
simply refused.  Their code tends to not get used and extended much,
and in many cases, has been dropped...  In some cases, either Christopher
or I rewrite the code, which a slightly annoying thing to have to do
(only slightly, because invariably code improves when someone makes
a careful editing pass, so there is some value in this).

Edward

At 08:48 AM 8/16/2004 -0500, Rod Spears wrote:
>Edward,
>
>I was merely trying to have discussion about the Kepler style guide. I 
>think your previous remarks were very divisive and inappropriate.
>
>Rod
>
>
>Edward A Lee wrote:
>>
>>Well, it seems very unlikely we'll ever agree here...
>>But I'm not giving up yet...
>>
>>Nobody is arguing for "every single file, module and/or
>>line of code looking exactly the same."  This is a polarizing
>>statement...
>>
>>I'm arguing that the relatively _unimportant_ properties be dealt
>>with consistently.
>>
>>Unfortunately, many programmers feel that where the curly braces
>>go is actually extremely important, and they love to argue about
>>it...  Too bad the same level of energy doesn't go into the important
>>things...
>>
>>Since coding style is really about the unimportant details,
>>it really has nothing to do with the "great commercial
>>software dilemma."  Whether software sells has little to do with
>>coding style...  I do believe that consistent coding style
>>promotes better software, but it's not because the coding
>>style makes the software look better.  It's because other
>>programmers on the team can more easily understand your code.
>>
>>Unfortunately, programmers who are so dogmatic about
>>unimportant issues are also likely to be dogmatic about important
>>ones, leading to "Frankenware," where everyone's contribution
>>has a different approach to concurrency, UI design, etc.
>>But that is a separate issue... On any collaborative project,
>>there are always people contributing who you wish were not
>>contributing...
>>
>>As for the idea that software is publication, I agree it's a radical
>>idea, and it will require a cultural change to take hold.  Cultural
>>changes are hard because there is a lot of dogma out there.
>>But I firmly believe that a good piece of software should be given
>>as much credibility for, say, tenure and promotion, as a good
>>series of papers...  At Berkeley it is, but I think this is relatively
>>rare... But culturally, we have a long way to go...
>>
>>As for "being as productive as possible," a real risk that Kepler
>>faces is an explosion of actors.  It is _not_ more likely to be used
>>if there are 10,000 actors in the library.  In fact, it's less likely
>>to be used. Having less than 100 well-designed actors with orthogonal
>>functionality, a coherent design (parameter names, port names, icon
>>designs, concurrency styles, granularity, ...) is what will make
>>it likely to be used.  This cannot happen if people aren't reading
>>each other's code.  Dogmatically refusing to follow a coding
>>style will discourage people from reading your code.
>>
>>More is not better...
>>
>>Edward
>>
>>
>>At 10:10 AM 8/13/2004 -0500, Rod Spears wrote:
>>>Sorry, I completely disagree. Writing software is certainly not the same 
>>>as publishing academic papers, and I think it is a fascinating thought 
>>>that Open Source could/should be considered a published work (sounds 
>>>like a discussion for another day).
>>>
>>>The reality of Open Source software is that if you put a lot of rules in 
>>>place you begin to limit the contributions, and that can be both good 
>>>and bad. There is certainly a desired level of quality and certainly 
>>>rules enforce that etc. etc. It was always a very difficult line to 
>>>walk; that is, to encourage contributions and then figure out "how" to 
>>>accept good work that may not fit exactly into the place it needs to fit.
>>>
>>>For example on Mozilla, the lack of every single file, module and/or 
>>>line of code looking exactly the same was never a problem for anyone 
>>>contributing to the project (I can't say it hurt productivity or the 
>>>quality of the code).
>>>
>>>This discussion and it is one I have had over and over, reminds me of 
>>>the great commercial software dilemma: Would a software engineer rather write:
>>>1) A perfectly engineered piece of software with no bugs, that doesn't 
>>>sell a dime.
>>>2) A rather odd piece of software with some questionable design and 
>>>architectural decisions that sells millions of copies.
>>>
>>>Certainly when writing commercial code, productivity ranks up there with 
>>>quality and all the other important aspects of creating great software. 
>>>I have seen this over and over again at the start of every project. The 
>>>engineers wrangle over coding style for weeks, nobody can agree but with 
>>>the higher levels of a style guide and in the end everyone gets worn 
>>>down and tired of the discussion. And then everyone writes their code 
>>>adhering to those general guidelines. I have yet to work on a commercial 
>>>project where the style guide for coding was dictated to the engineers.
>>>
>>>But Kepler (with contributions from SEEK) is not a commercial project. 
>>>So I guess I am at a loss to what its true priorities should be. My 
>>>priorities from the beginning have always been to create something that 
>>>people will actually use. To reach that goal I want to be as productive 
>>>as possible.
>>>
>>>In my personal opinion the Ptolemy style guide is quite unique and so 
>>>completely different than any other style guide I have used, that I find 
>>>it cramping my style (pun intended). So I did what I did for the sake of 
>>>getting my work done in a timely manner. (I could argue that because I 
>>>used a style guide that is more comfortable to myself, the quality of my 
>>>code is higher than if I struggled to "think" about my code as others 
>>>"think" about their code)
>>>
>>>I stand by what I said earlier about a general style guide with module 
>>>ownership and adapting to the style of the owner. It just seems odd that 
>>>I need to adapt to Ptolemy's style guide (which is basically what 
>>>Kepler's style guide is) and I doubt I will ever change a line of 
>>>Ptolemy code. Of course if I did, I would be more than happy to adhere 
>>>to its style completely.
>>>
>>>Rod
>>>
>>>
>>>Edward A Lee wrote:
>>>>
>>>>I would not take lightly making exceptions to the coding style...
>>>>Do it once, and everyone will feel free to do it, and you will not
>>>>have a coding style anymore...
>>>>
>>>>If you are publishing an academic paper, the editors of the journal
>>>>or conference proceedings get to decide on formatting issues. You
>>>>may have strong preferences about font, layout, reference styles,
>>>>header styles, etc., but you are not given a choice.  Should that
>>>>be changed?  I don't think so...
>>>>
>>>>Open source software should be viewed as form of publication.
>>>>The same principle should apply.
>>>>
>>>>Edward
>>>>
>>>>At 01:29 PM 8/12/2004 -0500, Rod Spears wrote:
>>>>>I agree that we should have a more "formal" meeting about our Kepler 
>>>>>coding standards. And I agree that one style does not fit all.
>>>>>
>>>>>But I still think we need to have some way to distinguish the scope of 
>>>>>a variable from its prefix. If folks don't like what I have proposed 
>>>>>then pick something, but it can be rather confusing without a prefix 
>>>>>(as I have found when reading some of the current code).
>>>>>
>>>>>As a suggestion consider this:
>>>>>On Mozilla we had a general set of guidelines, which most us followed, 
>>>>>but not everyone unfortunately. Of coarse, we could never agree on the 
>>>>>curly brace issue, but we did a fairly good job on deciding on file 
>>>>>names, interface file names, method argues, class data member names, 
>>>>>and global names.
>>>>>
>>>>>The other overriding rule (especially because we had the notion of 
>>>>>module ownership), was that you were to always make attempt to follow 
>>>>>the coding standard of the files(s) you were working in.
>>>>>
>>>>>Meaning those who spent a lot of time in their modules had a little 
>>>>>more flexibility in the style for those files, thus making it easier 
>>>>>and more natural for those developers. Then, if by chance, you found 
>>>>>yourself making changes to other people's code, you adapted to their 
>>>>>style. The obvious idea was that you probably weren't going to be 
>>>>>doing a lot of editting in other peoples code. Which, as it turns out, 
>>>>>was pretty much true.
>>>>>
>>>>>I don't expect to be editting much if any Ptolemy code, etc. And it 
>>>>>wouldn't make a lot of sense for someone to spend much time in the QB 
>>>>>trying to fix a bug when I should probably be the fixing it.
>>>>>
>>>>>I think there is an economies of scale thing in here somewhere ;-)
>>>>>
>>>>>(Besides, outside of variable naming conventions, a lot of code can be 
>>>>>reformatted with Eclipse or other tools)
>>>>>
>>>>>Rod
>>>>>
>>>>>
>>>>>Edward A Lee wrote:
>>>>>>At 11:17 AM 8/12/2004 -0500, Rod Spears wrote:
>>>>>>>Also, there seems to be some varying feelings and opinions about the 
>>>>>>>coding style for Kepler. My approach which I am sure differs from 
>>>>>>>Kepler is as follows:
>>>>>>>
>>>>>>>1) All method arguments start with a lowercase "a"
>>>>>>>2) All class data members all start with "m" (unless they are final)
>>>>>>>3) All local variables have no prefix.
>>>>>>>
>>>>>>>It is my belief that you should always be able to look at a variable 
>>>>>>>in the code and understand it's scope. I disagree with the approach 
>>>>>>>where both the method arguments and the local variables have no 
>>>>>>>prefix and are often distinguished by a "this.", which is rather 
>>>>>>>verbose at times.
>>>>>>
>>>>>>While I think these are valid points,
>>>>>>I would like to make a case for following the coding style anyway...
>>>>>>
>>>>>>There is no coding style that will appeal to everyone (I guarantee it).
>>>>>>The benefits of having a uniform coding style, however, far outweigh
>>>>>>_any_ benefits you might derive from any particular coding style.
>>>>>>
>>>>>>So, I would suggest that the discussion needs to be:
>>>>>>
>>>>>>  1) What changes should be made to the uniform coding style?
>>>>>>  2) Who's going to do the work to convert the existing code base
>>>>>>     to conform with any changes in the coding style?
>>>>>>
>>>>>>Number 2 suggests that changes had better have pretty compelling
>>>>>>reasons... I don't find the above reasons compelling enough...
>>>>>>(nor are they consistent: What if I name a local variable "model"?
>>>>>>Is it a class data member?).
>>>>>>
>>>>>>I think the concerns addressed by this proposal are adequately
>>>>>>addressed by keeping methods short and by choosing readable
>>>>>>names for variables that a compositions of full words and clearly
>>>>>>define the role of the variable.
>>>>>>
>>>>>>Edward
>>>>>>
>>>>>>
>>>>>>
>>>>>>------------
>>>>>>Edward A. Lee, Professor
>>>>>>518 Cory Hall, UC Berkeley, Berkeley, CA 94720
>>>>>>phone: 510-642-0455, fax: 510-642-2739
>>>>>><mailto:eal at eecs.Berkeley.EDU>eal at eecs.Berkeley.EDU, 
>>>>>><http://ptolemy.eecs.berkeley.edu/~eal>http://ptolemy.eecs.berkeley.edu/~eal
>>>>>
>>>>>
>>>>>--
>>>>>Rod Spears
>>>>>Biodiversity Research Center
>>>>>University of Kansas
>>>>>1345 Jayhawk Boulevard
>>>>>Lawrence, KS 66045, USA
>>>>>Tel: 785 864-4082, Fax: 785 864-5335
>>>>
>>>>------------
>>>>Edward A. Lee, Professor
>>>>518 Cory Hall, UC Berkeley, Berkeley, CA 94720
>>>>phone: 510-642-0455, fax: 510-642-2739
>>>><mailto:eal at eecs.Berkeley.EDU>eal at eecs.Berkeley.EDU, 
>>>><http://ptolemy.eecs.berkeley.edu/~eal>http://ptolemy.eecs.berkeley.edu/~eal
>>>
>>>
>>>--
>>>Rod Spears
>>>Biodiversity Research Center
>>>University of Kansas
>>>1345 Jayhawk Boulevard
>>>Lawrence, KS 66045, USA
>>>Tel: 785 864-4082, Fax: 785 864-5335
>>
>>------------
>>Edward A. Lee, Professor
>>518 Cory Hall, UC Berkeley, Berkeley, CA 94720
>>phone: 510-642-0455, fax: 510-642-2739
>><mailto:eal at eecs.Berkeley.EDU>eal at eecs.Berkeley.EDU, 
>>http://ptolemy.eecs.berkeley.edu/~eal
>>
>>_______________________________________________
>>seek-dev mailing list
>><mailto:seek-dev at ecoinformatics.org>seek-dev at ecoinformatics.org
>>http://www.ecoinformatics.org/mailman/listinfo/seek-dev
>
>
>--
>Rod Spears
>Biodiversity Research Center
>University of Kansas
>1345 Jayhawk Boulevard
>Lawrence, KS 66045, USA
>Tel: 785 864-4082, Fax: 785 864-5335

------------
Edward A. Lee, Professor
518 Cory Hall, UC Berkeley, Berkeley, CA 94720
phone: 510-642-0455, fax: 510-642-2739
eal at eecs.Berkeley.EDU, http://ptolemy.eecs.berkeley.edu/~eal