Software Development versus Software Engineering

One of the most useful things that I have gotten from studying things that I call "Demingesque " is the idea of Kanban. Kanban means "sign board" and is a way for projects to display information about themselves.

In its simplest form the Kanban idea is simply to keep track of things I need to do, things that I am doing, and things that I have done. In addition, because the board is placed in a location that is easy for management to see it can't help but communicate the status of the project or work area associated with the Kanban.

This idea is so simple it hardly seems like it is worth the effort of naming it. It is so engrained in the idea of a productive work team that I can't fathom needing to have a "methodology" associated with it. Yet I see amazingly complex ideas built up around this very simple tool.

Ironically, developers tend to like over complicated things in place of simple things. I suspect that it is because we are smart people and we don't like things that are too "simple" challenge us. Instead we want something hard that forces us to really stretch. So, I'd like to challenge people who think like that: don't think like that.

Instead, we should relish the idea of doing amazingly complex things with the simplest tools possible. In the places I've worked, the Kanban is most frequently implemented using a simple white sheet and a simple "sticky note" approach. I've seen many variations but ultimately you are just capturing the following information:

1. What do you need to do?
2. What are you doing?
3. What have you done?

Anything beyond this is probably a waste of time. This information recorded regularly can give you an idea of how long a project will take (based on the velocity of movement of items from "need to do" over to "have done") and how many "are doing" things are happening at the same time. The manager's job now becomes tracking this information and predicting that if fewer "are doing" things are happening then the "have done" pile grows more slowly.

You can formalize this as much as you feel like, put pretty math on it, or give it buzzword names, but really this is the basis for all software development project management... also sometimes known as "software engineering."


Washington DC Area Groovy User Group

I'm honored to be presenting at the Washington DC Area Groovy User Group this Wednesday. If you are going to be in DC I would encourage you to come out.


good code, great code, and really great code

There's great software, and there's really great software. The stuff that's great is the stuff that works well and is well documented. Ever need to figure out something? Go read the docs, if you screw up then the software tells you exactly how you messed up and didn't follow the documentation. That's great software.

The best software (the really great stuff) doesn't require documentation. You can play with it and discover how to make it do what you want. You just have to poke about with it a little bit and it will guide you to a working use case. You don't have to read a book, understand a theory (beyond basic computer sciencey things) and you can get to work almost immediately.

This is accomplished through really good failure modes and support tools that help you figure out how to use the system. It's 100 time the work of documentation but it is 100 times better. The best form of this is really great test coverage. You need to have really great test coverage to show you the use cases the system designers were thinking of. That is the best documentation because if a developer changes their minds the tests must reflect the change in paradigm.

Then there's stuff like this:

This is from the Sonatype Blog. On its own this is a tiny mistake. A blog has had the POM XML fragment stripped out of it. A bit of spelunking on the web produces this link as the definitive documentation for the plugin. Let's go and read the code for the plugin and see if we can't figure out what the missing tags are.

Over on github we find the emma4it plugin's source code. Diving this code we find that the project is actually pretty darn thin... and that's good because it is easy to understand. What does the JavaDoc say about how to configure this plugin? Thankfully there is at least documentation telling us what each of the Java files are for in the Maven lifecycle.

Does any of this include an example like the one Sonatype accidentally destroyed the only canonical example of in their blog? Sadly, no.

So my best guess is the first "report" word shown is a "report" id for the execution since we have more than one execution. My next guess is the phase we use in the documentation from the blog is different from the phase shown in the JavaDoc. The phase here is the "post-integration-test" phase by my guess. Next I have to take a wild leap. My guess is "project.build.sourcesDirectory" is the value set in the sourcesDirectory tag.

This is my best guess at the missing POM fragment:


So by my estimation this is good code, that is on the cusp of being great code. That is still a ways from being really great code which wouldn't require you to dig around for documentation to begin with.


The seven stages of dealing with PMD rule violation

Is your build broken from a PMD rule violation? Has your project has been set up so that a PMD rule violation breaks the build? On occasion even the best developers slip and push code that is in violation of the PMD rules they themselves agreed to.

I have been observing developers under these severe conditions for some time now and I've identified seven emotional stages that every developer who breaks the build due to PMD rule violations goes through. I am cataloging these here in the hope that it helps some developer cope with their broken build and move on in their project.
  1. Shock and denial

    You will probably react to learning that your code does not conform to your project's PMD rules with numbed disbelief. You may deny the reality of this PMD rule violation at some level in order to avoid the pain. Shock provides an emotional protection from being overwhelmed all at once.

  2. Pain and Guilt

    As the shock wears off it is replaced with suffering. Although it is excruciating, it is important that you experience this pain fully and not avoid it or escape it with //NOPMD comments or by the use of alcohol or drugs.

    You may have guilty feelings or remorse for the things you did or didn't do with your code. Life feels scary and chaotic during this phase.

  3. Anger and Bargaining

    Frustration gives way to anger. You lash out and lay unwarranted blame for the rule violation on someone else. You may blame PMD itself. You may blame the authors of the rules. You may rail against fate questioning "Why me?" and you may also try to bargain in vain with PMD saying things like: "I will never drink while coding again if you will just accept my patch"

  4. Depression, reflection, loneliness

    Just when other developers think you should be getting on with your project, a long period of sad reflection will likely overtake you. This is a normal stage of resolving breaking a build due to a PMD rules violation.

    During this time you will finally realize the full magnitude of your rule violation. You may isolate yourself from other developers on purpose to reflect on things you did in the code-base and focus on your memories of past times before you violated the PMD rule.

  5. The upward turn

    As you start to adjust to life after a PMD rule violation has occurred, you become calmer, your thoughts organize. Your physical symptoms (these range from mild stomach cramps and headaches to full blown cold-sweats and involuntary spasms) lessen your depression lifts and you begin to formulate a plan.

  6. Reconstruction and working through.

    As your mind becomes more functional, you find yourself seeking realistic code changes to be made to resolve the PMD rule violation. You start to work on restructuring your code around the PMD rule violation.

  7. Acceptance and hope

    During this last stage you learn to accept and deal with the reality of using PMD on your project. Acceptance of PMD does not necessarily mean happiness. Given the pain and turmoil you have experienced you may never return to a care-free and untroubled code base that existed before you broke the build. But, you will find a way forward in your project.

    You will start to look positively on your project again as a whole and actually plan things for future releases. You will once again anticipate writing good code and may even find joy in writing software again.

Rest assured, you can recover from a PMD rule violation. You can put your project back on track. There will be joy in coding again someday.