// Internet Duct Tape

Searching for the Perfect Inline Code Documentation Tool

Posted in Programming Tools, Ruby, Technology, Writing Better Documentation by engtech on March 07, 2008

Programming Tips

Even amongst programmers I’m weird because I have an intense love for documentation. No, that doesn’t mean I overly comment my code, or that you’ll catch me browsing happily through the product requirements document during my coffee break. I should be more specific.

engtech-documentation-unravelling.png

I have an intense love automatic documentation generation. Nothing makes me more tickled pink than seeing code and documentation living side by side in perfect harmony. I hate seeing documentation put on the company intranet only to diverge from the code it’s supposed to explain as the days go past. I hate hitting my head against a brick wall as I’m pouring through the source code trying to understand an API because at no point does it mention that it’s documented in a Word doc in another directory.

This is my rule of programming: documentation should live beside the code it documents, in the comments, especially if it’s API documentation. If your language of choice doesn’t already have some kind of automatic code generation tool then you’re probably using the wrong language.

(more…)

How to Profile Greasemonkey Scripts with Firebug

Posted in Firefox and Greasemonkey, Programming Tools, Technology by engtech on November 13, 2007

Programming Tips

Running performance analysis on Greasemonkey scripts can be a pain in the butt. They aren’t part of a webpage so standard tools for analyzing web sites don’t work… or do they?

The Goal

Profiling Greasemonkey scripts with Firebug

What You’ll Need

  1. Firefox
  2. Greasemonkey
  3. Firebug extension

The Trick

#1: You need to remove all of the Greasemonkey GM_* functions from the script you want to profile. This is easier than it sounds because all of the functions can be performed by plain ‘ole javascript (except for the open in new tab function and register menu command).

#2: You need to embed your Greasemonkey script inside of the running page so you can analyze it with Firebug’s profile tool. I have a function below that can embed a function inside the current web page.

#3: You’ll need to call the function either using unsafeWindow or by embedding a call to the function in the page.

#4: Litter your code with calls to Firebug’s console.profile() and console.time() functions.

Sample Code Template


(function() {
  function embedFunction(s) {
document.body.appendChild(document.createElement('script')).innerHTML =
s.toString().replace(/([\s\S]*?return;){2}([\s\S]*)}/,'$2');
 }

  function myKickassGreasemonkeyScript() {
    console.profile();
    // Put everything you need for your Greasemonkey script in here
    // Don't use any of the GM_* functions!

function kickass() {
      console.time("Block1");
      // Block of code that might take a lot of time
      console.time("Block2");
      // another block of code
      console.timeEnd("Block2");

      console.timeEnd("Block1");

    }

// more cowbell

console.profileEnd();
  }

  embedFunction(myKickassGreasemonkeyScript);
  // Method 1: embed the function call into the current page
  document.body.appendChild(document.createElement('script')).innerHTML = "myKickassGreasemonkeyScript();";
  // Method 2: directly call the function using unsafeWindow
//     window.addEventListener("load", function(e) {
//                   unsafeWindow.myKickassGreasemonkeyScript();
//                   this.removeEventListener('load',arguments.callee,false);
//                 }, false);

 })();

Firebug Tutorial

Michael Sync has a tutorial on using Firebug that describes the console.time() and console.profile() functions. The official website has a nice list of Firebug keyboard shortcuts and a brief description of all the console.* functions.

Related Posts

Using Mind Maps to Explore User Interaction

Posted in Programming Tools, Software, Technology by engtech on August 31, 2007

I’m “fortunate” to work at one of those companies where meetings are a way of life. Not only do meetings happen daily, but everyone and their dog is invited. Well, until one of the dogs bit an intern. Now the dogs are free to keep working on their projects, but everyone else is still stuck in needless meetings. The only good thing that has ever come out of these meetings is that I’ve developed a passing familiarity with mind mapping software.

Mind mapping is a technique for taking notes. You start with a central keyword or idea and then build up an ever expanding structure from around that starting point. I might have learned this before in grade three, but the Internet seems convinced that it’s the latest and greatest new thing. Note to self: go through kindergarten notebooks and search for ideas that haven’t been copyrighted. Mrs. Nelson, you will be my goldmine. Now I feel bad for falling asleep during story time.

mind map example

You can do mind maps easily by hand, but you can also use free or pay software to build them. It is a great technique for capturing the minutes and action items in a meeting because it is so freeform yet structured. But you don’t have to take my word for it, LifeHacker has given examples of writing mind maps for meetings, and Kathy Sierra has given mind maps a big thumbs up.

Back to the meeting.

I’m putting an appointment on my smartphone that I hate, and as usual I’m frustrated by how needlessly complicated their user interface is. Sell stock in Nokia and buy stock in Apple — you won’t go wrong. That’s when I remembered something I wrote in a blog post about how their UI design wouldn’t have hit the ground if someone had just drawn it out and realized that it takes 10 user interactions to place a phone call. I looked up at the projected mind map on the wall and I realized that I was looking at the perfect software for doing something like that.

Mind mapping begins with a central keyword, but instead you can think of that as the first screen in your application. Each depth in the mind map will represent a user action. One you have mapped out all the actions you can see the overall cogitative load of your program clear as day. Take a second to look at a mind map I did of the WordPress.com blog interface.

