Behind the Curtain at TCG

PHP Code Review Checklist

I recently created a code review checklist for a PHP based project I was working on.  If you want to be pedantic, it's actually a list of questions that the reviewers should ask themselves as they look through the code.

This isn't an exhaustive list and it's not meant to be.  The only thing you will get from making an all-encompasing code review checklist is a list the your reviewers will ignore.  I'm depending on my team to be smart, autonomous, rational, and wise.  Perhaps I am idealistic, or maybe I'm just lucky to work with a great group of engineers.  The final version is still under development, but I wanted to share what I think is important when doing a "formal" code review.

Questions to consider while reviewing code:

1. Is the code readable as written?  Does it require additional comments, better naming, or general refactoring to be easily understandable?  Does the code generally conform to the style of coding for the project?
2. Does each function contain a (very) brief comment describing functionality, inputs, and outputs?
3. Does new code keep business logic away from presentation code?
4. Is identical functionality repeated multiple places in the code base?
5. Are there any code blocks that should be abstracted into functions or classes for maintainability?
6. Are there any hard coded constants that could possible change in the future?
7. Are all reasonable error conditions handled?

These questions are shaped by my personal experiences and the kinds of projects that I work on.  Some of them won't be applicable to another project, or even if they are applicable, they might not be necessary. They are also very subjective.  Decisions made while writing software are rarely black and white.  What is readable code for one person might be opaque for another coder who has a different skill set.  "Reasonable" error conditions may differ based on how critical this application is.  Consequently, I think code reviews are best when they are discussions and opportunity for learning.

There was another group of questions that I thought were important, but aren't really code related.  They probalby won't become part of our checklist, but I think they are interesting none the less.

1. Are the requirements formalized in writing and tracked/managed properly?
2. Are the requirements clear and unambiguous?
3. Is there a testable scenario that can exercise the new/changed requirements?
4. Was the code tested by someone other than the author? 
5. Did the modified code satisfy all the current system requirements?
6. Did the test scenarios exercise all the changed code paths?  If not, is there a good reason for that?

For me these questions are more like project wide diagnostic tests.  If you are running over schedule or you are getting a lot of bug reports back from the downstream users, asking these questions may help explain why the code creation process isn't performing as well as expected.

Effective Image Buttons for HTML5 Mobile Apps

Mobile application development doesn't always mean native apps for iPhone and Android.  If you are an experienced web developer you can use HTML5 to make great apps that have a great look and feel.

I'm working on a small HTML5 mobile app that uses toggle buttons to set the application state.  For my app, I have a bank of buttons that have two states "in" and "out".  Here is what they look like:

I used Gimp to create the buttons as PNG formatted images with transparent background.  On my first iteration, I setup the buttons using simple HTML img tags:

<img src="Images/blue_in.png" state='in' colorname='blue' onclick="toggleButton('blue');"/>
<img src="Images/reg_in.png" state='in' colorname='red' onclick="toggleButton('red');"/>
<img src="Images/green_in.png" state='in' colorname='green' onclick="toggleButton('green');"/>

As you can see, I am storing the state of each button in the img tag itself. The toggle function looks at the current state and swaps the image around, like so:

            function toggleButton(color) {
                var button = $('.button_img[colorname=' + color + ']');
                var colorname = button.attr('colorname');
                if (button.attr('state') == 'in) {
                    button.attr('state', 'out');
                    button.attr('src', 'Images/' + colorname + '_out.png');
                } else {
                    button.attr('state', 'in');
                    button.attr('src', 'Images/' + colorname + '_in.png');
                }
            }

The first thing I noticed in testing was that on my Android device I was getting a very annoying green box highlighting the images when I clicked them.  You can disable this with a bit of CSS that sets the highlight color to transparent.  So I added this to my CSS:

.button_img { width: 100px; height: 100px; -webkit-tap-highlight-color:rgba(0, 0, 0, 0); }

