3  Comments

3.1 For code readability

One element of reproducible, or more specifically, sustainable code is its readability. In an ideal world, all code would be implicitly readable: its variable, function and class names would all explain themselves and a reader would immediately understand the authour’s intent (always remember that more often than not, reader and authour are the same person!). However, in reality, it’s often necessary to clarify the intent of some particular logic in line with the code, and this is where comments come in handy.

% Comments are lines of code that do not get executed.
% In MATLAB, comment lines begin with a percent (%) symbol.
a = 42; % They can occur on the same line as executable code.
% Everything after the % is a comment.


disp(a)


%{
Multiple lines of
code can be
commented out
as a block.
Using curly braces.
%}


% Comments can also be used to stop lines of code from executing.
% b = 84;

To make this quick and easy, in the MATLAB editor you can use the following key combinations to add or remove comments, respectively:

• Ctrl+R and Ctrl+Shift+R on Windows

• Cmd ⌘+/ and Cmd ⌘+Shift+/ on MacOS

• Ctrl+/ and Ctrl+Shift+/ on Linux

Note: This depends on your MATLAB keyboard settings and can be changed to suit your preference.

Comments are one element of good coding practice that I find most developers (that’s people who write code, i.e. you!) are familiar with, so this shouldn’t come as too much of a shock. However, they aren’t a substitute for the generally good coding practices described throughout this guide.

Large sections of comments should be avoided and if you find that your code needs them, it may be an indication that restructuring your code or using documentation (described later) instead may result in something easier to understand.

3.2 Commenting out code

As mentioned above, comments can be used to prevent a line from executing, which is a useful tool during development. This allows us to test different parameter options and approaches and can be helpful when debugging.

This being said, when we come to share our code, be this for publishing, dissemination or sending to colleagues, commented-out lines of code are a huge cause for confusion and potential errors in execution.

Reproducibility is a difficult challenge, hence this guide needing to exist, so when someone receives some code it will often not execute without errors (that’s the problem we’re trying to solve here). This leads the user to then look for sources of error and commented-out lines of code create ambiguity. Should this line be executed? Did my colleague intend to run this line or not?

Therefore, in most cases it’s a good idea to avoid commenting out actual code when it will be shared.

In practice, this isn’t always practical, so try to add other comments justifying why a line would be commented out at all. And the more packaged up and professional the codebase, the less you should have commented-out lines of executable code. I wouldn’t expect to see this in a finished toolbox or package, for instance.

3.3 Comments for controlling execution - don’t do it!

Following on from this, it’s common during development to use comments for controlling execution, setting options and changing parameters. Whilst this will make sense to the person writing the code (at the time) - other users will rarely be able to understand or have confidence in this approach.

If you’re sharing code and telling the user to “just comment out this line” to get the result they want - this is an indication that you should either split the job of this code into separate functions, or use conditional statements to control the execution.