Comment your damn code!!!

“Any fool can write code that a computer can understand. Good programmers write code that humans can understand.”
— Martin Fowler

When I was a computer science major in college, I had professors who used to dock points if my code wasn’t documented.  It didn’t matter how well-written my code was, and it didn’t matter how well my code worked.  If I didn’t include comments to describe my code, what my variables were, why I used certain functions and coding techniques, a project that could’ve gotten an A grade instead got a B.

That memory came back to me this evening at our SQL user group meeting this evening.  Our guest speaker was Jen McCown, who gave a presentation called “T-SQL’s Hidden Support Feature.”  (A description of her sessions can be found here, and I found a SQL Saturday link to it here.)  Her presentation talked about a feature included with T-SQL (and just about every language imaginable).  It is guaranteed to improve how people handle, develop, and maintain code, and it costs nearly nothing to implement.

What is this miracle feature, you ask?

Code comments.

Simply commenting code can save developers lots of headaches and development time.  It can provide an explanation of how and why code snippets were used.  It can describe variables, what they’re for, and how they’re utilized.  It can describe program structures that help in debugging and maintenance.  I even remember a comment to a SSC forum post by Jeff Moden who mentioned the return on investment of commenting code.  It also reminded me of Steve Jones’ article about how important it is to comment code.  I believe Jen’s presentation should be required for anyone who writes code.  The benefits for commenting code are endless.

Commenting code is probably one of the simplest and most useful, yet most underutilized, methods of documentation.  I’ve mentioned time and again about how documentation gets no respect in technology, and yet too many developers still refuse to do it.  Jen’s presentation was a reminder of how important it is to document code; in fact, she also mentioned some points that didn’t occur to me.  For example, documents such as Word, Wikis, or Confluence can get lost, misplaced, or buried.  Code comments, however, stay with the code; it cannot get lost or separated from the code.  (There were several other points she mentioned as well, but it’s her presentation, not mine, so I don’t want to take away from it.)

When I was in school, I was docked points when I didn’t comment my code.  Sometimes, I think developers should be docked pay if they don’t do so.  Commenting code is the simplest, yet most effective tools around.  So you want to be a better developer?  Then comment your damn code!

Advertisements

To paper, or not to paper?

After trying to implement updates to one of my documents.  I realized that I was having problems trying to visualize how to incorporate a number of needed changes.  After staring at my document on the screen for a period of time, I decided to print out my table of contents to better visualize the document structure.  The table of contents serves as a de facto document outline, enabling me to get an idea of the document’s structure.

However, the mere fact that I had to print out the table of contents got me thinking: is paper still relevant in this digital age?

These days, it seems like everything is digitized.  An increasingly number of people are reading books on e-readers and tablets.  Even I, a longtime New York Times reader, stopped buying hardcopy newspapers a long time ago and started maintaining a digital subscription.

That said, there’s something to be said about savoring a good book — a real book, with paper pages to flip, and a dog-eared cover.  Even though I maintain a digital Times subscription, every once in a blue moon, I’ll pick up an actual newspaper and sit myself down in a comfortable chair in a Starbucks, flipping through the pages and getting my fingers dirty with newspaper ink, while enjoying a cup of mocha.

(I’ll also confess to being a little biased, since my wife works in the newspaper industry.)

While viewing documents entirely on a screen seems to be the way of the world these days, I’m finding that there are some instances where there is no substitute for paper.  For starters, I recently wrote that, as a tech writer, I sometimes come across mental blocks in my work.  Viewing a document as a hardcopy, as opposed to on a screen, sometimes helps to break the stalemate.  With paper, I can take whatever individual sheets I need, place them on a table, and skip through whatever I need to edit.  I am able to better visualize document structure and hierarchy so I can better understand where things need to go.  I also have the advantage of being able to pick up a pen and scribble any notes wherever I need them and wherever I please.  Try doing that on a computer screen.