So now things are looking better, but the performance isn't really up to the standards of a native app.  When you click on a button it takes about half a second for the state to change.  My goal is to make this HTML5 app every bit as good as it's native cousins, so this delay will never do.  The problem is that I'm binding my toggle code to the onclick event.  Due to the nature of a touch screen device, the onclick event has something close to a half second delay between the time you touch the screen and when our javascript is triggered.  A better choice is to bind to the touchstart event.  That is called immediately when our button is pressed without any undo delay.  This code is a little trickier because you can't define it right in the img tag.  You can do all this with standard JavaScript using the addEventListener function, but I love jQuery, so my new code looks like this:

          $(document).ready(function () {
                $('.button_img').each(function () {
                    $(this).bind('touchstart', toggleColorTouch);
                });
            });

            function toggleColorTouch(e) {
                toggleButton($(e.target).attr('selectcolor'));
            }

Ahh, now this is looking really good.  One final thing is missing though...there is no auditory or tactile feedback.  That's not everyone's cup of tea, but if you want it is easy enough to add.  You can trigger audio feedback using HTML5's audio tag and API.  Just put this audio tag in in your HTML:

    <audio id="sound_click" src="click.wav" preload="auto"></audio>

Then when you toggle the button, trigger the sound:

            function toggleColorTouch(e) {
                document.getElementById('sound_click').play();
                toggleButton($(e.target).attr('selectcolor'));
            }

Older Android devices have some lag problems with the audio tag.  So if you are targeting Android, either use an alternate method or make sure you test this out on the devices you want to support. 

Standardized Grants Forms: It's Hard to Make It Easy

Victoria Collin from the Office of Management and Budget spoke at the National Grants Management Association’s November training session about the new Council on Financial Assistance Reform. The Council was created by the White House in October to make sure that the money others spend for the government is spent correctly and produces results. In return, the government is going to look at how to make it easier for people and organizations to apply for that financial assistance.

One of their aims is to better standardize grant applications across the Federal government to relieve some of the burden on applicants. This is difficult, as Federal grant programs cover so many different areas. Just as a challenge, I tried to come up with a standard application for three grant programs, Amtrak, WIC (Women, Infants, and Children), and cancer research. All have applicants, all represent social needs that deserve Federal support, all transfer resources from one entity (the Federal government) to another (the grant recipient).

So here is my form that would cover all three equally:

1. Name of the program to which you are applying:
2. Your name:
3. Your address:
4. Amount requested:
5. What you will do with the grant:
6. When you need it, and how long it will meet your need:
7. Why we should give it to you and not someone else:

I thought about a lot of other fields, like “How we will know that you are using the grant for what you say,” or “Name the Congressional district that will benefit,” or “List the deliverables you will produce,” or even “Give the number and names of unemployed veterans you will hire, how long each has been out of work, and the highest education level for each,” but the first question doesn’t make sense for the poor pregnant woman who gets two gallons of milk through WIC; the second doesn’t work for Amtrak; the third doesn’t easily apply to cancer research, and the fourth, as worthy as its goal might be, is just annoying.

I understand that it’s complicated to apply for grants, but if you want to spend someone else’s money, you are going to have to go along with someone else’s rules.

Nevertheless, the Council on Financial Assistance Reform will try to make the rules simpler in four aspects of the Federal grants enterprise:

• Fair and transparent award-selection procedures
• Government-wide reporting requirements, to emphasize results and allow government to blend funds and programs
• Consistent treatment of direct and indirect costs
• Risk-focused audits, looking for waste, fraud, and abuse

I wish them luck.

I’ve got to give a shout-out to Victoria Collins. She exhibited my favorite three best presentation practices:

1. Her slides were bullet points, charts, and pictures, not paragraphs, making them easier and more interesting to read.
2. She did not read her slides, she spoke to them, so we in the audience could follow along but were not distracted by reading ahead of her. We could listen.
3. Most difficult, she repeated questions before she answered them. Her audience was knowledgeable, so the questions were complicated, with a lot of explanation. She pulled the essence out of each question, and repeated it before she answered it. That is really tough to do, because the temptation is always to start formulating your answer as you listen to the question; she had to pay close attention to what the questioner was saying, and figure out how to rephrase it gracefully and accurately -- and then answer it.

Well done, Victoria.

Identifying Grants Fraud an Updated Old-fashioned Way

Recovery.gov has been touting its ability to identify waste and fraud in Recovery Act grants, and other grantmaking efforts are taking note. But the most successful methods are also the old-fashioned ones (albeit updated with technology).

The outgoing head of the Recovery Board, Earl Devaney, says his analysts have searched "massive amounts of data for criminal convictions, lawsuits, tax liens, bankruptcies, risky financial deals and other telltale signs of problems," in their oversight of their grants programs. Yet witnesses and gumshoeing are still the best ways to find ne-er-do-wells.

According to the Recovery.gov website, there were 8,032 reports of waste and abuse in Fiscal 2011, of which almost 1,800 resulted in investigations, and three-quarters of those resulted in actions. Another large group of miscreants and would-be miscreants was found by visiting them electronically at their locations -- and finding parking lots, warehouses, and storefronts standing in for community, retraining, and health centers.

These two discovery techniques are not new. They have been a part of crime fighting since the first detective found the first thief. But they were abeted by technology: many of the reports came in electronically through the website;  mapping software allowed electronic "visits" to applicants' addresses, and cross-database searching let Recovery Board analysts link addresses to multiple applicants and to business names and descriptions.

It's getting harder and harder to be a crook these days.

 

GAO Says FMCSA Grant Management Still a Risk

The Government Accountability Office says that while the Department of Transportation's Federal Motor Carrier Safety Administration had made strides in improving its grants management since the GAO audited the agency in 2010, it did not go far enough. A new report, issued this month, faults the agency for not doing a better job formalizing its grants management policies, training its staff in those policies, and involving its lawyers in reviewing grants. "Some challenges remain," the report says.

An overview of the GAO report may be found at http://www.gao.gov/highlights/d12158high.pdf; the full report is not currently on the GAO site.

GATB Proposes Standard Grants Identification System

The Government Accountability & Transparency Board submitted its first report to the President, and suggested that the government adopt "a single identification system that can provide clarity on Federal awards and be managed from a single, centralized source." The idea came from the Recovery Act's Recovery Accountability and Transparency Board, which had a similar recommendation for its programs.

The GATB's two other recommendations were likewise based on the RATB actions: to streamline and integrate how the government collects and display data, and to use technology to track spending. More information on  GATB may be found on the White House Blog.

 

Telework Exchange to Host Complimentary Webcast

The Telework Exchange, an Alexandria-based public-private partnership focused on demonstrating the tangible value of telework and serving the emerging educational and communication requirements of the Federal teleworker community has announced that it will host a complimentary Webcast titled “From Planning to Preparedness: Build Your Telework Strategy” on January 19, 2012 from 1-2 p.m. EST. The Webcast will focus on planning for Telework Week (March 5-9, 2012). Federal, state, and industry representatives will discuss management considerations and technology requirements to address when preparing for business continuity exercises, including Telework Week 2012. For more information and to register click here.

NIH Awards NITRC Phase II Contract to TCG

The National Institutes of Health (NIH) has awarded TCG a four-year contract to continue its support of the award winning Neuroimaging Informatics Tools and Resources Clearinghouse (NITRC), a user-friendly collaboration environment for the neuroinformatics community. This support will allow NIH to enhance and expand NITRC’s scientific scope and add new types of resources. To read the full press release, click here.

10+ Years of Telecommuter Wisdom

I have more than 10 years experience as a telecommuter.  Every year I learned something for myself that would have been nice in a set of guidelines to have before I started to work from home.

