Let’s talk about F# code comments a bit. If you are fairly new to programming, a comment is simply a note you add to your source file to explain the code or make some other kind of remark that is simply for documentation. Comments are indicated in code by using special markers, and these vary widely depending on the programming language. Comments are not included in compiled code, and end users never see them.
In F#, there are effectively three types of comment styles you can use. The first style is used for single line comments. That is, everything from the start of the comment marker to the end of the line is part of the comment. In F#, the single line comment marker is a pair of forward slashes (//), with no space between the slashes. For example:
// This is a single-line comment.
This style of comment should be familiar to programmers who have coded in C, C++, C#, Java, JavaScript, and other languages.
You can use this style of comment at the end of a line of code, as well. For example:
printfn "howdy" // Comment
The second style of comment can be used on one or more lines. As a result, two markers are required. (* marks the beginning of the comment, while *) marks the end. Anything between the start and the end is part of the comment. Here’s an example:
(*
This is an example of a multi-line comment.
Everything between the start and end markers
is ignored by the compiler.
*)
You can also nest multi-line comments, as shown here:
(* This is one line in the comment.
(* This is a nested comment. *)
This is the last line of the comment. *)
In this example, I’ve also arranged the format differently from the previous example to demonstrate that the position of the markers doesn’t really matter to the compiler. Some people may prefer one format over the other (or something completely different). It’s your choice, although I would argue that the first format has a nicer visual flow and makes it easy to see where the comment begins and where it ends.
The last style of comment is used for XML documentation, which refers to the technique of embedding XML into comments to make it easy for a code documentation generator to format your comments into HTML documentation pages. For obvious reasons, these are also referred to as documentation comments. If you are familiar with java, you may recall these being described as Javadoc comments. F# uses the same sty.le as C#, where XML comments are distinguished by three slashes (///). Note that these also have the same effect as single-line comments, because everything after the second slash is considered part of the comment. There are a number of pre-defined tags that can be inserted into the comments. Here’s an example:
/// <summary>
/// This is a description of the function, class, or
/// other construct.
/// </summary>
/// <param name="someFunctionParameter">
/// Decsription of a parameter or argument to a function.
/// Use as many as needed, and put them in the order they appear.
/// </param>
Here, <summary></summary> marks the start and end of a block where you might put a description of a method, function, variable, or other construct you are writing documentation. The <param…></param> tag is used to provide a description of a function parameter. As mentioned above, there are more pre-defined tags you can use to create slick documentation for your code. You can learn more about XML comments on MSDN.
Note: In Visual Studio, by default, comments are shown in light green to distinguish them from other parts of your code. This is commonly referred to as “syntax highlighting.” Other editors also offer syntax highlighting, but may use different colors. These are typically customizable, although the defaults are frequently perfectly adequate, and often, a company such as Microsoft will put a lot of thought and experimentation into selecting the defaults, so it’s often best just to go with the flow and just get coding.
When and how to use comments is a topic that could cover another article all by itself. I have another blog, The Puntatstic Programmer, where I sometimes cover general topics like this.
Learn F# 