-
Inline documentation
Inline documentation is a sore subject for a lot of developers. Many see it as wasteful; it easily becomes stale, it’s yet-another-thing to maintain, and if you can already read your language of choice, it doesn’t provide any real value.
Documentation is not for you; it’s for everyone else. (Well, it’s for you too, but the future you.)
Avoiding comments because your code is “readable and understandable” makes several assumptions about your audience, such as them having any working knowledge of the language you’re programming in.
Our jobs (specifically as leaders in open-source communities) are to grow the platforms we’re responsible for. By catering to only developers, we end up ruling out contributions from everyone that isn’t currently a developer at our levels. That’s sad for everyone.
The natural response is: if you need to add a comment to your code, you’re being too clever. This, again, makes assumptions about your contributing audience. Thing is, it’s not about adding comments to difficult-to-understand or poorly-written code, it’s about translating gibberish into plain English so a bigger audience can contribute.
Inline documentation is the nonce-check of the open-source universe; it promises what’s actually happening in gibberish-land matches the intention of that section of code. There are a million excuses not to document your code, but it all boils down to either:
- Being selfish.
- Being lazy.
- Being in a hurry.
- Not knowing any better.
- Being so insanely good at reading everyone else’s code that documentation has never in any way helped you.
Rarely is #5 the case; that only leaves ignorance and carelessness, which are unacceptable if you respect and admire your colleagues, users, and the efforts of your communities and teams of developers.
So, please… document what the heck you’re trying to do.
-
WordCamp NYC 2012 Session Description
bbPress – Simply Advancing Everything
bbPress is forum software (with a twist) from the creators of WordPress. It’s been rewritten from the ground up to integrate seamlessly with any existing WordPress.org powered site. In this session, I’ll unveil bbPress 2.1, and talk about advanced developer topics such as: sub-hooks, theme-compatibility, BuddyPress and Akismet integration, data migration, plugins-for-plugins, wp_rewrite, wp_query, and stacking post-types.
Hope to see you there!
-
World Wide WordPress 5k – #wwwp5k
This past Sunday, Paul and I took part in Automattic’s second annual wwwp5k. We walked all around the east side of Providence for a total of 4.7 miles. Paul met a bunch of new puppy friends, the weather cooperated, and we had a lot of fun!
-
Reviewing > Testing > Copying > Writing
Rarely anymore do I sit down and type code out at a keyboard. Most of the typing I do happens on my iPhone or iPad via SMS or email. Typing new things at a computer is not particularly effective for me, and it’s generally not directly related to whatever task is currently at hand.
When I do need to type, it’s usually code of the PHP, JS, or CSS varieties, which means more reviewing and testing than it does actually typing things out. Lots of thought, then copying code I know does something similar, iterating on it, testing it, reviewing it, and committing to the result.
More often than not (let’s say 80% of the time) I copy and paste most of the code that I write. The original code comes from some other functionally proven, correctly working method that I either wrote myself or I’m already familiar with from some another project I’m involved in, and it gets iterated on over time to become something else.
The argument for this, is we avoid human typing mistakes and reinventing proverbial wheels.
The argument against this, is we run the risk of copying an existing, potentially hidden bug.
It’s more important to review and test existing code, than it is to write new code. Before writing something from scratch, be sure to budget time according to a ratio of: reviewing, to testing, to time spent actually coding. My rough guess is that the code review and application hardening processes should take at least 10 times longer than the time it took to write new code, and about half that for code that’s been copied from existing trusted and known-working sources. Maybe longer, exponentially so if this new masterpiece is a large addition to an existing project.
By copying existing code, you automatically inherit the labor that went into forging it to begin with. Each time a new file is created and code is written from scratch, potentially thousands of costly man hours are being completely disregarded. It’s an arrogant way to get things done, and a method/mindset usually better avoided in most circumstances.
There will be times where it’s nose down, neck deep, headphones in, write-new-code-mode. When that rare opportunity arises, be sure to budget the appropriate time to reviewing and testing it.
-
Confessions of an Open Source Workaholic
Hi, my name is John, and I’m an Open Source Software workaholic. I touched on it a bit in my WPCandy interview, and I thought I’d finish the story here with a few added thoughts.
I live in a great neighborhood on the east side of Providence, RI. I work from home, rarely drive my car (ignore the frequent road trips), and enjoy the luxury of being walking distance from food, laundry, spirits, and anything else I might need to live a happy and comfortable life.
By day, I work for Automattic. I love my job. I love my colleagues. I love everything about what I do. To say it’s a dream job is an understatement. I work on some really awesome stuff going on around WordPress.com, Jetpack, Gravatar, and try to poke my head into other interesting social bits as much as possible.
By night, I’m the lead developer of bbPress, BuddyPress, and maintain both of the bbPress.org and BuddyPress.org sites. I believe both projects are two of the strongest spokes attached to the WordPress hub, and it’s my pleasure and privilege to be so closely involved with them. I am passionate about their success and enjoy iterating and improving them both equally, and love to help their users whenever I can.
That said, I’m in a unique and misunderstood position.
I work 40+ hours at a job that I love. Most days when I’m done with work I switch gears to my hobbies; usually that’s bbPress and BuddyPress. Other days, I enjoy going to the park with my dog Paul, watching Netflix, or enjoying a nice meal with friends.
In 2010 and 2011, I had the pleasure of mentoring some really bright individuals as part of the Google Summer of Code and the Google Code In projects. Gautam Gupta, a 15 year-old student from India, placed 6th by working closely with me contributing to the first major release of bbPress in two years; helping to totally refactor bbPress into a plugin for WordPress, skyrocket its popularity, and reinvigorate something great that hadn’t had much attention in a while.
My point, is that working on the bb’s is not something I am directly paid by Automattic to do. Instead, my job at Automattic enables me the means to keep my skills sharp *and* work on the software that I love, at the same time; it allows me to spend my free time giving as much back to the community as I am willing and able to. I choose to concentrate on bbPress and BuddyPress.
While Automattic does donate the time of several full-time people directly back into WordPress, and while it benefits Automattic as a business to be coupled so closely to its active development, it is not Automattic’s responsibility to staff anyone to contribute back to any open source project anymore than it is your own to do the same.
WordPress is free and open for anyone to build off of and dedicate resources towards. The bb’s are both free and open like WordPress is, with a lower barrier of entry to make a a much larger impact. If you’ve ever been intimidated by the amount of activity happening around the development of WordPress, or have been afraid your contributions aren’t good enough: 1. you’re wrong; 2. use the bb’s as your training ground.
If you choose to stick around and help work on the bb’s, your influence carries more weight because there are fewer people contributing. Dedicated contributors walk up the ranks quickly, earning core commit access like Boone Gorges, Paul Gibbs, and I with both BuddyPress and bbPress. We’re not the founding developers, we’re the currently active ones, and we would love to have your help. From code to codex, everything is an iterative work-in-progress.
Who knows, maybe eventually you’ll be an open source workaholic, too.
-
I miss Pier 38
Watching this video about Automattic from 2010 reminded me how much I miss our old office at Pier 38.
