[Mapbender-dev] Reminder: Code Conventions

[Christoph Baudson (WhereGroup)]

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.

This keeps the file sizes small, which is especially important for 
js-files. So I think it's not advisable to have too much comments in 
js-code. 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. 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.)

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!

Christoph

> I suggest using PHPdoc-style (IMHO this suits JavaScript code, too) at 
> least for some very common attributes of code:
> 
> /**
> * Comments style like this one
> * above functions, methods, variables, classes...
> */
> 
> Structure:
> Firstline in docblock: Short desription (Usually one sentences)
> empty line
> thirdline: longer description...
> emptyline: docblock-tags (see below)
> 
> Attributes in this docblock:
> @author name email
> @param type description
> @return type description
> @uses | @usedby name of function, class (not sure whether these are 
> standard...)
> 
> 
> This is highly readable and can be understood by both machines 
> (autogenerated technical docu... yippieh!) and humans (the 
> "Ahh...-this-is-how-its-done!"-effect when looking inside of 
> source-files, nice for learning new stuff too).