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.

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.

Fear is the birth of cruelty and the death of reason, wisdom, and finally, action. (Robert's Rule #26)

Fear, as our 'leaders' have discovered, is a powerful motivator. For most people, one of the most powerful fears is of losing their job, in fact, for some people, the fear of the loss of their livelihood is even stronger than their fear of death, because it means something very significant to those who depend on them. Because of the power of this fear, employers the world over become some of the most powerful entities known. However, this fear comes at a price, for fear is the birth of cruelty.

When you, as a manager, threaten someone's job and engage this powerful motivator, your 'direct report' will likely tow-the-line. They will likely become quite complacent. They will also likely quit innovating, start protecting their assets to the detriment of the team, and start looking for a place of employment where they believe they will be respected, which means their productivity will generally plummet and they will become a drain on morale. In short, what you will have created is a negative reinforcement cycle that will likely spiral out of control.

On the other side of fear, however, the lack of fear is an equally strong motivator. The lack of fear can be the result of either having nothing more to lose or a true feeling of safety.

The lack of fear that is the result of having nothing to lose - that finds its origination in desperation - is dangerous in the extreme, as The Art of War notes. It is the recognition of this fact that has led companies to treat terminated employees as criminals as they are escorted from the building, often without even being given access to their personal effects. The creation of this type of 'enemy' is a mistake of the highest order and you should always try to maintain the appearance that even those discharged have something more to lose. Helping them move on to another position (if that is at all possible) is a good start. After all, just because they don't fit in with your organization that does not mean they would not fit in quite well somewhere else. If you can honestly, objectively review their contribution you will (nearly always) find some benefit they provided to the organization that you can leverage as they look for another position.

On the other end of the lack of fear spectrum - when a person feels safe in their job - people are more likely to take risks, stretching and growing. They are also likely to innovate, be more relaxed and positively affect team morale, in essence become a powerfully positive asset. It is the creation of these positive reinforcement cycles that we need to create. One of the most powerful effects of these positive reinforcement cycles is the energy they contribute to the team, as study after study has shown that 'winning' begets 'winning' and nothing so strongly counters winning than fear and trembling, because fear is also the death of reason, wisdom, and eventually, action.

Trust everyone at the table, but cut the cards anyway (Robert's Rule #18)

[Tweeted 2011-06-06]

Living in an area where there are multiple casinos within a short drive or a long walk, I've learned to see some things using gaming metaphors. One of these metaphors is trust everyone at the table, but cut the cards anyway (Robert's Rule #18), and if you are an empiricist like Hume, then this rule will automatically make sense.

How does it apply to work? First, if you are not able to trust your colleagues, work (and probably life) will be miserable. Of course the reverse is also true; trusting your colleagues will go a long way in making work not be the worst part of your life. In fact, I've had some jobs I should have hated because they were such a poor fit and yet I didn't because of my colleagues.

Second, not only will the inability to trust your colleagues make life miserable, it will be very difficult to accomplish what you need to accomplish as well. The amount of time you spend countering the machinations of office politics in a hostile environment will outweigh whatever other successes you have. In addition, those times in which you don't succeed your discomfort will be worse because of the negative self-talk that comes out of the lack of trust and your assumptions about yourself.

Of course, this doesn't mean that you should just blindly trust. After all, your trust can be pretty easily misplaced, and this is your livelihood we're talking about here. You can't just go about willy-nilly assuming that everything your colleagues do and say is true, and even a series of lucky guesses ends sometime, which is a very good reason to confirm what you believe to be true.

Of course all of this is to say trust everyone at the table, but cut the cards anyway.

Silence and neutrality enable oppression (Robert's Rule #11)

[Tweeted 2011-05-09]

Today's post isn't directly related to work experience...at least not for most people.

I grew up in the middle of blue-collar union country at a time when unions were strong. Members of my family would have never considered crossing a picket line. Why? In part because it feels good to know that someone has your back. Of course there's always the collective bargaining thing too...after all, it's usually difficult, not impossible but difficult, to oppress a large group of committed, active people.

History is full of examples of people who have stood up to those who oppress them. One of the most famous in American popular culture is the Molly Maguires (if you haven't watched the Sean Connery/Richard Harris movie you really should). I understand that the real history of the Mollies is a bit clouded, and also that history is written by those who win. However, instances of the oppressed standing against those who oppress them provides a valuable lesson that applies to all of life, both working and non-working life.

Because this lesson applies to both work life and non-work life, it's become one of the rules I strive to remember every day. Every day, silence and neutrality enable oppression (Robert's Rule #11), and every day we must combat it, because oppression brings everyone down to the lowest common denominator.