Jump to content
block34

Docblocks recommended for a class and for the methods

Recommended Posts

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 by block34

Share this post


Link to post
Share on other sites

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.

  • Like 1

Share this post


Link to post
Share on other sites

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.

  • Like 1

Share this post


Link to post
Share on other sites

Join the conversation

You can post now and register later. If you have an account, sign in now to post with your account.

Guest
Reply to this topic...

×   Pasted as rich text.   Restore formatting

  Only 75 emoji are allowed.

×   Your link has been automatically embedded.   Display as a link instead

×   Your previous content has been restored.   Clear editor

×   You cannot paste images directly. Upload or insert images from URL.


×
×
  • Create New...

Important Information

We have placed cookies on your device to help make this website better. You can adjust your cookie settings, otherwise we'll assume you're okay to continue.