[Mapbender-dev] Reminder: Code Conventions

[Marc Jansen]

Hi list,


Christoph Baudson (WhereGroup) schrieb:
> Thanks for your suggestion, Marc.
>
> 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