My Pen Is My Tongue

A few days back I sent out a series of tweets about "self-documenting code". Self-documenting code is an idea that's been around for many years, like stories about the wee folk...and like the wee folk, no one has seen self-documenting code.

The short version of the tweet series is that if you're writing code, you should be writing documentation as well - it's really too important to skip. This post, however, is not really about self-documenting code, but rather about how to write documentation, and more specifically a certain piece of documentation that you should never neglect.

---

I entered the whole techno-geek world at a time when computer labs were a real thing. Punchcards and shelves full of binders stuffed with documentation were commonplace. Documentation isn't like that anymore. When Java came along, I was almost enthused to use JavaDoc because of the level of clarity it added when writing the documentation. Now that nearly all code written by large, technologically advanced firms is either in Java or JavaScript (or ECMAScript), JavaDoc and JsDoc are - or should be - the de facto standard.

There is seldom serious argument against using one of these two tools anymore. There is disagreement about how the tools should be used, however. In the JsDoc community, one of the points of contention is the @author tag. To be clear, the JsDoc tool authors have stopped using the author tag and no 'contributor' tag has been added. It might seem, from their use (or non-use) that these tags are unimportant, and in fact, that is a common perception, especially in light of the advances in source code management, or what we used to call "version control".

However, not only should you use the authorship tag(s), you should be encouraging everyone else to use them as well.

It would come as a surprise to no one if I reminded you that we write code to solve problems. Not only are we writing code to solve problems, we're writing code to solve complex problems. For example, no one would write code to add two numbers...doing simple calculations on large data sets, perhaps, but there is a "complexity bar", below which we wouldn't dream of using code to address a problem. The first step of writing code is understanding the problem you're trying to solve.

As a hypothetical example, let's assume you've inherited a project. You've read the documentation that describes the solution to the problem the code offers, but after getting a small understanding of the problem combined with the solution being used, you have a list of questions. Why was this particular solution chosen over other solutions, for example. You can make some assumptions, but wouldn't it be nice to be able to contact the author to ask for their insight? Code, even well-documented code, is only a partial story. Just like every fan of a book turned into a motion picture knows, even faithful adaptations leave out bits that someone thought important. The first reason to include authorship information in your documentation, then, is the abundance of information it can point you to.

The common response to this concept is that the authorship information is not needed in the documentation because source control software, like git (my personal favorite), can track that information and expose it through tools like blame.

This response, however, misses the purpose of such tools. Version control is tied to a specific change...in git parlance, a commit. Yes, you can look at a particular line and see the last change of that line - the author of that change - but that is qualitatively different information than the author of a solution...and that information is generally only the last change. In order to get authorship information you must follow changes to a specific line back through history, and if at any point history was squashed or rewritten, that information is gone. Version control tools are excellent at solving the problem the author intended them to solve, as the author understood the problem; do not expect another author's code to solve a problem as you understand it.

Another reason authorship is important is we, as an industry...and really we as the human race...have difficult acknowledging the contributions of women and persons of color. The list of women who have significantly contributed in STEM fields without attribution is long...far too long. Not including attribution participates in that system of oppression by reinforcing the status quo. If we want to have any hope of disrupting patterns of discrimination, patterns that have existed for millennia, we must combat it at every turn.

A while ago I wrote a post called Visibility and Obscurity that described a situation in which attribution was changed on work I had done. In academia this is typically called plagiarism, and in most instances it's a punishable offense. Even outside academia, claiming to have done something you have not done can have serious consequences - Scott Thompson's resume scandal is evidence of that.

We should be writing code we can release with pride. Build things you're proud of and put your name on it...and give that same consideration to others. Amplify voices that are too often silenced or ignored - it does not diminish your contribution and it makes a difference. If it only makes a difference to the woman or person of color who finally has their contribution recognized - that's enough. If the only people who see an authorship reference are your employees, your colleagues, that's enough - they are important too.

Happy coding.

Visibility and Obscurity

Several years ago, when I first started at PayPal, the front-end development environment was still fairly young. As a result, tools that might have existed in other environments were missing.

As a veteran coder, I quickly grew tired of repetitive tasks - I wanted to be writing code - and set about writing scripts that developed into a significant tool suite. I shared that tool suite with both front-end and back-end developers (there were no full-stack developers in those days) and the use of those tools spread throughout the company, across the globe.

