Php – Is it recommended to use DocBlock even if I’m not using phpDocumentor

documentationPHP

I'm developing a simple website for a client.

I have read about phpDocumentor and DocBlocks, and I thought that documenting my classes and functions will be very useful.

I'm almost sure I will not generate any documentation for the site, since it's a pretty simple website, and guess what? It doesn't have an API…

But is it still recommended to write DocBlocks in my code? From what I know many programmers even don't write simple comments, but DocBlocks.
I'm not going to generate any readable documentation by the client/ next programmer but I still think that making some comments that are more than just simple text will be better.

edit – If you think that DocBlocks are redundant in my case, are there any other "standards" for writing comments / documentation?
The last time everything that doesn't have a standard makes me feel stupid, that I'm not sure if it's better to write if(){ or if () {, /* */ or //, etc.

I'm new to the documentor and DockBlocks, and I'm still not sure if I have to write this question here or in StackOverflow. Thank you very much anyway!

Best Answer

It is useful to document similar stuff in a similar way. This makes it easy to read the code as you can grasp the important things easily. Using an established standard as a foundation is useful as new team members will quickly get used to the scheme. phpdocumentor format is based on JavaDoc. The same form is sometimes used in other languages, too. Therefore even developers not familiar with PHP are more like to understand and use it quickly.

Additionally tools like IDEs support the format. And can derive information for some help from it.

If you should be strict in using it is a different question. You might use just little parts of it and modify others to your needs. Just like with any other tool ;-)

Related Solutions

Documentation – Are XML Comments Necessary?

If your comments only look like this:

/// <summary>
/// Gets or sets the sublot number.
/// </summary>
/// <value>
/// The sublot number.
/// </value>

Then yes, they are not all that useful. If they read something like this:

/// <summary>
/// Gets or sets the sublot number.
/// Note that the sublot number is only used by the legacy inventory system.
/// Latest version of the online inventory system does not use this, so you can leave it null. 
/// Some vendors require it but if you don't set it they'll send a request for it specifically.
/// </summary>
/// <value>
/// The sublot number.
/// </value>

Then I'd say they have value. So to answer your question: Comments are necessary when they say something that the code does not say.

An exception: it is good to have comments on anything that is publicly accessible if you're writing a library/API that will be available to the public. I hate using a library and seeing a function named getAPCDGFSocket() with no explanation of what an APCDGFSocket is (I'd be happy with something as simple as This gets the Async Process Coordinator Data Generator File Socket). So in that case, I'd say use some tool to generate all comments and then manually tweak the ones that need it (and please make sure your cryptic acronyms are explained).

Also, getters/setters are generally bad examples for "are comments necessary?" because they are usually quite obvious and comments aren't necessary. Comments are more important on functions that perform some algorithm where some explanation of why things are being done they way they are could make the code much more understandable and also make it easier for future programmers to work with.

...and finally, I'm pretty sure that this question is relevant for all styles of comments, not just those that are formatted using XML (which you are using because you're working in a .NET environment).

Named Output Parameters vs Return Values – Best Practices

Edit (since the question has changed)

If your method only has one output, of course you return that value.

bool DoStuff(...)

is much more readable when you use it than

void DoStuff(..., out bool success)

Look at the sample usage:

if(DoStuff(....))

DoStuff(..., out success)
if (success)

Also, it allows in-lining and chaining (if the language supports it):

ProcessRequest(GetRequest(reqID))
newval = ProcessString(oldval).Replace("/t","")

Converting these to "out" params would lead to much uglier code, plus it's just wrong.

For 1 return, always use return values.

Best Answer

Related Solutions

Documentation – Are XML Comments Necessary?

Named Output Parameters vs Return Values – Best Practices

Related Topic