Paper copies could also help alleviate eye strain.  (I am not an expert in this, so for all I know, I might be off-base here.)  I sometimes find it easier to look at material in print than I do on a screen.  I say this, despite the fact that the old tube-style CRT monitors have gone the way of the dinosaur.

By no means am I advocating that we should go out and kill more trees; on the contrary, I am all for taking steps to protect the environment.  All I am saying is that paper is not completely dead.  Although most documentation these days is digitized, I believe that the imminent demise of paper is somewhat exaggerated.

Technical writer’s block

“What no wife of a writer can ever understand is that a writer is working when he’s staring out of the window.”
— Burton Rascoe

“Waiting for the break of day; searching for something to say; flashing lights against the sky; giving up, I close my eyes…”
— Chicago, “25 or 6 to 4”

Those of you who write creatively — whether it’s a book, an article, music, etc. — have all experienced writer’s block.  Even if you don’t write, maybe you’ve experienced it in some form.  Maybe you were assigned a writing project in school.  Maybe you’re trying to come up with ideas for a party or how to celebrate a co-worker’s special occasion.  It even comes up when my wife and I discuss what to do about dinner (“What do you want?”  “I don’t know!  What do you want?”).  No matter what form it takes, the moment when your brain fails to come up with any ideas (sometimes called a “brain cramp”) happens to all of us at some time or another and more often than we’ll admit.  As much as I’d like to post a ‘blog article each day, there’s a reason why I don’t.  A lot of it is because I don’t necessarily write articles professionally and I don’t always have the time to do it, but an equal part of the reason is not being able to think of things to write about.

For this article, I’d like to talk about technical writer’s block — yes, there is such a thing, and it happens more often than you think.  (I don’t know if that’s a widespread term; for all I know, I might have just coined a new phrase.)  However, it differs from other forms of writer’s block in that a technical writer already has a subject about which he or she is writing.  In this case, it’s not a matter of what you’re writing about; it’s more a question of how to write about it.  I can’t tell you how many times I’ve stared at a computer screen for (at least) twenty minutes, only to realize that I spent those twenty minutes just blankly staring at the screen.

Those of you who are technical writers, let’s see a show of hands: how many of you have been given, say, a step-by-step instruction to write about, but have agonized about how to put it together?  Should you list them as numbered instructions?  Should you keep it to simple bullet points?  Is it better to put items into a table and write out definitions for the terms?  People who know nothing about technical writing don’t understand the struggle; they think it’s just a matter of throwing it together and making numbered points from them.  What they don’t realize is that it is not that simple.

For one thing, writing instructions isn’t that much different than writing code.  Both involve logic.  But let’s say you have an instruction to “push the red button” but only if you performed another step or are faced with a specific circumstance.  In structured programming, this would probably take the form of an IF-THEN or CASE statement.  But when you’re writing a document, situational instructions aren’t as clear cut.  There is no standardized method for writing an if-then statement in a step-by-step document.  I’ve seen this situation addressed in different ways; in one job where I was employed as a full-time technical writer, the group include a style with their template that included a small table for these situations: do this for one situation, do that for another.  I’ve seen others where a step is accompanied by a note: “this only applies to (whatever).”  Since there is no standard way to address this, it likely makes writing instructions more, not less, difficult than writing code.

Your audience likely plays a role.  I’ve espoused time and again that you need to know the audience for which you’re writing.  In my first successful technical writing project, I made sure that I put myself in the reader’s shoes, empathizing with the reader.  “How do I write this so I can see what I need to do?”  That strategy made things very clear, and I was able to write a good document.  Unfortunately, tech writers don’t always have this luxury; sometimes, either the type of audience is unclear, or the writer is writing for multiple audiences.  If you know your audience, it gives you an idea as to how to structure and write your document.

As I wrote earlier, design matters.  Of all my experiences with technical writer’s block, this is probably the one with which I struggle the most.  How should things be laid out that would most help the reader?  Where should things be placed so that they best direct an end user?  A document’s design often makes or breaks a successful document.

