AW: [Mapbender-dev] Reminder: Code Conventions

[Samson, Marko]

Hi,

I think, that the code conventions are a good thing to make developing more efficient and productive, after a therm of adjustment to the conventions. (@Cristoph:btw. are this standard php conventions? where did you get them from, or did you develop your own conventions?)

But my opinion to comments is like Marcs. I don't think, that comments would be a great performance or filesize problem. (or did you have any problems by files, inflated by comments, in the past?)
Surely, there is no reason to comment every row. But I think, that a short description of a function (needless to say, that not every set and get function has to be commented), perhaps with some special problems or conditions and some special vars, would increase the productivity and double developing and uncontrolled function-groth in every module.

As the Code Conventions say: performance is not a good reason to avoid commenting


Gruß,
Marko


Marko Samson
Landesbetrieb Wald und Holz NRW
GIS-Anwendungsentwicklung
Referat I-5
Albrecht-Thaer-Straße 34
48147 Münster


Achtung, neue Telefonnummer!
Tel.: 0251/91797 - 169
Mail: marko.samson at wald-und-holz.nrw.de
 

> -----Ursprüngliche Nachricht-----
> Von: mapbender_dev-bounces at lists.osgeo.org 
> [mailto:mapbender_dev-bounces at lists.osgeo.org] Im Auftrag von 
> Christoph Baudson (WhereGroup)
> Gesendet: Montag, 22. Januar 2007 10:30
> An: Mapbender Developer List
> Betreff: [Mapbender-dev] Reminder: Code Conventions
> 
> Hello,
> 
> thanks for your arguments, Marc. The points you made are all 
> sensible. I would be interested in other members opinions on 
> comments, especially in JS.
> 
> Before we make a decision there should be some more time to 
> discuss these matters. I suggest to postpone voting on the 
> conventions for two weeks (Feb 5).
> 
> Please take a look at
> http://www.mapbender.org/index.php/Code_conventions and let 
> us know what you think.
> 
> Cheers, Christoph
> 
> >> At the moment this kind of documentation is maintained in 
> the Wiki. 
> >> Each module should have a link in the header that leads to a wiki 
> >> page where each function/class is explained similar to the 
> way you described.
> > 
> > Thats a good approach, yet I think the possibility to have an 
> > automated code docu (as PEAR has for instance, see
> > http://pear.php.net/package/Date/docs/latest/) would be nice, too.
> >> This keeps the file sizes small, which is especially important for 
> >> js-files.
> > 
> > Yes filesize does matter, but once cahched by the browser 
> it would not 
> > do harm anymore...
> >> So I think it's not advisable to have too much comments in 
> js-code. 
> > 
> > I disagree: usefull comments can - in my opinion - never be 
> to much... 
> > especially when using some sort of compression (see below).
> >> In an ideal world the js-code would have comments in the SVN, and 
> >> they could be removed once Mapbender is running to 
> increase the performance.
> > 
> > Commenting in SVN is - again my opinion - no substitution to coding 
> > comments.
> >> But I don't know of a way how to do this. Anyone?
> >>
> >> (Btw, do you know how jQuery compresses the file? I see 
> there are two 
> >> versions available, the compressed one being significantly smaller.
> >> This might be interesting as well.)
> >>
> > 
> > Yipp: jquery uses Dean Edwards excelent tool packer: 
> > http://dean.edwards.name/packer/
> > It removes all comments, new lines and the rest of the code is 
> > optimized as an eval statement (eval is not always evil...) You can 
> > pack manually, or automated via different tools:
> > PHP 5: http://joliclic.free.fr/php/javascript-packer/en/
> > There should be other APIs for the automated use of this... I just 
> > can't find them right now
> > 
> > This would also mean that all javascript code has to follow some 
> > conventions. Nothing special: always use the semicolon, do not use 
> > shorthand comparisons: see 
> http://dean.edwards.name/packer/usage/, and 
> > http://dean.edwards.name/packer/usage/sample.html.
> > 
> > Most common errors are statements like these:
> > 
> > function foo() {
> >  return 'bar';
> > }; //never forget this semicolon
> > 
> > AND
> > 
> > function bar() {
> >  if (myVariable == 'foo')
> >    return myVariable;
> >  else
> >    return 'baz';
> > }
> > (never forget to use the braces {} within if ... else)
> > 
> > 
> >> So, if the js-code has its documentation in the wiki, I doubt it 
> >> would be a good idea to have the php comments in the code, 
> it would 
> >> confuse people. I'm not against the phpdoc-style documentation, I 
> >> only fear that we have already marched in another 
> direction and going 
> >> back would be too time consumptive. But I would like to hear some 
> >> other opinions on this!
> >>
> > 
> > As long as we all use the same method, I see no problems with using 
> > any sort of documenting our work. But may I once again 
> strengthen my 
> > wish for having lots of docu (formatted as the community wants it) 
> > *within th code*. I - personally - like having relevant information 
> > about code in the source file I'm viewing... that would by no means 
> > result in commenting only within the file (the wiki may be 
> used as well).
> > 
> > Using a nice editor (Eclipse for instance) and documenting your PHP 
> > code with PHPdoc results in lots of rewards by the editor : 
> tool-tips 
> > with method-arguments, auto suggestion, etc.
> > 
> > BTW: I really like the way we are now disussing within this list: 
> > hopefully we will keep up with this...
> > 
> > -- Marc
> > 
> > _______________________________________________
> > Mapbender_dev mailing list
> > Mapbender_dev at lists.osgeo.org
> > http://lists.osgeo.org/mailman/listinfo/mapbender_dev
> 
> _______________________________________________
> Mapbender_dev mailing list
> Mapbender_dev at lists.osgeo.org
> http://lists.osgeo.org/mailman/listinfo/mapbender_dev
>