We all know that we must write documentation in code, else we be hit on the head with a blunt object. This goes deeper than that, to the dreaded details for those who do not wish or cannot read code. It also goes to what makes a better library than another. Doesn’t mean that the documentation has to be perfect, just that it exists.

Damn phpDoc, Damn phpDoc to Hell!

Just Kidding, phpDoc is very useful and should be used in development. There are some difficulties with information the phpDoc documentation web sites provide. In most cases when @example tag is not utilized effectively or not at all.

It really is the primary concern that I have when reading through phpDoc sites that no true examples are given to places the method or function or class usage in context. Yeah, you tell me what it does, but how exactly do I use it? I would like to use two different sites for an example, the php.net manual and the SPL phpDoc site.

The PHP manual is great because not only does it state what the function is and the parameters, but also gives examples. The SPL phpDoc gives you all you will ever need to know about the SPL classes and interfaces, but there is a very good reason why there are so many tutorials out there for SPL. The popularity of external tutorials for SPL is that there exists no examples on the SPL phpDoc site.

An advanced developer could take a look at the site documentation and do a few tests and have a working implementation. What about the rest of us? The lowly mortals that do not have such time to experiment and devote time to figuring out how to use the various classes.

It would explain why I instead choose to write my own ArrayObject every time I need the functionality. I know how to use Countable, Iterator, and ArrayAccess, so why is ArrayObject any more difficult? I should not have to depend on the talent (and kindness) of other developers and would be better served by the “official” site for such information.

(I think of SPL as an exception to this article’s rule because it comes with PHP and offers advantages not otherwise available.)

Making Better Libraries

You can have the best API out there, whether object or procedural, but without some guide to use it, no one will. I’ve sought out many libraries that I threw out, because the author didn’t take the time to write a manual on how to use it. Now, you might say I’m whining and you’ll be correct. I have little time to go through hundreds or thousands of lines of code just to solve what should be an easy operation.

To give an current example on how manuals should be, notably the Zend Framework, in the beginning the documentation wasn’t perfect (complete would be a better description and still isn’t at this point). Still, it is fine because most of the questions can be answered by reading what exists. I can provide feedback on how it can be further improved, because there is a manual.

It is worse to have no written manual than poorly written (clarity, grammar, spelling, missing sections) documentation. Proving that you at least tried means more than the appearance that you either don’t care or don’t have the time.

If you are writing a public library, it at least says that you want people to use it at some point. It might be the most boring and torturous experience known to a coder, but it is well worth the effort (unless your library is terrible, but at least you can take the experience and use it in a job setting).

Improving the Manual

One of the biggest fears of writing a documentation is that it must be perfect. Not true, states this author, for I can never write a perfect manual. I’ll be damned if I’m not going to try, knowing that I’ll fail. At least there would be something to show and to receive feedback saying, “Your documentation sucks!” At least I’ll be able to reply, “Oh yeah! Where exactly can I improve it?”

Just start writing it and if you have clarity or other problems, a helpful user might let you know. A even more helpful user is going to let you know the exact phase to make it perfect or help provide the improved documentation on their own.

Help your users by providing a more detailed context of how to use the library and slowly try to improve it as time permits. If no one offers to help, then carry on improving the manual on your own. It would only help you understand your library better and help your existing users on using your library.

It is easier to tightened a few spots here and there than to write whole sections or the whole manual. If you at least have something that exists it is going to be quicker to update it to improve the existing sections or adding new sections. Think of it as an investment and own it.

Conclusion

Really, however you go about doing it, comments in code is to help yourself and anyone that dares to try to maintain it in the future. Knowledge without context is worthless to your user, so my advice is to either utilize the @example phpDoc tag or write a manual along with the phpDoc site to relate the usage better.

At the very least, you’ll be able to better answer questions by saying, “RTFM.” Or at least a more polite phase or link to the section they are asking about.

Possibly Related Posts:

• Bullet: E-Book Library Management and Content Server
• Using ZendFramework 2 beta1 For Directory Project
• The Way of Kings and Cosmere Theory
• “In Time” Movie Premise Flawed
• Completing HTTP Library For PHP

At the cost of memory overhead, it is useful to have a look up table to save time. The solution came from having a search method that would look up to see if the element existed each time. With all of the times I would be calling the search method, it made sense to create a look up table.

The Search method before the look up table used a while loop to iterate through the elements and tried to find the correct one to return. It became apparent that I would of had to use this search method more than I would like to continuously search through the entire array each time I wanted to position. That and this search method only returned the node and I would sometimes need the index (which would be easy to add, since the internal container is an array and the key would be the index).

    public function search($x, $y, $z = 0)
    {

        $this->rewind();

        while($this->valid())
        {
            $cur = $this->current();

            // Check that the x value is the same. Quicker to check the x pos
            // first and continue then to check all values at the same time.
            if(!($cur['x'] === $x))
            {
                $this->next();
                continue; // Possible Bug
            }

            if(!($cur['y'] === $y) && !($cur['z'] === $z))
            {
                $this->next();
                continue; // Possible Bug
            }

            // If all checks pass then current be returned ending the loop.
            return $cur;
        }

        return false;

    }

