Tag Archives: Best-practices

Best Practices – Part 2

I just got out of Matthew and Lorna's tutorial on Best Practices and my mind is swimming with all of the things I want to try.  So, pretty much a normal day for me.  Part 1 can be found in the related links on the right hand side.

Part 2 is basically more of the same; a list of all the things you're not doing but probably should.

Let's start with documentation.

End User Documentation

The purpose of end user documentation is to provide a narrative for developers.  In other words, the purpose of providing end user documentation is what is demonstrating how to interface with the software you are writing.  It will often describe architecture, theory and design patterns that you used to implement various parts of your software.  Even though documentation is a very important part of the overall process it is often one that is not often properly done.  Or even partially done.  Part of that might be due to the fact that deciding on the tools to use can be a difficult decision to make.  So here are a few options that you have

Wikis

If you don't know what a Wiki is by now you're probably been under a rock for the past 10 years.  The basic concept of a Wiki is that it is a community forum where people can edit information.  It is generally easy for others to contribute but is generally un-distributable.  Meaning that besides the HTML interface of the rendered Wiki code you don't really have any ways of distributing it in an alternate format such as PDF or CHM.  Other problems are that it is difficult to translate, since it is fairly free-form and it is usually unversioned.

HTML

We may not often think of straight HTML as a documentation format but it can be.  It is easy for people with any web background and can be distributed but is difficult to offer in other formats such as PDF and CHM.  Since it's more structured than a Wiki it can be translated but will run into several of the same problems.

Docbook XML

Docbook was the favorite.  This was easy to say because Matthew said "It's my favorite".  If you are familiar with XML you are already familiar with Docbook, though there are some specific tags and attributes that you need to use.  I found some information on Docbook Stylesheets that might be interesting to highlight some of those.  Some of the benefits of Docbook are that it is reasonably easy to understand and because Docbook is really just an intermediate language you can use it as the glue between various documention formats.  Because it is in a highly structured format it can be both easily translated and it also supports versioning.  One thing to note is that because code can mess up the XML format that most of your code examples should most likely be written within CDATA tags.

The thing to note is that most people can't read XML directly, so you need to render it in the format.  One of the options you have is the PHP Docbook renderer.

Additional documentation

Documentation doesn't necessarily mean "documentation".  Documentation can be a myriad of other things.  It can be

  • Tutorials
  • Installation instructions
  • Examples
  • FAQs
  • Forums
  • User contributed

Lorna said something interesting that I thought was pretty important.  "If you don't know where to get started with an open source project, work on examples."  In other words you know the software, but you don't want to break something so you're unsure as to where to start.  Want to know where to start?  Examples.  There you go.

Be a User-Contributor

  • Answer forum questions
  • You don't need to be an expert
  • Hang out on the IRC channel
  • Help wirth project docs
  • Blog
  • Don't think of yourself as a consumer

The one here that I found the most interesting was that you don't need to be an expert.  Talking to the "experts" can be a little daunting.  They're the experts!  No they're not!  My definition of an expert is someone who knows enough to know they're not an expert. 

Testing

