loading...

Joel's Checklist

joelbennett profile image Joel Bennett ・5 min read

To quote the late Randy Pausch, "Experience is what you get when you didn't get what you wanted". Most of the time you want your software products to be build smoothly, your deployments to go out without a hitch, and your customers to be happy. But that doesn't always happen. Over the course of the last few years, I've got my fair share of "experience". Every time I've run into something, I've tried to make a note of it so that I don't run into it again. You know - fool me once, shame on you. Fool me twice, shame on me...

This has slowly morphed into "Joel's Checklist". Checklists aren't the best way of handling things, as they won't catch every case, but at least by going through a checklist of things you've messed up on, you can check to make sure you aren't going to run into that same issue again. There's a reason that pilots go through checklists. Our particular team isn't very diligent at following this, but I've still found it to be helpful from time to time, so I figure it's worth sharing.

Keep in mind that this checklist is primarily aimed at what I do - run a back-end development team that specializes in agriculture modeling (using Python), with a web front end on it. So there are some pretty specific things in here, but it still might be helpful to others.

Joel's Checklist

Design

This section should be reviewed before you write a single line of code!

  • Do you actually understand the problem?
  • Have you talked to users who will be using the system? Do they understand your design? Can a user work through your theoretical design?
  • Do your mocked-up user interfaces allow a user to work through all use cases?
  • Will the application be used in multiple languages? If so, how are you handling that?
  • Are the proposed changes adding or removing features to an existing system? If features are being added, are they indeed what is wanted?
  • If features are being removed, how angry will users be? Are users currently using them? Do you have metrics to back that claim up? Are there alternate ways of performing the same action?
  • Who has final authority to say what features make the cut and which ones don't? Have they reviewed the design with you?

Backend:

  • Are things that are database models really needed? Are there things that should be database models but aren't?
  • Are database models properly normalized? If not, is there a valid reason for them not being normalized?
  • Should nullable fields actually be nullable? Is there a logical reason for them being nullable?
  • Do database field names match model field names and UI labels?
  • Do all columns in database tables accurately reflect the type of data that they will be storing? E.g.: Do decimal numbers have the correct number of decimal places?
  • What makes a given database row unique? Will this have implications in other places?
  • Does the database/table structure seem well designed? Are there any things that stand out as being odd?
  • Do all models have a way of being printed out to a string? E.g.: __unicode__(self) or .ToString()?
  • Are all API end points wrapped in try/except blocks? Will any API call ever display an internal server error or unhandled exception?
  • Are there any sections of nearly-identical code? Can they be removed?
  • Are the comments in the code actually reflecting what the code does?
  • Are all inputs to the system properly sanitized?
  • Are all results returned in a logical order (i.e.: sorted)?
  • Any time we are writing a file, do we strip invalid/bad characters out of the file path and name?
  • How do things behave when we have multiples of things (e.g.: multiple related foreign objects)?
  • Any time we are getting collections of objects from the database, do we handle the case where we have an empty collection?
  • Are all exceptions that return to a client presenting something that is human-readable?
  • Are you ever comparing floating point values? If so, are you taking into account floating point inaccuracies?

UI

  • Do all UI fields have an appropriate place to be stored in the database?
  • Does the UI work on low-resolution screens? (Or, do you have a minimum resolution, and does it work at that resolution?) Does it look okay on high resolution or high DPI displays?
  • Are required fields marked as required to the user?
  • Is the user forced to enter required fields before a server call is made?
  • Are all error messages displayed to the user clear as to what the problem actually is?
  • Are all labels for fields correct?
  • Are there appropriate tooltips or help icons, when necessary?
  • If using any sort of windowing system, are windows correctly titled? Are windows resize-able? Do all controls dock/resize properly? Do windows have a minimum size?
  • When possible are you re-using Add/Edit dialogs? (They are often the same, so why duplicate code?)
  • Is it possible for user A to edit data that user B currently has displayed? If so, how is it handled? Does user B see updated data when user A saves it?
  • Are all calls to the system wrapped in try/catch blocks? Will the client ever see an unhandled exception?
  • Are any message boxes that can pop up really needed? (Are there more elegant ways of handling pop-up message boxes)? (Same with modal dialogs)
  • Do all operations that may require a long time to run indicated so to the user? (Are there proper "Loading..." indicators, where needed?)
  • Do all validation messages appear in the same area as the data that caused them?
  • Are all inputs to the system trimmed for leading/trailing whitespace?
  • Are any integer inputs checked for being -1 where values < 0 are not allowed?
  • Are any string inputs checked for being null/empty/whitespace?
  • Are fields checked for maximum length? If there is a maximum length, what happens when it is exceeded? (This also applies to the back end!)
  • When displaying a UI, is it apparent if no results are displayed? E.g.: Showing a count of items currently displayed?
  • If something is disabled on the UI, there should be some sort of visual reason why (e.g.: tooltip that says "Disabled because of..."
  • Do all context menus have an equivalent button found elsewhere? (E.g.: is there functionality found only in context menus? If so, that's less than ideal).
  • Do UI elements which would be used successively (e.g.: clicked on repeatedly) move locations at all? (They should be in the same place so the user doesn't have to move to click to get to the next thing)

Testing and Performance

  • Do all unit tests pass?
  • Do all features still work when there's more than one instance of each database model?
  • Does the system run at a reasonable speed on target hardware?
  • Does the system run at a reasonable speed when dealing with a reasonable amount of data?
  • Do all features work when logged in as different users (if applicable)?
  • Is it all possible to create corrupt/bad data through the UI?

Deployment

  • Are all Debug settings properly set to false when deploying to production environments?
  • Are any non-minified files deployed? If so, is there a valid reason for doing so?
  • Do all tests still pass on a deployed version?

Discussion

pic
Editor guide