I just wrote about some of the issues I face.  How to resolve them is not as clear cut, and I don’t have as many answers as to how to address them (that might be worth its own article).  Here are a few ways that I’ve dealt with technical writer’s block.

  • Ask questions.  Clarification helps answer some of the issues with which I have to deal.
  • Get help.  Another set of eyes can sometimes break the impasse.
  • Work on something else.  Working on another task can sometimes spur ideas.
  • Walk away.  Sometimes, you just need to take a break.

I’m sure there are others ways as well that haven’t occurred to me.  How do you deal with technical writer’s block?  Feel free to respond in the comments.

Agnostic document references

Many of you who are technical writers — or data professionals — understand how important it is to not expose real data.  There is a huge emphasis on data security, as there should be.  But a lot of people never think about smaller pieces of data within a document — something as simple as, say, an email address.  In a lot of documentation I write, I make it a point to make much of it as anonymous and agnostic as possible.  There are a number of reasons for this, as I outline below.

I’ll start with a point of emphasis that I make in documentation time and again: know your audience.  Earlier this year, I was responsible for writing a user guide for an application that was to be used by multiple clients.  When I first started working on the document, the application was only being used by one client.  The application — and the document — contained many references to that one client.  In order to update the application to serve multiple clients, all references to the one client had to be removed, not just in the application itself but also in the documentation.  If a document is to be used by multiple audiences, specific client references should be made generic.

Likewise, I’ve accessed applications that display my name on the screen: “Welcome, Ray Kim,” for example.  If I screen-capture that image, I often alter the image so that my name is removed.  I don’t know about you, but I wouldn’t want to be contacted incessantly about an application that I probably know little about.

Another reason is data security, which becomes a larger issue by the day.  Sensitive corporate data risks being exposed within documentation.  For example, for my screen captures and illustrations, I request a “dummy” account that displays “bogus” corporate data for document illustration purposes.  I’ve gotten into the habit where I request this for every document I write.  Corporate data is sensitive; indeed, there is an increasing awareness of keeping such data private (the European Union’s GDPR and laws such as HIPAA and various other data protection laws come to mind).  Live data should never be used in documentation (unless authorized by the client in question); you can never tell what can be revealed in that data.

Here’s another reason I have for keeping documentation generic.  Let’s say, for example, an instruction for additional help directs you to “contact john.smith@yourcompany.com” in your document.  However, there’s one problem: John Smith no longer works for the company.  The correct contact is john.public@yourcompany.com.  But nobody made you aware of this change, nor is anyone aware that this contact is in the documentation.  And who is to say that John Public won’t leave the company or change roles in the next couple of weeks?  Additionally, listing a specific person runs the risk of that person getting spammed by peope who decide to use the contact for reasons other than the one listed in the document.  These risks come up any time a document references a specific person.  A better approach is to reference something more generic — say, a generic mailbox (e.g. HelpDesk@yourcompany.com) or a departmental site.

Here’s another argument for using generic references: how often does the document need to be updated?  Let’s say, for example, you write a document that references “Acme Corporation.”  Over the course of time, “Acme Corporation” changes — perhaps the company is bought or merged, the name changes, and so on.  How often do you need to go through your document looking for “Acme Corporation” and all its variations (shortened to “Acme,” abbreviated as “AC,” misspellings, etc.)?  And suppose your document is hundreds of pages long, with company references interspersed all throughout the document?  Making those edits does not make for a good working day.

Documentation runs the risk of exposing large amounts of data.  For data security, privacy, or even simple editing reasons (and maybe a bunch of others that I haven’t thought about yet), unless there’s a specific reason for not doing so, illustrations, examples, and references should often be made generic.  It’s a simple but critical step that can make your job better as a technical writer, and save your organization from a number of headaches — possibly ranging from complaints from audience members to a lawsuit.

The importance of maintaining a LinkedIn account

