Posted on

Netbeans, phpDoc, and WordPress

A posting from our private “Tech List”, a list I share with select tech geeks mostly from the days at Cyber Sprocket Labs.   We tend to share high end tech tips that only geeks would find interesting.    I am posting here for easy reference for “The Tech List” groupies.

My Intro To Netbeans

9 months ago Chase was showing me NetBeans on his desktop.   It had some cool features for PHP like auto-complete and some very handy code lookup tools that reminded me of Visual Studio without all the weight.

 I wish I had learned about the NetBeans environment a long time ago.    NetBeans+ GitHub + SmartGit have made my coding at least twice a productive when it comes to PHP work, especially with complex WordPress plugin code.
In the past few months, while working in NetBeans, I’ve been refining my phpDoc skills.  This is EXTREMELY handy in making coding far more productive.    Here are some of the things I’ve learned that I wish we had all known about at Cyber Sprocket.    With the right tools it makes coding for people with senility (me) easier.

Effectively Using Netbeans for WP Dev

1) Wrap your ENTIRE plugin into a single instantiated object.
My plugin invocation now is basically something along these lines:
DEFINE(blah,blah) // a few of these help with WordPress stuff, like plugin version
class MP {
}
class MP_Error extends WP_Error {}
add_action('init', array('MP','init');
That is pretty much it other than the singleton.
2) Learn how to create and use singletons PROPERLY in WordPress
It must be a static method.
It should return itself as an instantiated object.
Set minimal properties as needed, not the entire WPCSL object here.
public static function init() {
    static $instance = false;
    if (!$instance) {
        $instance = new MP;
    }
    return $instance;
}
3) phpDoc the class
In netbeans you go back to just above class MP {} and type /** after starting the frame of the class with properties and methods in place.
It will AUTO-CREATE the template PHP docs.
First line of comment = 1 line description
Lines 3..m = a longer description if you’d like
Lines m+1..n = the properties defined with @property, @property-read, @property-write    (the setters/getters with r/w, r, w status)
These property lines, like variable lines are simple:
@property-read <type> name  description
for example
@property-read string plugin_name the plugin name
This indicates a read-only property for the object.
4) phpDoc the methods
 
Like classes, but NetBeans is even better with the docs, you write the function first.   Then go before the function foo() line and type /**.   NetBeans will create the entire phpDoc template.   You update it to give it the “hints”.
This is something I use a LOT now and you’ll see why in a moment.   Here is an example from WPCSL_Settings add_section:
Old school:
/**
* method: add_section
*
* does stuff
*
* params:
*     [0] - named array, blah blah
**/
New:
/**
 * Create a settings page panel.
 *
 * Does not render the panel.  Simply creates a container...
 *
 * <pre><code>
 *   $mySettings->add_section(array('name'='general'));
 * </code></pre>
 *
 * @param array $params named array of the section properties, name is required.
 **/
5) If your phpDoc property/variable type is a specific OBJECT then NAME THE OBJECT. 
For example:
class MP {

   /**
    * The WPCSL settings object, shortcut to the parent instantiated object.
    *
    *  @var wpCSL_settings__mp
    */
    private $wpcSettings = null;

}

Why I Am More Productive

Now here is why all these tips with phpDoc are useful and how I’ve slowly made my coding at least twice as efficient.
NetBeans defaults to having code hints and auto-fill turned on.   The cool part about this is it will do a few things like tell you when a required param is missing and flag the line as an error, the same way it does with blatant PHP syntax errors.    If you are creating some new code and you pause for a second with a partially written invocation then it will show you the possible options from a list of PHP functions, custom functions, or methods from objects you’ve phpDoc’ed properly.
Thus, I do something like this:
$this->wpcSettings->a   <pause>
It now shows me all the methods and properties in the WPCSL Settings Class that start with a in an in-place drop down list.
I cursor down to add_section and pause.
It shows me the full documentation on the method including my code example, the required parameters and more.
I press enter, it drops the completed method along with the first prototype in place, I cursor down to select from the various templates, for example if secondary parameters are optional, press enter and if fills out the entire code block.
I then modify the prototype to fill in my settings and I’m done.
If you do this right you can be ANYWHERE in your code as deep as you need to be.   You never have to go looking for the source, especially if you’ve written decent phpDoc comments.
I used to find myself split-screen looking at the source method or property code to see what it did or how it worked.    Now I spend time documenting the methods or properties in a verbose phpDoc comment and I never have to look at the code again.

Key Points

If you do NOT wrap everything inside a parent class it takes a lot longer to pop up the help.
If you just use the lazy @property object $myvar (or ‘mixed’) syntax you do not get to see all of the methods whenever you newly instantiated object is referenced by the variable name.
If you use things like public, private, setters, getters and use the matching phpDoc elements like @property-read  then NetBeans warns you if you do something illegal like try to directly SET that property.

A Day Older, A Day Smarter

I know some of you probably had productivity helpers like this while at Cyber Sprocket, but if I had known then what I know now I’d have been insisting that we all learn and properly implement phpDocs as our commenting standard.
An as you all know the other “freebie” with this is I could easily generate a full HTML (or markdown) site with all the classes, methods, and properties of any plugin with a few short commands.   I’ve not done that yet but will play with that sometime in the near future.    I need to figure out how to bake it into WordPress content at charlestonsw.com but I think it would be cool to have an entire plugin + wpCSL documented in an easy-to-browse format on the web.
Posted on

SmartGit Tips & Tricks

I have been using SmartGit (http://www.syntevo.com/smartgit/index.html) for nearly a year now.   After having used command-line git and the graphical log viewer, gitk, I have become very accustomed to using SmartGit for managing my code repositories.   After a short learning curve I have become fairly proficient in managing my branches and general code repository issues.

Here are some tips & tricks I’ve learned along the way.  Granted, not many listed here yet, but hopefully other SmartGit users out there will share.

Tagging Code

Tags are very useful for marking key positions in the repository without creating a branch.   We use this at Cyber Sprocket to tag the commit that represents a specific product release.    SmartGit makes this easy, but you will need to create a private key.   Look for our articles on creating OpenSSH keys using PuttyGen to create your key file.

Once you have your key file you can attach it to a project when you set the project up.  SmartGit will store that key for future use, making for easy tagging of your repository.

At this point tagging the repository is easy:

  • Open the log viewer.
  • Right-click on a commit and select “Add Tag”.
  • To publish the tag back to the origin server go to the working tree/project window and select “remote / push advanced” and select the “push selected branches or tags”.  That is where you can select the new tag and push it back to origin.

Finding A Commit By ID

Even though SmartGit is very good at managing branches and encouraging plain text labels for branches and tags, there are times when the only way you can find a specific commit is via the SHA-1 commit ID.    For months I’d been using the command line to locate those commits and manage them, often just to add a tag or a branch so I could find that key commit at a later date.

Turns out SmartGit has an easy, if somewhat hidden, way to find a commit.

  • Bring up the log window.
  • Start typing in the SHA-1 key -or- press ctrl-v to paste in a hash you’ve copied

SmartGit will locate the first matching commit ID doing the typical fast search/filter as you continue typing.

 

Those are my two tips & tricks for today.  If you have any, please share.