Docblocks recommended for a class and for the methods

[block34]

Look at these examples.

Docblock only for the class:

/**
 * Tool to format a text.
 */
class Formatter {
	    function format() {}
}

Docblock only for the method:

class Formatter {
	/**
     * Format a text.
     */
    function format() {}
}

Docblocks for both (slightly diversified):

/**
 * Tool to format a text.
 */
class Formatter {
	    /**
     * Format a text.
     */
    function format() {}
}

Identical docblocks for both (although they create a little redundancy for my taste):

/**
 * Format a text.
 */
class Formatter {
	    /**
     * Format a text.
     */
    function format() {}
}

Do you usually use pattern[/ u] to comment on your classes?

Edited November 9, 2019 by block34

[requinix]

I don't put comments on classes. They tend to be somewhat self-explanatory just by reading the (namespace and) name alone. Unless there's something particular complicated about them... but most of the time any complexity is with what that happens inside a method.

But definitely put comments on the methods.

[maxxd]

Comment when and where it's necessary. When it comes to methods, I'm a fan of always writing documentation but at least document the parameters, regardless the scope of the method - I've heard people say it's only important to document the public API of a class. This is utter bullshit. However, when it comes to initial documentation for a class if it does something weird, then yeah - document that sucker.

For instance, your Formatter class seems simple enough - it formats a thing. However, if you're not using namespaces and your system formats both HTML and JSON, but Formatter only deals with JSON then document that. I'd argue you should use namespaces or rethink your class naming scheme, but sometimes you come into legacy code and have to do what you have to do.

[block34]

Thanks