The Art of Commenting

This week I noticed an article on comments in PoSh over at Simple Talk. It's a nice look at the topic from Greg Moore and discusses the various ways that you can comment in the language. Since these scripts are often shared in a corporate environment and because they may outlast your tenure, it's a good idea to include comments in your scripts and functions.

The idea with PowerShell is similar to what you get from docstrings in Python. Since many people can script and build modules, being able to get some help and understanding of the code is important. Even for the modules I write, I may use them for some time and then put them down. When I go to use the same cmdlet or function again, I might not remember all the parameters or what I was thinking. If you've ever had to dig into code to understand what is happening, you quickly learn to appreciate those well documenting help strings.

You may quickly learn to despise those that don't write them well or even forget to include them at all.

Writing a useful comment is a bit of an art. The author often needs to put themselves in the shoes of a less skilled individual, or maybe one that is context switching and needs to quickly understand what the code is doing. Not necessarily exactly how it works, but what it is supposed to do. This helps us decide if we can use the code quickly, or if we might need to dig in further.

In the article, Greg points out some nice additional comment items, such as requirements for the module to run. These are the types of quick enhancements to code that greatly improve its useability for others. I'd highly recommend everyone learn about comment based help in PoSh, docstrings in Python, and other valuable commenting techniques in your language of choice.

Learning to write good comments is a valuable skill, one that your team will appreciate. Since most of us work on teams these days, those skills just might make you more desirable for that next promotion or even a new position when word gets out. Practice becoming a good comment writer.

Steve Jones - SSC Editor

Join the debate, and respond to the editorial on the forums

A common task in data science and analytics involves using data to make predictions. Predictions can add a tremendous amount of value to businesses, allowing them to plan ahead, focus resources and increase efficiency.

Every now and again, we as DBAs need to get away from the daily grind of the hum drum tasks. We need to find a way to have a... The...

I recently was working on a customer system where a myriad of bad things had occurred simultaneously that left them in a scenario where their primary database server had...

A picture is worth a thousand words, right? Sometimes, a picture for an event session just may be able to say it better than 50-60 letters used to try... The...

Validating your server setup is an integral component of your duties as a SQL Server DBA. When performing those validations, it is possible to run into an intriguing difference... The...

When running into error 1326, it makes plenty of sense to try to create a backup dump device (only as a testing exercise) as well as test the connectivity... The...

I wrote recently about menu items being missing from SSIS and other BI projects in VS2019, but another thing that's gone MIA is the Integration Services Connector for Power...

I posted last time that I'd completed my Part 1 eBook on Core Concepts. The Part 2 eBook is on the differences in the SQL language between Snowflake and...

I've had a lot of great feedback on my series of blog posts about Snowflake, and explaining the concepts for an existing SQL Server audience. Just out for Christmas...

One of my clients migrated to SQL Azure Managed Instance and contacted me for an interesting situation. Let us resolve Restore Error. First appeared on SQL SERVER – SQL Azure...

The Power BI 2020 Salary survey was popular enough...

Unlike the last couple of years (e.g., 2019), I’...

Introduction The purpose of this blog is to provide brief overview of the MS Exam 70-768 with focus on the preparation from the perspective of a junior MSBI developer....

One tries to climb the ladder of success but at th...

For years I have written a year end post about things that didn’t happen to me for the previous twelve months. This year I’ve decided to pivot that theme....

Wow, it's been a really big year in many ways. I had a list of goals for the year, and overall I'm pretty happy with where it's ended up....