My own presentation and a lightning talk by Paresh Motiwala from our SQL Saturday this past July got me thinking about my own LinkedIn account.  I’ve been going through the activities feed fairly regularly, making sure my ‘blog articles are posted, getting an idea of how many people see (much less, actually read) my articles, and to get occasional updates as to what my contacts are doing.  But it also occurred to me that it’s been a while since I did a full-fledged inventory of my own LinkedIn account.  I’ve written before about the importance of maintaining documentation, and my own LinkedIn profile is no exception.

Why inventory my LinkedIn account?  To answer this, I suppose I should explain why I have a LinkedIn account at all.

I’ll admit that I’m usually a lot more active on LinkedIn if I’m looking for a job.  I don’t know the statistics as to how people use LinkedIn, but it wouldn’t surprise me if job hunting is the number one reason.  Nevertheless, I try to check my LinkedIn fairly regularly, regardless of whether or not I’m looking for new employment.

I should note that, as of this article, I am not actively looking for employment.  That said, I still think it’s important to maintain my LinkedIn account.

Probably my biggest reason for maintaining a LinkedIn account is networking.  I’ve written before about the importance of networking in your professional lifetime.  I have an entire presentation about networking.  LinkedIn provides a tool for maintaining my networking contacts and staying in touch with them.  I’ve often said that one of my main reasons for maintaining my Facebook account is to keep in touch with family and friends, and to keep them up to date with whatever is happening in my life.  LinkedIn mostly serves the same purpose, with the primary difference being that the context is professional, not personal.

If you’re job hunting, a LinkedIn account is invaluable (I would even go as far as to say it’s necessary).  I came across an article (on LinkedIn, of course!) that stated about 85% of jobs were filled through networking.  I can personally attest to this; the person who hired me for my current job is connected to me through both Facebook and LinkedIn.

If you’re not convinced that LinkedIn is necessary for effective job hunting, imagine this scenario.  You’re a hiring manager who’s looking to fill one position, and is looking over two nearly identical resumes.  Both people are qualified for the position.  You decide that you want to know more about them.  You see that one has a LinkedIn profile.  The other does not.  Guess which one will have the advantage.

I’ve seen job applications that ask for your LinkedIn profile URL.  That tells me that employers take LinkedIn pretty seriously.

I said earlier that I am currently not actively seeking new employment.  However, I didn’t mention anything about passively looking.  Although I am content in my current position, I would be remiss if I didn’t keep my eyes and ears open for my next big thing, whether it’s a step up in my position or my salary.

I attended a SQL Saturday presentation by my friend, James Serra, about how to build your career.  One of the takeaways from his presentation was not to get comfortable if you want to get ahead — a point that prompted me to write about it in another ‘blog article.  Granted, I enjoy what I do, and I’m sure I could remain in my position for some time, but I’d be crazy to pass up an opportunity that represents a major step up and is right up my alley.

So, I started going through my own LinkedIn profile.  First, I went through my contacts to make sure it was up-to-date.  I started by going through the last SQL Saturday schedule, looking through the speaker profiles to see who else had LinkedIn accounts (those who have one are noted by a LinkedIn icon under their names), and checking to make sure I was connected to them.  I should note that I did not do this with all the speakers, but mainly the ones I know reasonably well and with whom I feel comfortable connecting.

Going through the “People you may know” feature, I was surprised to find a number of people whom I know but was not already connected on LinkedIn.  I sent them invitations to connect with me.  As of this article, about ten of them have accepted my invitation within the past week.  More will be coming, I’m sure.

I also looked at my own summary and realized that it’s not really a “summary” — that is, it should be a list of highlights and fairly easy to read.  I have some ideas in my head as to how to rewrite it; I have not yet done so as of this article.  Nevertheless, my personal professional summary will definitely get some tweaking sometime in the days ahead.

Whenever I assemble a new presentation, I make sure that it is listed under my Publications section.  It indicates that I am active with my presentations.  Demonstrating that you are doing something to enhance your background (in this case, staying active with my SQL Saturday presentations) is always a good thing.

