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

Always ask someone to test your product

This morning, one of my colleagues posted this message to our Slack channel:

please ask someone else to test your code before pushing it

It brought to mind an important thought (and more ‘blog article fodder): any time you produce something, regardless of what it is — a software application, documentation, a presentation, a music composition, a dish you cooked, etc. — always ask someone else to test it out before you send it out for public consumption.

That testing could take several different forms — it could be an end user trying your application, somebody reading your document, listening to your presentation or your music, trying your dish, and so on.  Testing results in feedback, which results in improvements to your product.

Whenever we produce something, we have our own vision — and our own biases — as to how the product should come out.  We expect our products to be perfect as resulting from our own visions, and we expect (and demand) that the consumers adhere to our visions and how we expect the products to be viewed or interpreted.

Unfortunately, we are blinded by our biases.  The world does not share our same visions.  People who use our products will never, ever, perfectly interpret how our products should be consumed.  More often than not, we’ll find that what we produce will be used or interpreted in ways that never occurred to us.

Even in my own workplace, I write and edit a lot of online documentation.  Much of what I write comes from other sources, often about topics about which I know little (or, sometimes, nothing).  I try to write material based on the information I have at hand.  Very often, I come across gaps that need to be filled.  I’ll do my best to ask original authors what was intended, or to dig for information to fill those gaps.  But in absence of those resources, I end up making assumptions and using my own intuition to fill in the blanks.  Those assumptions might not necessarily be correct, and what I write could end up being different from what was originally intended.  It is for this reason why I am constantly asking my colleagues, “take a look at what I wrote.  I want to make sure what I wrote is accurate.”

In a manner of speaking, creating products is a form of communication — in that what we produce results from an idea in our heads, and the end users — the consumers — are the ones “listening” to the communication — in this case, the end product.  If you are familiar with the basic communication model, a sender creates a message, a receiver interprets the message, and the receiver reacts to the message in the form of feedback.  Producing a products works in exactly the same way — a producer creates a product, a consumer uses the product, and the consumer reacts to the product, generating feedback.  In between the sender and the receiver is “noise” that degrades the message or the product (it is not literally noise — the “noise” can simply be the fact that the sender’s and receiver’s interpretation of the message are not one and the same).

So, any time you create some kind of product, always ask someone else to try it out.  You’ll find that the person’s feedback will result in tweaks to your product.  And you will end up with a better product.

Humble beginnings

Once again, the Facebook “On This Day” memory feature shows it can be a curious thing.  And again, this is one I wanted to share.

The picture you see above showed up on my Facebook memories feed this morning.  Three years ago today, I gave a presentation at my local SQL Server user group meeting.  I had come up with a presentation idea that I thought would be of interest to my user group, as well as other technical professionals.  I jotted down some notes, put it into a presentation, and presented it at my local user group.

About a month later, I gave this very same presentation at our local SQL Saturday.  It was my first SQL Saturday presentation!

I was curious as to how other events would take to my presentation.  Later that year, I submitted it to, and was accepted at, another SQL Saturday.  It was my second time speaking at SQL Saturday, my first time speaking at an event in “foreign territory,” and my first SQL Saturday — speaking or attending — outside of New York State.

Since that humble beginning, I’ve spoken at 13 (soon to be 14) SQL Saturdays at seven different cities around the northeastern United States.  Thanks to this endeavor, I’ve traveled around the region, met a lot of great people, expanded my professional profile, started a ‘blog (that you’re reading right now!), enhanced my career, gained more confidence, improved my presentation skills, and become a better person.  This all came about because of these conferences and from this simple start three years ago.

I hope I’ll be doing many more!  Happy three year anniversary to me!