Out of that activity, there were two different experiences that bear examination. I'll address the later of the two experiences first.

In later years, as the development environment matured, another engineer - one responsible for establishing a standard development environment - took control of the tool suite (totally understandable) and put his name on my work (not understandable). The tools I had birthed and nurtured through numerous changes in the development environment, and continually promoted so they would be visible to all engineers - were adopted and their new foster father promoted himself as their creator when they became visible to upper management.

This is not an unusual situation. It happens all too often - much more frequently to women, of course - that someone other than the individual who has done the work takes credit, especially as the work becomes more visible.

That experience taught me two lessons. First, how you handle it says volumes to those who see the situation. Second, obscurity can be moments away, behind someone else's shadow, even when you think the visibility you've worked to cultivate over years is secure.

The second experience was much more pleasant. On a regular visit to a development office, I was introduced to an engineer who had recently joined the company. The engineer and I exchanged pleasantries - the normal "nice to meet you" bit - and then the engineer who introduced us told her my username (which was explicitly tied to the aforementioned tool suite)...and her expression and demeanor shifted dramatically. As someone who's never been in the "popular" club (yes, I've been a nerd and geek since before secondary school), that reception was quite an ego boost.

I had no real expectation of receiving such a reception - none of my long-time friends who'd seen me develop the tools reacted in the same manner - and it caught me by surprise. That reception also taught me a lesson - there will be some ways in which you're always more visible than you believe you are.

History is eager to write out of the picture those who have struggled to build great things - whether it's a woman who's made a significant contribution to our community (like Nicole Sullivan, the creator of OOCSS) or a man who is more interested in the work than the credit (like Nikola Tesla).

When you find yourself in these situations - situations of visibility and/or obscurity - how you navigate those shoals says volumes about your ambition, your drive, your values - such as integrity and trust, and what you know to be true about yourself. In those situations, may you have fair winds and running seas.

Happy coding.

What Isn't Said

