If an "example" may be worth a thousand words, a programmer for a "comment" can be worth hours and hours of work! Comment the code is often tedious and, at the time of writing the code, it always seems a futile. On the contrary, especially when you take old code, the comment you entered the right can be infinitely useful to reconstruct mental paths have been forgotten. Fortunately, for those like me who developed the Web, you can comment on the enormous vatanggio almost all the code in the same way! The double slash (/ /) or containment through slash asterisk and slash asterisk (/ * and * /) is supported by virtually all lunguaggi development of common use, virtually all derived from the C: Javascript, Actionscript, PHP, ...
Such as headers, for example, I always use a structure of this type, the same for almost all the languages I use:
1 2 3 4 5 6 7 8 9 | / * ** @ Name: main.as ** @ Description: the main class of the Flash project ** @ Author: undo = = ** @ Web: http://www.undolog.com ** @ Email: @ g.fazioli undolog.com - g (dot) Fazioli (at) undolog (dot) com ** ** @ Ver: 1.0 * / |
exactly the same syntax can also be used for Javascript or PHP. Use the @ symbol (at), the snail, so as to track the comments within the code quickly, ultile for comments on functions (methods), events and properties:
1 2 3 4 5 6 7 8 | / * ** @ Name: collapse () ** @ Description: generates a parse-type ** @ Params: value - value of collapse **: Type - type of collapse ** @ Result: true if ok, false if error ** @ Seealso: uncollapse () * / |
In Actionscript, where it has more often to do with classes, methods to distinguish between (public or private), events and properties can be handy durente the passing of a code:
1 2 3 4 5 | / * ** @ Name: ontopdown () ** @ Description: (event) - trigged when the element is active ** @ Seealso: ontopup () * / |
1 2 3 4 5 | / * ** @ Name: color ** @ Description: (property) - get / set the background color ** @ Seealso: bgcolor * / |
True, I would say that not only help yourself re-reading the code, will also help those who come after you (if you work on shared projects). In this case it also becomes a form of respect, leave a good job in the hands of others makes life easier for others.
Somewhere I read a quote from someone who said English, "as if the program is that after you were a psychopath who knows where you live"
@ Chris: holy words!