mind mapping a user interface

Once the big blob of your UI is mapped you can at a glance look at the most common actions a user would have to perform and see how many interactions it takes to get there. You could even use a mind map to design how content is linked on your blog and how hard it is to use. Admittedly, drawing out a UI like this is nothing new, but using mind mapping software for it is so damned convenient.

Key Points

  • Mind mapping software is not just for note taking and meetings
  • It can be used for mapping user actions
  • The finished diagram can be used to optimize the most important actions and clearly see what actions are redundant or unnecessary
  • The finished diagram makes a great 1 page tear sheet to help users remember where everything is

More Information About Mind Maps

Emacs Wiki

Posted in Links, Programming Tools, Technology by engtech on June 01, 2006

It really seems like wikis have hit a critical mass and everything has a wiki now. Here is the wiki for Emacs support: http://www.emacswiki.org/

Comments Off

Emacs, emacsclient and gnuclient.

Posted in Links, Programming Tools, Technology by engtech on June 01, 2006

For those of us who use Emacs as our text editor, there is one major problem: it’s a memory hog. That’s why it comes with a client application so you can open files from a separate process into an existing Emacs (server). This reduces the memory usage as you only have one process of the editor running. (Note: If you are already in the habit of always opening files from within Emacs instead of within a shell then this won’t really give you any enhancements). This application is called:

Although the three clients all offer the same basic functionality, it is generally considered that gnuclient has richer features.

Martin Schwenke provides a port of gnuclient for GNU Emacs at http://meltin.net/hacks/emacs/gnuserv/.

He also has a shell script called dtemacs that can integrate Emacs into a desktop environment like Gnome, KDE or CDE. If Emacs can not be contacted using gnuserv, Emacs is executed and left iconified. Either way, a new frame is opened to edit the specified files.

Comments Off

How to move all gnu emacs backup files to their own directory

Posted in Links, Programming Tools, Technology by engtech on May 28, 2006

Emacs (Gnu Emacs or XEmacs. Read about the difference at xemacs.org) is a robust text editors (plus a whole lot more). One of the features that drive me crazy is the backup files it creates whenever text is editted (editting README.TXT will create README.TXT~ in the same directory). There is a lisp package called "autosave" that will put all the autosave/backup files in a separate directory so that you don't clutter your workspace.

This link contains settings for your .emacs (or custom.el) file that will properly configure autosave for GNU Emacs or XEmacs.
snarfed.org :: gnu emacs backup files

Free CVS Book – Open Source Development with CVS, 3rd Edition by Karl Fogel and Moshe Bar

Posted in Book Reviews, Links, Programming Tools, Technology by engtech on May 27, 2006

"Open Source Development with CVS, 3rd Edition" by Karl Fogel and Moshe Bar is available as a free PDF download under the GNU GPL. It can also be browsed online in HTML. There is also a lengthy article available talking about CVS best practices.


Comments Off

Configuration Management wiki — build management, version control, bug tracking

Posted in Links, Programming Tools, Technology by engtech on May 19, 2006

The Configuration Management wiki. It looks a bit disorderly, but there may be some good nuggets of information to glean amongst the dross. It looks like the most fleshed out section is the list of available tools (covering build management, version control, defect management and merging).

The fundamental purpose of Configuration Management is to establish and maintain the integrity and control of software and hardware products (e.g. servers, source code, patches, documents, CPU’s etc) throughout a project’s life cycle.

Effective configuration management can be defined as stabilising the products artifacts and process (activities) at key points in the life cycle.

CM < CmWiki

Comments Off

Apache Ant (Java-based replacement for Make) User Manual

Posted in Links, Programming Tools, Technology by engtech on April 27, 2006

Apache Ant is a Java-based build tool. In theory, it is kind of like make, without make‘s wrinkles.

Why?

Why another build tool when there is already make, gnumake, nmake, jam, and others? Because all those tools have limitations that Ant’s original author couldn’t live with when developing software across multiple platforms. Make-like tools are inherently shell-based: they evaluate a set of dependencies, then execute commands not unlike what you would issue on a shell. This means that you can easily extend these tools by using or writing any program for the OS that you are working on; however, this also means that you limit yourself to the OS, or at least the OS type, such as Unix, that you are working on.

Makefiles are inherently evil as well. Anybody who has worked on them for any time has run into the dreaded tab problem. “Is my command not executing because I have a space in front of my tab?!!” said the original author of Ant way too many times. Tools like Jam took care of this to a great degree, but still have yet another format to use and remember.

Ant is different. Instead of a model where it is extended with shell-based commands, Ant is extended using Java classes. Instead of writing shell commands, the configuration files are XML-based, calling out a target tree where various tasks get executed. Each task is run by an object that implements a particular Task interface.

Apache Ant User Manual

Comments Off

Eclipse IDE – demo of using Eclipse with Java and Glade to create a simple GUI

Posted in Links, Programming Tools, Technology by engtech on April 20, 2006

This is a flash demo by Andrew Overholt using Eclipse IDE to build a simple Java app.

>> http://people.redhat.com/overholt/nativeeclipse/index.html

Follow

Get every new post delivered to your Inbox.

Join 286 other followers