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!
3
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 😉
1
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).
2