If you're a follower of this blog, you'll notice that my posts tend to fall into three general categories. There are posts about how do something, like put PayPal on your Facebook page, build a slider toggle, or include reference notes, posts that show a different side to things in technology industry news that catch my eye, and posts that are general career advice from someone who has spent a few years in a very turbulent industry. I'm not sure if this post fits in any of those three categories, or if I'm starting a fourth after reading the blogs written by two men I consider to be, at the very least, something more than acquaintances (http://www.thejourneyismydestination.com/ and http://www.codercowboy.com/). I should point out, I suppose, that neither of these has the reputation in the industry of Eric Meyer (http://meyerweb.com/) or Nicholas Zakas (http://www.nczonline.net/), but I suppose that gives them a little more influence in my estimation because they are writing, not because they need to but because they need to, and I see something of myself in that, and besides, their year-end posts were good.

In addition to the inspiration from other bloggers, this time, as I looked back on the past year and looked forward to a new year (as many of us do at the start of a new year) I came across interviewing tips from recruiters and one in particular caught my eye as I read through the post, asking myself the interview questions as part of my year-end self-reflection. The question caught my eye, in part because as someone who has conducted several interviews and 'phone screens', I find it to be a question that I've been asked, but have never asked - it's simply what is your greatest weakness.

This time, perhaps I found insight that has eluded me in previous years or perhaps I have rediscovered a forgotten truth, but I recognize that there are those who see my greatest weakness only as a weakness, while I see my greatest weakness as a strength as well. This difference in perspective likely comes about because we all expect that other people to not only understand our actions - because they're based on beliefs that spring from rational thought - but to share those rationality-generated beliefs our actions are based upon. However, that universally-held, unspoken belief is false - there are those who do not understand our actions and do not share our beliefs, and likely never will - their perception is fixed and the die is cast.

Here's where I offer a bit of advice. When this happens to you, and it's extremely likely it will, at some point although you will not fully realize what is happening you will attempt to cast what others see as your greatest weakness as a strength. This is a Sisyphian task, and no matter how many times you roll that boulder up the hill, scrabbling for every inch of dirt, it will roll back down, and all the while, none of us acknowledge or challenge our perspective unless we trust each other - really trust each other - and remember that we're human, doing the best we can with any given situation.

As the past year closes and a new one is begun, I am also reminded that good leaders know the strengths of those on their team, and beyond that, great leaders see strength where sometimes even team members see only weakness. As we work together, maybe we should take Peter Drucker's words to heart and listen for what's not said - search for those points of weakness - and talk about why we see them as weakness but to then use our trust of each other to move beyond that to see them - really see them - not only as weakness but as a hidden strength, because whether we're the team captain or just one of the players, we can all benefit from the humanity that comes from trusting each other.

What kind of engineer, indeed.

Several of my friends and colleagues have tweeted and otherwise commented about a post on the extremely knowledgeable Nick Zakas' blog.

I have a lot of respect for Mr. Zakas, and often enjoy his blog posts, learning something each time I visit, and this post was no exception. Unfortunately, there is also a point with which I don't agree...but it's not really Mr. Zakas' point. He says,

If you stop and think about it, writing code is something that a lot of people do. You can hire someone cheaply out of college to write code and it may not be as good as an experienced software engineer, but if it’s close enough, that’s usually all you need. So if your programming acumen is the only thing that you focus on, you aren't improving your position in the company. What matters far more are the soft skills that you have along the way. Do people enjoy working with you? Do you add something over and above your coding skill?

First, to Mr. Zakas' point, there are a lot of people who can code...but there is a potentially significant difference between "close enough" and "correct". With "close enough" your revenue most likely will not be zero, but it will also likely not be as much as it would with "correct"...and in some situations, "close enough" may be nowhere near close enough. If we're talking about a web page that responds in 8 seconds instead of 4 or 6, that may be one thing (though you might want to see my earlier post about speed in websites, Faster, faster, faster) but if we're talking about real-time or life-critical software, is "good enough" really good enough.

Still, Mr. Zakas is correct in that our reputation is important...but therein lies my problem, and it's demonstrated to a degree by those Peter Hinssen refers to in Will the real CIO please stand up - individuals who associate responses to the phrase 'IT departments' which are "wonderfully colorful comments such as 'arrogant', 'out of touch with reality', 'language of their own' and - increasingly often - 'hopelessly out of date'."

Are there engineers who are reasonably considered "arrogant" or "out of touch"? Certainly, and, I suppose if Mr. Zakas' post were geared toward those engineers alone, we might not have anything to discuss. Note, however, that Mr. Hinssen's post discusses the prevailing attitude. If we see "arrogance" and "hopelessly out of date" as the status quo, then I would posit that Mr. Zakas' advice to adjust our attitude addresses a symptom of the underlying problem without addressing any of the underlying issues.

In part, the prevailing attitude - that we are arrogant and out of touch - is our fault as software engineers. Whether we write software for the World Wide Web, smartphones, or desktops - we have, to some degree, failed to convey our value to the organization. Often we do speak a language of our own, and life would be much easier (from the perspective of those who see us as arrogant and out of touch) if we would just communicate more/better/the right way - if we would stop being so out of touch - if we would stop seeing ourselves as so valuable to the organization - after all, the contribution of an engineer is not that significant because "writing code is something that a lot of people do" (emphasis mine).

As a User Interface Engineer (or web developer, if you'd like), I often hear comments similar to this - comments about how someone's teenage relative can build a good web page. While there are, of course, prodigies, the amount of engineering that is required to create the best web page is significantly greater than the skill level held by general practitioners, as is the amount of engineering required to create the best software for other media. I would posit, therefore, that our challenge is not as much improving our soft skills (though every engineer I've met would benefit from such development), but rather conveying our value to the organization in a meaningful way. To that end, as a counterpoint to Mr. Zakas, I would commend a quote that Baskin-Robbins used to hang in their stores: "there is hardly anything in the world that someone can't make a little worse and sell a little cheaper - and people who consider price alone are this man's lawful prey."¹ 

There are a number of issues that might be discussed when an organization perpetuates a culture similar to Mr. Zakas' comment above (that people who code are a commodity) or similar to those Mr. Hinssen references; however, one of the most significant is that organizations which learn to accept "close enough" when it's less expensive incur technical debt that becomes deadly. Further, the effect such an attitude has on morale within the IT department can be equally as deadly as mounting technical debt.

There is, in my estimation, another side to this story. In the face of significant potential issues, such as creating code that's "good enough" under one estimation and not another, mounting technical debt without having resources to address it, and demotivating personnel, there is also the thought that perhaps the perception of engineers as weak in soft skills, arrogant, and out of touch, is mistaken. Perhaps, just perhaps, those engineers are instead are significantly different than other employees.

Perhaps these engineers are not arrogant and out of touch. Perhaps there are weaknesses related to their soft skills, but if we, instead of operating from the assumption that what these engineers do is something that a lot of people can do, operate from the assumption that what these engineers do is something that few people can do, and that they are therefore in a different realm than others, might we see their "arrogance" as an indication they have a different understanding of their capabilities and the situation? Might the perception that they are "out of touch" be due to the manner in which they, in their different world, relate to those outside  of their area of expertise.

Let us consider then, the possibility that their "arrogance" and being "out of touch" are, at worst, simple weaknesses in their soft skills. What is the best advice? Certainly Mr. Zakas' advice is good, and traditional - work on your weaknesses. However, is that really the best way in which these engineers can contribute? In this consideration, I would offer the following advice that Dr. Donald Clifton gave his son: "your weaknesses will never develop while your strengths will develop infinitely."²

Let me be clear - the best advice the creator of the Clifton StrengthsFinder, Gallup's own online psychological assessment, could offer his son, was to build his life and work around his strengths rather than try to fix his weaknesses. For Dr. Clifton's son, and many engineers, Mr. Zakas' words, and in fact the words of those who brand us as "arrogant" and "out of touch" would have them "fix their weaknesses".

In this, I would posit that rather than engineers spending time fixing their weaknesses, that they spend time using and developing their strengths, and that management (at all levels) spend time seeing and celebrating diversity and the value it brings. I understand this is unconventional wisdom, but perhaps, just perhaps, this is a new age - an age in which each of us can contribute to our fullest.

What kind of engineer do I want to be? One that develops my strengths infinitely.

1. This quote is attributed to John Ruskin, though there is some debate about whether or not that attribution is valid.
2. Reported in a post by his son.

Rules are beneficial because they give constraint, but it is in stretching that we grow (Robert's Rule #21)

[Tweeted 2011-07-17]

As an engineer, you have to be familiar with rules – mathematical formulas, design rules, data normalization rules, language rules, et cetera, et cetera. We're so familiar with rules that we could not imagine living without them, and if someone breaks a rule, we have other engineers dedicated to quality to identify those instances so they can be remedied.

So, if we're always following rules, how can we innovate or invent new things? We do both by stretching. In infinite diversity in infinite combinations (IDIC) creativity gains its full strength. Creativity is the basis of both innovation and invention.

If we consider, then, that our creativity is a muscle, we can think of the rules governing our environment to be the resistance against which we exercise that muscle. Much like our physical muscle is toned and built in striving against gravity by climbing a mountain, our creative muscle is toned and increased in striving against the 'rules'. Of course this exercise requires that you be familiar with what rules you strive against as well as how those rules impact your environment, for instance, if we didn't understand how gravity worked, we would not be able to effectively exercise our physical muscles.

In this analogy, we see can that rules are beneficial because they give constraint, but it is in stretching that we grow (Robert's Rule #21). So, go and create.

You are not your job, you are a person (Robert's Rule #8)

[Tweeted 2011-05-04]

Like many people, I get asked "what do you do" quite often. At times it's been rather difficult to explain to people who "don't get" computers. In fact, one person went so far as to say I didn't really work because I didn't "make" anything. It took me a while to determine that, in his mind, unless you contribute to the production of a physical item in a meaningful way, you aren't really working and you shouldn't get paid. Thankfully, there have never been very many in my circles who have held the same belief.

Another problem I've had in responding to the question is until recently "what do you do" has been a little vague, or imprecise, rather because I've always done several things simultaneously. When I started out in the industry, I was an "Installer". As an Installer, I traveled a region and installed payment systems, trained the users, performed any troubleshooting required, made sure the customers had the supplies they needed, wrote customer service utility software, et cetera, et cetera. After I moved on from that job to client/server development and became a "Systems Programmer". However, 'programmer' jobs were usually more analysis and design than actual development, and then added to that were DBA duties, managerial duties, et cetera, et cetera. When I moved from the client/server environment to the web and became a "ColdFusion Developer" or a "Web Developer", it generally didn't reduce the scope of work much as there were design duties, development duties, network/server administration duties, DBA duties, et cetera, et cetera. Basically, there generally has been more 'et cetera' than distinct role duties.

All of this poses a problem more for existentialists than essentialists, I suppose, so perhaps it's only a problem because of my perspective, but perhaps not

I guess you might say at certain points in my past I've been an Installer-Trainer-CS Representative-Field Engineer-Programmer or Systems Programmer-Data Analyst-DBA-User Interface Designer-Technical Writer-Manager or System Administrator-Web Server Administrator-Programmer-DBA-Web Developer-Web Designer. All of that sounds really complicated and imprecise simultaneously. Besides, I noticed that any time I've been 'between jobs' I've never stopped 'being', so a change in perspective was required and I came to the startling revelation that you are not your job, you are a person (Robert's Rule #8).

As a result, when people ask "what do you do" I no longer respond "I'm a [insert title here]", I generally clarify whether they inquiring in what capacity I'm employed or if they mean something else. If they're inquiring about my work, I say "the majority of my work is as a [insert title here]"; if they mean something else, then I answer their real question to the best of my ability.

There are a few side-effects that I've noticed when verbally recognizing this small truth. First, people generally take a moment to consider what they're asking, which tends to move the conversation quickly out of the in-one-ear-out-the-other chat (that drives me mad) into a realm of real conversation. The second side-effect that I've noticed is that I feel more free to balance work and non-work life. For example, the majority of my "outside-the-home work" may be as a system administrator and that may entail thwarting network attacks, but the majority of my "inside-the-home work" is as a husband and father and in both inside and outside the home I am a person. That means, for example, that there are some meetings I don't take (such as those scheduled during my daughter's bedtime when I'm supposed to be reading her a story or singing a lullaby) and some job opportunities I will never pursue (because they would require me to sacrifice some portion of my humanity).

As far as I can tell, we all have only one life to live. At the end of mine I hope that my wife and daughter say "he was a good man"...anything else just won't do.

Ethical conflicts are like the TARDIS (Robert's Rule #7)

[Tweeted 2011-05-03]

One of the things that system theory gives us is a self-reinforcing loop. Granted, systems theory isn't the only thing that contains this concept; however, its centrality to systems theory is significant.


One of the fables that I have enjoyed over the years goes a little something like this.... Once upon a time a thief was being pursued by the authorities. In his haste to evade capture, he dashed into a temple and donned the robes of a holy man. The authorities entered the temple to find a man in the robes of a holy man and asked if he had seen the thief they were pursuing. He assured them he had not. However, in order to continue to evade capture he had to continue to play the role of the holy man. After many years, a severe drought fell upon the land and the ancient scriptures said only the sacrifice of a holy man could end the drought. In his final act in the role of the holy man, the thief sacrificed himself. As he lay dying, rain began to fall.


We all know examples of little actions that grow into larger, more important actions. The most common example of this is deception. To maintain deception ever larger deceptions are required; they are the ultimate pyramid scheme. This is why most advisers caution against something even as small as padding your resume.


Once, while interviewing candidates for my employer, I was given the task of assessing technical abilities in web languages. All candidates had been pre-screened by telephone and resumes had been reviewed, so by the time the candidates arrived, we were confident in presenting several problems so that we could observe and assess their abilities. I should say that I find this task pretty meaningless in many cases. With the advent of online resources and the tendency of the development community to share resources and experiences, a few minutes of searching can answer most questions. Because of this, I also tend to be very lenient in my assessments and somewhat laid-back in approach.


However, in one instance, I presented the problem (in written form) and the candidate immediately handed the problem back to me saying "I can't do this". After 10 minutes of me encouraging him to attempt an answer, even if he was not confident of the result, he continued to refuse.


I have to add here that one thing we don't tell candidates is that if we believe that they are not qualified for the position they are seeking they may still be qualified for other positions in the company, and we may adjust the interview to determine if they are a fit for a different position.


The candidate I was interviewing was likely qualified for a different position; however, it was plain to see that he had been deceptive with his resume and during the pre-screen. It was a small thing, really, to say "yes, I can do that" when really he couldn't. The problem was that saying "yes, I can do that" when he clearly knew that he couldn't, blocked him from progressing further with that employer. Completely.


Simple, but difficult, especially when there's so much on the line. Now he's just one more example that helps me keep in mind Robert's Rule #7 -- the first ethical conflict is usually so small it appears minor and so large it becomes a major career factor, and the candidate will continue to work for small start-ups, never really progressing to the next level.