Year 1: Cancel your cable television.  You will get a lot more done in and out of work.
Year 2: Your bedroom does not make a good office.  Use a dedicated room....with a door.
Year 3: A 5 or 10 minute daily phone check-in with your team can save hours of work later.
Year 4: Be careful writing e-mail.  It can easily offend or be misunderstood.
Year 5: Just because you are “home all day" does not mean that you can babysit your nephew.
Year 6: Wake up on a schedule, work on a schedule.
Year 7: Get an animal companion. 
Year 8: Go outside and see the unfiltered sun at least once every day. 
Year 9: If you still have a land-line coming into your home, don’t answer it when you are working.
Year 10: Get exercise when you can.  It keeps you sharp and awake during the day.

Looking back at my list, I see that these items divide into two categories: ideas that help you to work harder and ideas that help you to get away from work.  Paradoxically, telecommuters suffer from both problems.

To help you work harder you need to bring in the good bits about working in an office.  During work hours, you need to focus on work.  That's a lot easier to do sitting in a cube farm with the rest of your team than sitting at your kitchen table by yourself...with last nights dishes in the sink and every other distraction of your personal life surrounding you.  Every hour you skip working from 9-5 is another hour you need to make up in the evening or weekend.  And that is no fun.  I learned that very quickly.  The solution that worked for me was to make my home office environment feel a lot more like a regular office environment.    

If you have a dedicated room for your office you are surrounded by the trappings (pun intended) of your work life.  Having a door keeps the sounds, and possibly children, of your home life at arms length during business hours.  A 10 minute "stand up" phone conference keeps you in sync with your peers the just as well as stopping by their desk a couple times a day.  Finally, keep as far away from daytime television, classic movie reruns, and 80's era sitcom reruns as possible.  For me, killing my television was the best way to do that.

Then there is the other side of things: feeling like you are working all the time.  When you are in the middle of a big project it is easy to get sucked back to your desk for "just a minute" after dinner.  Colleagues working on a different schedule will still call your desk phone seeing if they can catch you for a question.  When I work at home I don't really break for lunch...I just bring food to my desk to eat.  Then when you finally decide to get away from work, just seeing your office when you walk down the hall can keep you from mentally getting away from work...ever.  These things just don't happen when you work outside the home.

Keeping to a 9-5 schedule, or whatever works for you, gets you in the habit of being away from work for the evening.  I'm lucky because my kids get home from school at 4PM.  That's my quitting time.  I get up early and have a full day's work done by then.  In the best case, I don't even think about work until 6:30 the next morning.  It is necessary to get some down-time if you want to be efficient the next day.  Owning a dog ensures that I will have to get up to take care of it a couple times a day, maybe even a nice 30 minute walk in the fresh air at lunch when the weather is good.  Regular exercise is necessary for everyone, especially us folks sitting at a desk for 8+ hours a day. 

These rules work for me.  Everyone is different and they might be just the change you need to start loving your telecommute job with all your heart...or you might need to do things differently.  Either way, if you have the opportunity to try working from home, I recommend it.

Elegant Code's Wonderful Blog Series on JavaScript

Up until this point, JavaScript was something I held my nose and used to get dynamic and Ajax interactions working on my websites.  jQuery made it more tollerable with its mysterious "$" syntax and its ability to zip through the DOM tree and manipulate CSS.  But over at Elegant Code, Jan Van Ryswyck has done an impressive job putting together 12 posts on JavaScript that are short yet very instructive and interesting.  I suggest it for any developer who wants to understand a bit of the magic and possibly improve their perception of JavaScript:

1. Functions
2. Objects
3. Prototypes
4. Enforcing New on Constructor Functions
5. Hoisting
6. Automatic Semicolon Insertion
7. Static Properties and Methods
8. Namespaces
9. Reusing Methods of Other Objects
10. The Module Pattern
11. Functional Initialization
12. Function Hoisting

Thanks Mr. Ryswyck!