5

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!

Improve this question
3
  • In my experience at companies that had PHP apps that were not used as APIs and not used to generate documentation we didn't use DocBlock.
    – programmer
    Jul 12, 2012 at 20:53
  • @JasonHolland so you're saying that it's not important? How do you/ your company often write comments?
    – Nadav S.
    Jul 12, 2012 at 20:59
  • I added an answer FWIW.
    – programmer
    Jul 12, 2012 at 22:04

2 Answers 2

Reset to default
7

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 ;-)

Improve this answer
1
  • Thanks for the answer. I'm using PhpStorm and it generates docblocks just fantastic. It's good to hear that many people are using this format even if not for phpDocumentor.
    – Nadav S.
    Jul 12, 2012 at 21:12
3

At my previous jobs we didn't use DocBlocks for PHP if the code was not an API and was not going to be used to generate documentation. Here was our philosophy on comments:

Use /**/ only for formal documentation at the top of the script that includes the author, date, brief description, etc. Use // for all other comments.

We noticed that comments can get out-dated and turn into lies about the code. We instead would try to write "self-illuminating" code by choosing function/class names that better reflect their purpose/function. We would also re-factor complex functions into simpler functions that "do one thing" instead of writing large functions that had a short novel comment above it to try and describe what it did.

The only benefit I can see that we were missing is labeling the function arguments on what data type they expecting and what data type the return value is. But then again, PHP is a loosely typed language where the DocBlocks could betray you (best to just use === and !== and is_*() functions if you really need to look at data types).

Improve this answer
2
  • Interesting. Are you saying that function foo_bar(array $param){} is not good and I should use is_array($param) instead? I have started typing codeblocks now, and I'm still not sure what approach I should take.
    – Nadav S.
    Jul 12, 2012 at 22:16
  • @Nadav S., No, by all means I think you should use the language features provided like type hinting in the function parameters if it makes sense. But you can not use type hinting for scalar types such as int or string (which is where DocBlocks could be considered useful). I'm saying that you may not want to put your full trust in DocBlocks on param types since php is loosly typed and instead use is_* if you really need to enforce a certain type.
    – programmer
    Jul 12, 2012 at 23:46

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.