10 Aug 2016
Ever heard of a mog? I’m talking about John Candy playing Barf, the half-man, half-dog. He had an effective approach towards laser-slinging bad guys. To wit, this pic :
Notice how all the shots smartly get routed right back to the bad guys. They get shot with their own lasers! Genius!
I’ve had managers that use this technique, and I think it is an anti-pattern.
Let’s take a hypothetical case and walk it through. Here is how it works for “Phil”, week 1:
- Phil has a problem he can’t easily solve.
- Phil approaches his manager because he needs help.
- His manager responds with, “What do you think you should do?”
- Phil answers with some ideas, which then turn into a list of things to do to solve the problem.
On face, this is a great approach, because it forces Phil to think through the problem he needs to solve, and the options he has available. The manager, likewise, can feel good about herself because she’s encouraging critical thinking.
Let’s remain optimistic. Let’s say the problem was solved. Yay! Maybe Phil really did need to think through things and come up with solutions. Ok, now onto the next problem. Let’s say it’s week 3:
- Phil has a problem he can’t easily solve.
- Because he’s learning, he thinks through all the options and even tries different solutions before speaking with his manager.
- Phil approaches his manager because he needs help. He explains all the things he’s done to solve the problem, including the failures, the ideas and so on. He’s really thought this one through!
- Manager responds with, “Hmm. Well, what do you think you should do?”
- He gives more answers and he leaves with a list of tasks.
So, the Mog Defense continues. Phil has grown, but the manager is using the same approach. At this point, Phil really has done everything. Maybe some new ideas came up in the conversation, but I’m betting they were assigned to Phil.
It’s not so much that the manager is doing a bad job guiding the employee (although in my opinion that’s true, too). The problem is that the manager is not engaged and is barely supporting the employee. Perhaps this tactic can work if the manager follows up and ends up giving advice later, or helps the employee process it afterwards. However, someone that persistently uses the Mog Defense is probably not this kind of manager and is just trying to avoid getting lasers in the gut.
Eventually, Phil will learn how to handle this relationship. Here is how it works, week 7 and onward:
- Phil has a problem he can’t easily solve, even after thinking through all the options.
- Phil approaches his manager and says everything’s going well because he’s a great employee that can solve his own problems.
- Either Phil finds someone else to give advice, or the problem goes unsolved, and is swept under the rug.
Now, you’ve got a broken system.
28 Mar 2016
Please don’t say this.
Really the problem I have with this phrase is the “complete” part. Whenever I’ve heard it, my uncensored reaction is, “gee, we’ll be done by the end of the day!” And, to speak bluntly, that gut reaction is the only reaction some folks will have if they don’t fully understand software development.
Code Complete is far from done; it’s totally untested. Even the most basic cases have not been evaluated, and as far as I know, no one has given you a code review, either. But it sends a message, whether intentional or not, that the amount of work left is trivial.
Perhaps I’m splitting hairs, but saying “code complete” and saying “I just need to write tests” are two different phrases to me.
Code Complete says:
- “I coded for the happy path. We can put it in production now if you want it sooner?”
- “Testing is not part of development. Development is done.”
- “Hi. I like to build card houses. Man I’m going to be frustrated when this falls over in a few minutes.”
Still need to write tests says:
- “I’m not into TDD, and I’m not done with the work.” <– honestly I am personally ok with this. Everyone codes differently.
- “I have initial structure in place. It’s going to change from here.”
- “I am now going to question what I’ve written, and respond to those questions.”
It’s basic, really. “Code complete” says that you think you’re done when you’re really not, regardless of who is in charge of testing it. (Though I admit, I hope you do a lot of it yourself.) But, perhaps the worst offense of all, using the word “complete” makes it sound to a product owner that you are mere minutes away from being done. Constantly hearing this phrase will devalue the importance of testing, and, to me, you can’t call it “complete” until it’s been tested and reviewed.
16 Feb 2016
There are plenty of things that you need to do right in order to properly maintain, publicize, and grow an open-source project. This is not that kind of post.
I’m writing about what you want to avoid at all costs. I don’t mean mistakes, things that you might innocently wander into doing. Instead I’m talking about things you might do that feel wrong. It’s because they are. And the knot you feel in your stomach when you look the other way? It feels worse on the receiving end.
Here are the 7 deadly sins:
Sloth
The first and perhaps most obvious is Sloth. You probably already know what I mean. A lazy repo-maintainer is an alienator, a frustration.
Sloth is bad because it turns away people who are ready and willing to help you out. It also turns away people who haven’t decided if your library or tool is useful. If it already doesn’t work with modern technology, they will slink away and search up another solution, or even roll their own.
When you are too lax in your basic duties, all you are doing is giving them plenty of time to think about how frustrating you are, about all the time they spent on their solution, and how it wasn’t given an iota of your time.
Virtuous patterns:
- Answer that issue as soon as possible
- Give feedback on that pull request as soon as you can, even if it is to say “I see this; I can’t get to it until time x.”
- Release your changes frequently
- Put in the effort for a good CHANGELOG. It’s going to take you about 2 minutes when you do a release for the lovagod.
- Upgrade your dependencies so your library works with the latest.
You can tell yourself, “I’m just lazy. I’ll get to it.” But to me? You are flat-out ignoring people, ideas, the software continuum. Log on, answer questions, fix up your code.
Gluttony
The opposite of ignoring pull requests is to accept absolutely all pull requests. We could live in a fantasy-land that every pull request has merit (especially when you are seeing pretty green checkmarks for that pull request). But the underbelly of a liberal acceptance policy is a repo that has lost its way. It then becomes a complicated, pointless mess.
Virtuous pattern: It’s ok to say no to pull requests that are counter to your vision for the project. Just explain why you’re saying “no” and, if possible, suggest an alternative project or solution. Saying no does not make you a Bad Person. But saying yes all the time? That does.
Pride
Being a sinfully proud repo owner means you think your repo is too perfect to touch. C’mon, man.
Committing this sin means several things:
- Something about your project is so special (“easy,” “powerful,” “useful,” … ), that you think it doesn’t need to obey conventions, like having a README, styling, tests, or an issue log.
- Lots of compatibility breakages.
- Poor documentation. Here’s a hint: saying “the documentation is in the code” doesn’t help everyone. Maybe you have good docstrings. Hooray for you. You need to publish them.
Virtuous pattern: Be unafraid to question the choices you’ve made. Engage others when they have questions, because you’re going to get some good ones. (And if you get the same question over and over, you need to figure out how to address that question before it comes to the repo.)
Always seek improvement with an open mind.
Wrath
Look, no matter how ugly that code is for the pull request, no matter if the person flatly ignored some of the rules you set out in your CONTRIBUTING file (because you have one of those!) or has wasted precious moments of your life with their dumb code and dumb questions…don’t be a jerk about it.
Virtuous pattern: Constructive feedback.
Greed
- Stealing someone’s commit or idea. Maybe that sounds awful to you, but trust me, I’ve seen it. If someone puts up code you need to completely refactor, you should do what you can to keep that person’s commit in the logs.
- Worse: Stealing someone’s commit or idea and putting it behind a paywall. I’ve seen this happen, too. Isn’t that awful? Look, I know your project needs to make money at some point. But, a business plan that includes taking others’ contributions and making customers pay for them has got to be the worst form of freeloading. It’s like your buddy brings the chips to the party, then you charge everyone (including him!) for those chips, and keep the profits for yourself. Listen to what you’re doing, man!
Lust
A.k.a. “this pull request looks great! Your code is great and your idea: great. I can tell you know what you’re doing. Actually, could you also completely refactor an entirely different set of code that needs help? I’ll merge it after you do that.”
(My interpretation here, is that you are lusting after contributors and their skills.)
When a person is submitting a pull request, s/he wants to use the repo. In fact, they are probably dutifully getting it merged upstream, then they can pull the published library instead of dealing with a fork. That is awesome! Don’t abuse your power by making them jump through hoops that are irrelevant to what they are trying to accomplish. If they are touching code you want refactored, then yes you can use this person’s help. But be reasonable about it. If you want them to help you do a deeper refactor? Just ask him or her. But keep it out of this particular pull request. Otherwise you’re begging this person to create a fork and avoid future upstream improvements. (Which the person probably has more of.)
Virtuous pattern: Understand the problem the person is trying to solve and help him/her get there. Don’t stretch the scope of this person’s work beyond accomplishing the original intent. If you need some help and this person is willing to do it, don’t hold a PR hostage.
Envy
Envy in this context can mean a few different things.
- Deliberately making it difficult for adopters to monetize your code
- A ridiculous license agreement
- No collaborators, just you
- Shamelessly copy/pasting code or features from other projects (perhaps that’s lust?)
Look, if your project is open source simply because you want that free Github repo, I’m not going to hold it against you. Just make that clear in your README. You’re retaining some rights to this software. You can do that with a license, so pick the right one. (I’m just guessing, but if you’re really that caught up about it, you probably are not posting it on the Internet, though.)
If you have a generous license and you’re falling into some of the above bullet points? Then I call you out and say you really don’t want your repo to be open source because you can’t stand the thought of someone else ‘owning’ it.
- Virtuous pattern 1: Add collaborators you trust, and cheer on other projects trying to accomplish a similar set of goals
- Virtuous pattern 2: Have a fair license agreement
8th Deadly Sin
This is mine: my blog doesn’t have any discussion component, and therefore is lacking in transparency and a proper feedback loop. If you’ll forgive me that, I’d love to hear what you think. Check the about page and drop me a line if there are other things that drive you away from adopting or contributing to an open source project. I’d love to hear it.
20 Jan 2016
Would you board a plane in order to travel 10 miles?
What if traveling those ten miles looked like this?
Sometimes it takes a magnitude more energy to cross what is otherwise an easy stretch. This could be finding out why the engine light is on; it could be mopping the floor; it could be running tests.
To a certain extent, I’m talking about cost that’s difficult to quantify. You are a smart person, you should trust your gut. If you’re doing x over and over again, you don’t like it, and find you’re compromising for otherwise-unhealthy behavior, then something’s wrong. Not with you: with x.
I once worked for a company that had better coverage numbers for the acceptance tests than it did for the unit tests. Arguably, that’s fine. Your code is covered. Maybe even with acceptance tests, it’s covered “better”. However, it is costly and time-consuming. Running 10 acceptance tests might take a couple of minutes; whereas running 10 unit tests could be done in under 1 second. Now blow that out to 800 tests and you are wasting precious time.
But why was coverage so much better? I could blame, in part, poor choices, poor culture, etc. However, one reason is that they were simply easier to write than unit tests. Useful unit test base classes were non-existent. Repeatable patterns were not around, either. Crucial setup steps for things the application did, even having an available mocking library—all missing. (Whereas, these kinds of things existed in the acceptance test framework).
The only thing that these gaps did was promote bad behavior, and that behavior went unchecked. Not because the department was flooded with bad people, but because we were not concentrating on the behavior itself.
Given
- I am a conscientious developer. I want to test my code.
- I have a deadline I’m contending with.
It’s a simple, common scenario. The question is, what’s the best pathway to answering those two things? Automated tests! Hurray. But which automated tests will be used?
Answer:
- Sometimes, it’s the one that’s the fastest to write, even if it’s the slowest to run.
Once we observe the counter-intuitive decisions we commonly make, and step back to look at the overall landscape, we can understand that the landscape itself needs to change.