After all of that, I would have to create unit tests to make sure that if the x position didn’t exist, that it continued without testing for the y and z positions. Failing that, I would have to use another method to repeat. I however was able to reduce the search method to the following efficient and speedy code.

    public function search($x, $y, $z = 0)
    {
        if($this->_searchCoordIndex($x, $y, $z) === true)
        {
            $index = $this->_coordsIndex[$x][$y][$z];
            return $this->_coords[$index];
        }
    }

The look up table prototype:

class Quantum_Coordinate_Array
    implements SeekableIterator, Countable
{
    /**
     * Keep a look up table of the coordinate indexes.
     */
    protected $_coordsIndex = array();

    public function search($x, $y, $z = 0);

    protected function _setCoordIndex($index, $x, $y, $z = 0)
    {
        $this->_coordsIndex[$x][$y][$z] = $index;
    }

    protected function _existsCoordIndex($x, $y, $z = 0)
    {
        if(isset($this->_coordsIndex[$x][$y][$z]) && $this->_coordsIndex[$x][$y][$z] != null)
        {
            return true;
        }
        return false;
    }

    protected function _searchCoordIndex($x, $y, $z = 0)
    {
        if(!array_key_exists($x, $this->_coordsIndex))
        {
            return false; // X key does not exist
        }
        else // X key exists
        {
            if(!array_key_exists($y, $this->_coordsIndex[$x]))
            {
                return false; // Y key does not exist
            }
            else // Y key exists
            {
                if(!array_key_exists($z, $this->_coordsIndex[$x][$y]))
                {
                    return false; // Z key does not exist
                }

                return true; // All key exists
            }
        }
    }

}

Apparently also, the _existsCoordIndex and _searchCoordIndex do exactly the same thing, except the logic for the _existsCoordIndex is quicker. The _searchCoordIndex would have to be unit tested, but it would be more accurate than _existsCoordIndex (if it is needed and desired).

Possibly Related Posts:

• Bullet: E-Book Library Management and Content Server
• Using ZendFramework 2 beta1 For Directory Project
• The Way of Kings and Cosmere Theory
• “In Time” Movie Premise Flawed
• Completing HTTP Library For PHP

It was by chance and this crazy post that caught the attention of Laura Thomson that I was able to visit OmniTI. To me, the professional world exists at another level above average existence. I never thought I would be able to tour any business establishment, so I didn’t think to ask in a sane matter. It is impressive that any company would open their doors to the average person who is not a customer.

The Talk

I was expecting, just to be shown around, ask a few questions about how the place was run, and be kicked out the door. However, I think it was a treat to actually sit down and have a discussion with Laura, George, and Wez after the tour. It was fun to engage in a PHP discussion without having the other person just nod. Talked about PHP and some other stuff.

The Tour

Why it was exciting?

To be able to meet some prominent developers and leaders of PHP, who wouldn’t be excited?

It might not sound like much, or at least it didn’t seem like much to the people I told, but from an academic perspective, it was a chance to see what it like in a professional development office. There is some anxiety to not knowing what happens at a professional workplace and leaves much to the imagination. I really had no idea what to expect and I can imagine that if I ever do get a professional job that the place would look something like OmniTI, until I do get a professional job and find it is exactly like Dilbert.

The details

I was kind of shocked at how the developers worked in such an open space. One without cubicles and with wavy desks. It does help to lighten the mood, in my opinion. It is quite depressing to be confined to a tight space, maddening even. I had to clean cubicles, it was depressing just being in there just for a few seconds. I think it is just the idea of isolation in a room full of people. You could die and no one would know until they either smelled your corpse or walked by.

The layout was logical, keeping the “work” and the “client” areas away from each other. However, the “boss” areas are quite close to the work area, so slacking off probably isn’t an issue, since you can’t hide, like you can in a cubicle.

I probably should have said something about not being able to hear, but I mostly caught the gist of the speaker. Well, it wasn’t that I couldn’t pick up and understand the complete conversation. I did miss a few joke cues, because it took to long to realize what was being said was a joke. It is one regret that I keep forgetting that it is okay to tell people that I have a hearing problem.

Wez was cool.

Yeah, Chris had left before I arrived, but Wez was there, which was just as cool. What was also cool was that Laura invited him to join in on the tour, so I had two people showing me around. Wez did reference a few things on my blog, both good and bad.

Wez was the complete opposite of what I imagined. I kind of thought he would be wider and shorter, but no, he is a giant (at least 6 feet) and skinny. Reminded me of a friend I have, except Wez is skinnier. It is the shirts I think, which is why I tuck my shirts in. I’m fat, but eh, I don’t want to look any bigger than I am now.

