Why phpDoc?

Ok. So this one is just personal. Most people don't have a problem with phpDoc, and don't argue against using it–at least not that I'm aware of. But I'm lucky. I know some of the rare few.

Before I begin, let me just say that this rant is totally inspired by the fact that people need to be more open-minded. I don't want to point fingers, as this blog is public and I wouldn't want to alienate those that I know of whom I'm referring to, but c'mon people! We really need to be less haughty and ditch our I'd-like-to-pretend-I-know-tons-just-because-it-makes-me-feel-better attitudes. And by "we" and "our" I mean "you" and "your." Now, let's begin.

You are an idiot.

You knew it was coming. I just really get annoyed by this whole closed-minded thing that I seem to get the blunt end of all the time. It is so ridiculous to look at a piece of software, notice that there is one piece of functionality that–on the surface–seems to be missing that you think ought to be there, and freak out and create a de facto doctrine banning it from use and scorning those who do use it. There are so many more sides to any argument for the clincher to be a one-issue, end-of-discussion coffin-nailer.

Now, in response to your question, I must ask one of my own: "Why the frak NOT!?" If you don't document your code using a JavaDoc like syntax, WTF are the rest of us supposed to do with your code. We have no idea what's going on, and can't see what the individual pieces of code are supposed to be doing. More importantly, of course, there's no way to tell what the "big picture" is.

The point I'm trying to make is this: JavaDoc makes absolute and perfect sense, and there's not a &*%# thing you can say to change that fact. If you insist on being ignorant, that's your choice but I don't want to hear about it, and it had better not affect me.

Even if I never intend to generate documentation using the phpDoc tool, I am going to use JavaDoc like comments in my code. There's no other way to comment functions, classes, includes, defines, and pages any better, so why would you not do it. Furthermore, why would you try and define some alternate syntax, which sucks, and will eventually lead you back to JavaDoc anyway. Remember, machine readable is the key here, and JavaDoc is absolutely machine readable. You can do anything you want with it.

It's like when you try to develop your own tool for doing anything that has already been done, thinking: "I'll just code my own. In house is better, and I know how to program, so how hard can it be? blah blah blah..." No!!! Everything you try to do is going to lead you back to the tool that you were trying to replace in the first place. If you want a framework, use a framework, don't try and invent your own. It's been done already, and you're not coming up with new concepts, so just stop trying! There's not a $&%# thing you are doing that will be an improvement if is all you're trying to accomplish is getting a certain type of functionality working. If you actually had good ideas that had never been done, maybe it is worth it to "roll your own" XYZ functionality, but when it's been done before, use it! I'll say it again: Stop trying!!!