documentation in the code
DocBlock comments:
- Explain your code for others
(or for yourself in a month)
- Get code hints in most IDE's
- Make your code ready for API docs
"If you come across core or
contrib code that is missing
comments, then open a critical
bug on the issue queue. If
anyone complains, tell them to
talk to me..."
-- @crell
(Larry Garfield - paraphrased)
THE MAGIC OF DOXYGEN
"Doxygen is a documentation generator, a tool for writing software reference documentation. The documentation is written within code, and is thus relatively easy to keep up to date. Doxygen can cross reference documentation and code, so that the reader of a document can easily refer to the actual code."
http://en.wikipedia.org/wiki/Doxygen
https://drupal.org/coding-standards/docs
tips:
-
"Always code as if the person who will maintain your code is a maniac serial killer that knows where you live"
- Start writing your comments & functions before you code
- Each function/method should do a single thing
- Run coder
- Develop an appreciation for beautiful code
example
hook_form_alter()