What an incredible year it’s been.  I kept thinking that I was busy, but I had no idea until I looked at the final numbers (I have a Power... The...

With the end of the year, other things are coming ...

eWEEK PREDICTIONS 2020: The continued development ...

eWEEK TREND ANALYSIS: Cloud services are now the n...

I am honored to present Azure DevOps and the SSIS ...

Feb 29, 2020 is the date for SQLSaturday Tampa, nu...

Powershell in 2012, Powershell 4.x onwards introdu...

Comments are helpful when programming in any langu...

The trick here is to find a way to search thousand...

eWEEK TREND ANALYSIS: Dell Technologies' COO and v...

eWEEK TREND NEWS: A whole new class of technologie...

Building a workstation-class mobile PC that would ...

And new Latitude laptops may entice business users...

Lenovo’s ThinkPad X1 Carbon and ThinkPad X1 Yoga...

Continuing our run of CES 2020 announcements, Leno...

Throughout 2019, we’ve had quite the reverse of performance when it comes to the competitiveness of the modern performance-oriented desktop processor. This year we’ve seen AMD introduce its Zen...

Another year has gone by and it has now been 10 years since DAX was first introduced in late 2009. As usual, it is time to review the past year and to take a look at the year ahead.

Another year has gone by and it has now been 10 years since DAX was first introduced in late 2009. As usual, it is time to review the past...

With the release of SQL Server 2019, CTP 2.1 new features were added to Intelligent Query Processing (QP) feature family. One of those features was Scalar UDF Inlining.

Dangarang

My client had hired me after reading my recent series on Parameter Sniffing. Today, we will discuss Database Scoped Configuration - Parameter Sniffing. First appeared on SQL SERVER – DATABASE...

I strongly recommend that you read my earlier blog posts on this topic before you consider the option of recompile suggested in this blog post. First appeared on SQL SERVER...

I have been having with many of the readers after reading the latest blog post series on Performance and Recompiling Query. First appeared on SQL SERVER – Performance and Recompiling...

With the December Power BI Desktop update, users are introduced to a new color picker when customizing theme colors. The new color picker is much more versatile than the original when selecting colors.

The drillthrough feature in Power BI will let you let you go into more detail about a specific column in a visualization.

Let’s take a quick look at one such calcualtion and how it can be covered with an aggration. I am going to use the same version of AdventureWorks sample database and Power BI model that I used in my previous blog post on aggregations, with a few changes.

Power BI and Excel are tools so close to each othe...

If you used an excel file in a local source (or even OneDrive for Business, but sourced locally), you need to do one extra step to make your query...

You can use a host of time-intelligence functions ...

Splunk is a search engine for collecting and analyzing all sorts of "machine data", including log data and metrics for SQL Server. SQL Monitor gives you the detailed diagnostic...

If you avoid illegal characters and reserved words in your identifiers, you'll rarely need delimiters. Sadly, SSMS applies square bracket delimiters indiscriminately, as a precaution, when generating build scripts....

In this 35 minute livestream recording, I commit conflicting code to a Git repo in Azure DevOps Services using Redgate’s SQL Source Control, then step through options to fix...

The Microsoft SSIS Team announces the general availability (GA) of the SSIS Projects for VS2019 version 3.3! In this version, the biggest change is that we removed Power Query...

Are you interested in guest posting? Publish at DataScience+ via your RStudio editor. Category Programming Tags Data Visualisation Machine Learning Python Sentiment Analysis Customer attrition is a metrics used by many businesses to monitor and quantify...

For this post, we’ll be using Powershell to install and configure the HGS server (required for “attestation”) as well as executing the steps required to configure the SQL 2019 server to work with HGS.

Click to learn more about author Ariff Kassam. Many companies are considering migrating their legacy applications to cloud-computing models and implementing microservices as part of that migration. These organizations...

T-SQL window functions simplify solving many complex queries. In this article, Edward Pollack demonstrates how the functions can be used to find gaps and islands in a dataset.

I was recently answering a forum question about wo...

Let us learn, ISNUMERIC Function and Interesting R...

You are working on a database development project, and you need to obtain the records before/after an INSERT, DELETE, UPGRADE or MERGE Statement to present it to the user... The...

It's useful to be able to find one string within another string. T-SQL has two basic functions for that: CHARINDEX and PATINDEX. CHARINDEX is used to see if one...

Darnit While helping a client out with a performance problem recently, I ran into something kind of funny when creating…

Seriously.

As part of our free SDU Tools for developers and DBAs, we have many scripting functions. SQL Server allows you to create your own database roles, and generally, you...

eWEEK NEWS / TREND ANALYSIS: Technologists are predicting vast changes that they say will show up in 2020, but it’s important to remember that just because something might be...

eWEEK TREND ANALYSIS: Amazon joined the quantum co...

Spaceflight lived, software ownership died, and net neutrality lived and died.

Company may attempt 50% more launches than any pre...

Bosch, a "tier 1" auto supplier, is entering the crowded lidar market.

Gas taxes pay for the upkeep of our roads, but electric cars don't use gasoline.

Vitamin Advil

Click here to learn more about Gilad David Maayan. Kubernetes (k8s) is a popular container orchestration platform. However, the rush to adopt k8s technologies can lead to errors. In...