Why test?

  • Makes future maintenance of the code easier
  • Defined expectations
  • Test known behaviors
  • Identify early when changes in code break existing behaviors
  • Quantify the quality of your code
  • Code Coverage (not the best metric, doesn't tell the quality of the test)
  • Self-documented behaviors via unit tests

What is not testing?

  • Reloading – In other words, hitting F5
  • Var_dump()

What is testing?

  • Reproducible
  • Automatable

Test Driven Development

Test driven development is a methodology that I have become a recent convert to… big time.  Every customer I have talked to about it has become believers in test driven development.  Zend Framework uses test driven development.  I won't go into how to do it, though I did do a video on it that you can check out.

A couple of things to note about test driven development.

  • Write code to make the tests pass
  • Allows for playing with the API's before you've committed to coding them
  • Often hard to get into the rhythm; once you do it's hard to quite

I would like to spend more time on the subject but that's all I have time for.

Conclusion

I was hoping to end this with part 2 but there's still a lot to cover (Matthew and Lorna had a lot of information).  So I will work later on to finish up with part 3.

Best Practices – Part 1

I am in the middle of Matthew Weier O'Phinney and Lorna Jane Mitchell's talk on PHP Best Practices and after the 3 pages of notes I took in the first hour I wanted to get some things down on virtual paper before getting too far into it.  There is a lot of information that they're giving out.

Source Control

The first thing they talked about was Source Control.  Unfortunately, I was doing my writeup on MongoDB and I missed a bunch of stuff.  That said, there were two things that I had time to write down.

The first thing was "If you are not using Source Control, START!"  I have to agree.  It'd be silly if I disagreed.  The only real question is which source control to use. For that there was a list provided from Wikipedia that gave a comparison of different version control systems that looked pretty useful.

Coding Standards

The next section that they started talking about was that of Coding Standards.  There are a few ways that you can know if you don't have a coding standard.

  1. You reformat it
  2. Code you wrote 6 months ago looks different from today
  3. Modifying old code introduces syntax errors

When trying to determine whether or not you need a coding standard ask your self the following questions.

  1. Can you read your own code
  2. Can others read your code
  3. Can you read someone else’s code
  4. Can you switch between code bases easily

Coding standards assist in the maintainability and collaboratibity of your code.  What this means is that you can have more people working on your code.  Code is structured predictably.  When something is predictable it is easier to have someone new work on your code.  Coding standards decentralize who can work on code.  In other words, when you're on vacation and you don't want to be bothered by some emergency code change that needs to be done you can simply pass it off to someone else who can get working on it faster than you can get to a computer.  And really, after having several umbrella drinks on a Caribbean beach somewhere, would people really want you working on code?

One of the statements  I really appreciated was the statement; "Don’t write your own coding standards!!!  There is nothing special about your code."  When I was working in Zend's Services department I would work hard to encourage customers to embrace some kind of coding standard.  I didn't care which, but they had to chose one.  OK, well, that's not entirely correct.  I told them to use the Zend Framework coding standards because they have already born themselves out in the real world.  But the Zend Framework coding standards were no different from the PEAR coding standards (which ZF stole from) which was no different from the Horde standards (which PEAR stole from).  In other words, the problems that people were trying to solve did not change.  There were some updates made to handle some new cases, but for the most part, the coding standards have been relatively static.

Design Patterns

Design Patterns for me are a bit of a double edged sword.  On one hand they solve a very useful purpose.  They provide common solutions to common problems.  The problem is that there are so many problems that need to be solved that there are, in my mind, too many design patterns.  In other words, because there are so many potential gloves to fit the hand people sometimes worry too much about getting the exact right design pattern.

That said, Design Patterns have a great use if you don't become too overburdened by them.  Lorna did a great job about describing some of the more pertinent.  but she also said something important; "don't invent reasons to use design patterns".

Factory

  • Has methods to create and return objects
  • May return different objects
  • May use complex logic to work out the returned object

Registry

  • Can be a singleton but not a requirement
  • Register them here but access them elsewhere

Adapter

  • “Adapts” a specific interface to fit something else
  • Allows the class wrapped by the adapter to exist independently from the component

Root cause analysis – Client got a bit of knowledge!

Decorator

  • Wraps another class in order to modify its behavior
  • Target class doesn’t change
  • Decorating class often implements the same interface
  • Can be visually decorative, but not always

This one was the most interesting to me because you don't see it much in PHP applications, but the example that Lorna showed looked eerily similar to Swing layouts.  The example looked something like this.

interface LabelIterface
{
    public function render();
}

class BasicLabel implements LabelInterface
{
    public function render()
    {
        return $this->lable->render();
    }
}

class LabelNewLineDecorator extends BasicLabel
{
    public function render()
    {
        return $this->labout->render() . "n";
    }
}
class LabelStarDecorator extends BasicLabel
{
    public function render()
    {
        return '** ' . $this->labout->render();
    }
}
class LabelHyphenDecorator extends BasicLabel
{
    public function render()
    {
        return str_replace(' ', '-', $this->labout->render());
    }
}

You have some basic functionality, but it is easily extendable.  It "decorates" the original class.  Neat.

Observer

  • Watches for changes in another object
  • Responds to those changes
  • Target class is aware, notifies observers

I was thinking about this and this sounds a lot like the Zend Framework plugin and action helper functionality. 

Matthew and Lorna are getting up and running again so this is where I'll stop.  Nevertheless, I made a really good call in attending the Best Practices talk.

Web Analytics