Commentary lines in programming

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 / softwareCommentary character(s)Example
VBA (Office) and VBscript (.vbs)    ' in front of the text' my commentary
Rem in front of the textRem 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 textRem 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 formulasuse 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

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!




Homepage

Section contents

About Wim

Wim Gielis is a Business Intelligence consultant and Excel expert

Other links