I do have frustrations with PDO, but it is mostly from learning something new. I thought it was and still is a great feature to have in PHP. I’m glad I had a chance to clarify that to him personally.

“We aren’t going to let you leave here alive.”

I didn’t reply to this for two reasons. The first reason was that I knew it was a joke, which was stated later in the tour. The second was that I had thought to say, “Yeah, I would like to see that happen,” or, “Whatever you want to do,” but I thought about it and it didn’t seem like a good idea to test fate and find that they had a Plan B “just in case.” I would have been more concerned if they knocked me out and I woke up tied to a table and suddenly hear a chainsaw starting in the background.

I also didn’t want to say, “Yeah, I say that all the time too,” and freak out the host, it is never good to potentially freak out the host. I discuss killing people all the time, so it wasn’t a big deal to me. For me, if I was really going to kill, then I wouldn’t tell it to their face, unless I was about to pull the trigger.

I do have a mental list (as to not leave evidence), but it is doubtful that I’ll ever kill them. Torture, yeah maybe. I think torture is more fun anyway. You can only kill someone once, but you can torture them for as long as you think they should live. It also leaves hope that they might make it out alive, which you can crush under the weight of a bullet hitting them in the heart. Make sure you laugh, it is more crazy that way.

Possibly Related Posts:

• Bullet: E-Book Library Management and Content Server
• Using ZendFramework 2 beta1 For Directory Project
• The Way of Kings and Cosmere Theory
• “In Time” Movie Premise Flawed
• Completing HTTP Library For PHP

I think the idea of releasing packages based off the Zend Framework is a great idea, like the Google Data Client Library. If I could propose that they add an Authentication package including OpenID, LID (not really authentication or I should say includes more than just authentication and you can use OpenID with the newer specifications), and the others. Not part of the core of Zend Framework, but available for those who wish to use it.

The Yadis specification library uses a similar component to that of the Zend Service component and therefore could be used in one part to handle the request. The Yadis specification is really easy, other than the HTML regex to gather meta data to get the location of the Yadis XML file. All you need after you have the Yadis service file is to just use either DOM or SimpleXML to parse it and return the services.

Yadis is great for letting scripts know what services are available and where the service is located. Supposedly, it is to be used along with OpenID, but isn’t required.

Started a project a long, long time ago, around Summer-ish. Yeah, dropped it because Zend Framework had a component I was working on. Sigh. Still I mean, it would be nice if it was part or a optional component for the Zend Framework. I would do it, but I mean, HTML regex scare me. Can do XML.

Possibly Related Posts:

• Bullet: E-Book Library Management and Content Server
• Using ZendFramework 2 beta1 For Directory Project
• The Way of Kings and Cosmere Theory
• “In Time” Movie Premise Flawed
• Completing HTTP Library For PHP

Updated:

I’m pretty much kicking myself. In all my tests, I never once thought about returning an actual array!

“Pfft, that would be too easy!”

I suck.

Lines 35, 36: Add ‘ArrayAccess’ to the end of the line 35

class Zend_Config implements Countable, Iterator, ArrayAccess
{

Add anywhere in the class that you feel makes sense. In my version 0.1.5 preview release, I placed it in lines 80-98:

public function offsetExists($key)
{
	return $this->__isset($key);
}

public function offsetGet($key)
{
	return $this->__get($key);
}

public function offsetSet($key, $value)
{
	return $this->__set($key, $value);
}

public function offsetUnset($key)
{
	return $this->__set($key, null);
}

Yeah, I mean. After looking at the code a little bit, it became somewhat clearer on how the object functioned and how it got passed my previous post restrictions. Really simple actually.

The point I should make is that offsetSet bypasses the protected magic Set method, therefore, since I can’t test it on 5.0, it would be hard to say if it would still work or not.

The issue of code duplication is resolved by using methods that already exist. For objects that return arrays, it is possible to use the same methods listed above for any class that also use the property overloading magic methods.

Use at your own risk!

Uses the Zend Framework Config class.

$DoNotTouch = new Zend_Config(Zend_Config_Xml::load('/path/to/config.xml', 'secretdata'));

// Property

$value = $DoNotTouch->key->key;

// Or Array

$secret = $DoNotTouch->asArray();    // Iterates over all values and returns as PHP Array
$value = $secret['key']['key'];

Or simply and without as much overhead:

$DoNotTouch = new Zend_Config(Zend_Config_Xml::load('/path/to/config.xml', 'secretdata'));

// Property

$value = $DoNotTouch->key->key;

// Or ArrayAccess
$value = $DoNotTouch['key']['key'];

Possibly Related Posts:

• Bullet: E-Book Library Management and Content Server
• Using ZendFramework 2 beta1 For Directory Project
• The Way of Kings and Cosmere Theory
• “In Time” Movie Premise Flawed
• Completing HTTP Library For PHP