This post is all about comments and the importance of commenting your code. This topic may seem boring, but I promise it is extremely important and a great habit to learn.
Comments in any programming language are text blobs that are not readable/executed by the programming engine. In other words, they don’t do anything other than provide context/information for the user trying to understand the program or section of code they are reading.
In most languages there are two types of comments: single-line (inline) and multi-line. Single-line comments are comments that can start at the beginning or end of one line of code. They are great for short descriptions about the code directly before or on the next line. Multi-line comments are comments that can span many lines in the programming interface that are great for introductory descriptions about the program or to introduce new sections of code. Common introductory comments can include the author, date created, and overall purpose of the code.
A good practice is to start each program or code you are creating with multi-line introductory comment. The below example is how a multi-line comment in DAX (Microsoft Power BI) would look like.
/* Purpose: Creates a filtered count for pharmacy stock out medications Author: Ben Moore Contact: email@example.com Date Created: 3/17/2021 */
Multi-line comments in DAX are created with /* … */ (with your comment in the …)
Single-line comments in DAX are created with either // or —
Below is an example of a single-line comment used to describe the purpose of a filter condition on a single line of code.
Example_Filtered_Stock_Outs = CALCULATE( COUNT([Stock Out Measure]), 'Med Item'[Backorder_Flag] <> 1, -- filtering out any backordered items 'Med Item'[DEA_Class_Flag] = 0 // filtering out non DEA class items )
Again, you can use either — or // to create single-line comments. Single-line comments are great for other developers who are trying to read your code who may not know much about the underlying data model or table structures. Most programming languages including different flavors of SQL, python, and R all have the ability to create comments.
In summary, commenting your code as lots of benefits:
- Increases the readability of your code for others
- Starting out your programs or code with an introductory multi-line comment is helpful for documenting the purpose, author, contact info, and date created
- Commented code helps you quickly pass off your work to others without having to go line by line explaining your processes
Do you use comments in your code? Let me know what you think below.
As always, stay digital!