[Mapbender-dev] Reminder: Code Conventions

[Christoph Baudson (WhereGroup)]

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