Question

A simple question: Which is the best way to document for example the types of function parameters or return values in dynamic languages? Adding comments after each function definition?

Answer 1

The conventions depend more on commenting/documentation features of the language than on the static/dynamic typing nature of the language. Even more do they depend on the documentation tool used, as often multiple different documentation tools exist for one language. Although in statically typed languages you don’t have to document the technical types of the parameters, you still need to document the meaning and purpose.

A large group of languages with C-derived syntax use Javadoc style comments. For example in PHP:

/**
 * Calculates the area of circle.
 * @param float $radius The radius of circe.
 * @return float The area
 */
function area($radius) {

The YARD tool for Ruby uses a similar convention:

# Calculates the area of circle.
# @param [Number] radius The radius of circe.
# @return [Number] The area
def area(radius)

I guess on the whole, this is the most mainstream style.

In several languages you just write pretty much free-form comments, using bulleted lists etc when you need to document list of parameters. An interesting example in this regard is Perl with its pod comments:

=item stuff(radius)

Calculates the area of circle.

=cut

sub stuff {

Contrary to the examples provided by ralu, I think it’s more common to have documentation before the function definition… but in the end it all depends on the language.