I also solicit recommendations from people.  Maintaining recommendations on your LinkedIn enhances your profile.  And I make it a point to reciprocate when someone leaves me a recommendation.  This is a key point of networking; networking is a two-way street.  If someone does you a favor, make sure you do the same.

Maintaining LinkedIn is critical for your professional career.  I only talked about a few reasons for maintaining your account; there are many more that I didn’t mention.  (Out of curiosity, I Google-searched “reasons to maintain linkedin account” and a number of links showed up.)  In this day and age where maintaining an online presence is nearly expected, LinkedIn might make the difference in advancing your career.

Want to learn about a topic? Try writing about it

Every now and then, I’ll peruse the forums on SSC.  In addition to people answering questions about SQL Server, there also tends to be some banter, which is probably not unusual in many forums of this nature.  One of the comments I’ve seen time and again is something like, “I learn more about subjects by answering people’s comments on these forums.”

There is more truth to this statement than people realize.  In my experience in writing about technology, I often find that I end up learning about the technology about which I’m writing — sometimes to the point of becoming a subject matter expert.

Several years ago, I taught part-time at a local business school (roughly equivalent to community college level).  I taught primarily general mathematics and a few computer classes.  I was once asked to fill in for another instructor who taught statistics.  My problem: I didn’t know much about statistics.  So, I read up on it (along with the syllabus that I would be teaching that day).  I wanted to at least be able to sound like I knew what I was talking about.  As it turned out, by teaching that class, I actually learned something about it.  The students were not the only ones who got an education that day.

The other day, I began writing a draft article regarding a subject about which I’d like to learn more: BI (edit: the now-finished article can be seen here.).  I’ve dabbled in BI a little bit; I worked a previous job where I was asked to perform some data analysis (which is how I learned about cubes and pivot tables), and I took a course in decision-support systems in grad school.  I’m seeing more SQL Saturday presentations about BI; indeed, there are even SQL Saturday conferences dedicated to BI topics (usually indicated by the words “BI Edition”).  It is a topic about which I do have some interest, and it’s something about which I’d like to learn more.

My friend, Paresh Motiwala, who was one of the organizers for SQL Saturday Boston BI Edition a while back, encouraged me to apply to speak at the event.  I said to him at the time, “the only thing I know about BI is how to spell it!”  (His response: “Hey, you know how to spell SQL!”)  On hindsight, I probably should have applied; it turns out that even BI Edition conferences accept professional development topics, under which nearly all of my presentations (so far) are categorized.

So if I claim to know so little about BI, why did I decide to start writing about it?  Well, I’m trying to learn about it, and I’d like to pass along what I learn.  But, I want to place a greater emphasis on the first part of that statement: I’m trying to learn about it.  Writing about it makes me learn something about it a little more in-depth.  And by doing so, I discover that I have a better grasp of the topic.

Hopefully, relatively soon, you’ll see an article from me about BI.  Hopefully, I’ll have learned enough writing about it that you’ll be able to learn something from me.  And hopefully, I’ll have demonstrated that I’m learning something new, and improving myself in the process.

If you want to learn something new, try teaching it or writing about it.  You’ll be surprised how much you, yourself, learn in the process.

Better Comments

This is a reblog of a post by my friend, Steve Jones. I’ve often said that commenting code is a form of documentation, and needs to be done more.

Voice of the DBA

I assume most of your comment your code.

Well, you probably comment code most of the time.

I’d bet your comments have quite a bit of detail.

And you do this completely inconsistently.

That’s what I’d think, or maybe just what I want. Even the best developers I know will not consistently comment code. You can drift through any project on Github and see this. Those projects on GitHub might even be better documented because people know they are public. In most corporate environments I have worked in, I’ll find that when people get busy, or distracted, or even when they’re experimenting to find a solution, and they don’t write detailed comments. Usually only when someone fixes a bug, with a solution found quickly, do I get a really useful comment.

There are all sorts of ways that people think about commenting their code. I ran across a post from…

View original post 254 more words