Commentary lines in programming
- Dec. 21, 2013
Introduction
This is a rather short article about commentary signs in code statements. More specifically, what signs and characters can we use?
Other people have spent countless hours and effort on the "why" of adding commentary lines to code, we do not have to replay that discussion over here. I usually advise to have a reasonable amount of commentary lines, relative to the number of code lines. Not too much commentary lines, not too few.
Overview
Below I show you the characters and structures that are used in a number of environments, in which I programmed in the past, or still do. I will check out this article in the future too since I tend to forget the correct characters in certain programming environments.
| Environment / software | Commentary character(s) | Example |
| VBA (Office) and VBscript (.vbs) | ' in front of the text | ' my commentary |
| Rem in front of the text | Rem my commentary | |
| HTML, XML | <!-- in front of the text and --> after the text | <!-- my commentary --> |
| CSS | /* in front of the text and */ after the text | /* my commentary */ |
| SQL (SQL Server, Oracle, …) | -- in front of the text | -- my commentary |
| /* in front of the text and */ after the text | /* my commentary */ | |
| Batch files (.bat) | Rem in front of the text | Rem my commentary |
| :: in front of the text | :: my commentary | |
| TM1 rules and processen | # in front of the text | # my commentary |
| MDX in TM1 | -- followed by the comment, after the text | {} -- my commentary |
| // followed by the comment, after the text | {} // my commentary | |
| /* in front of the text and */ after the text | /* my commentary */ | |
| Excel formulas | use the N() function | =A1/1000+N("This is revenue in thousands") |
| Eviews | ' in front of the text | ' my commentary |
| Stata | * in front of the text | * my commentary |
| /* in front of the text and */ after the text | /* my commentary */ | |
| C++, PHP, JavaScript, Ajax, … | /* in front of the text and */ after the text | /* my commentary */ |
| // in front of the text | // my commentary | |
| Groovy script | // in front of the text | //my commentary |
The N() function in Excel neglects text: that way you can show text as a way to clarify parts of a formula. Although there are better ways to do this, I did not want to hide this trick for you.
In general commentary lines are automatically marked in green font color in a lot of programming environments, unless you explicitly change this setting in the Options. That is why I used green in the table above. When executing code, these green lines are skipped. It is the way to go to incorporate clarifications, remarks, additional explanations, test code, among others things.
Most of the tools have menu options or icons on a toolbar. With these tools you can select 1 or more code lines/blocks and add or remove commentary signs in 1 operation. Below you can see a screenshot where you in the upper right corner, you will notice icons to turn the selected code lines into comentary (or remove the commentary signs again).
That’s it for this time!
