How comments in programs are used these days

Theoretically you can use dingbats and emoji in source code. Wouldn’t recommend it, though.
        meter.calibrate(FACTORY_DEFAULTS);
// because of type erasure scala primitive types just become Object                                 if (operandType != Object.class                                     && !conflictingDefinitions.contains(operandType)) {
if (classToMethod.put(operandType, method) != null) {
classToMethod.remove(operandType);
// let's not create ambiguity
conflictingDefinitions.add(operandType);
}
}

Temporarily deactivating troublesome lines

Both NetBeans and IntelliJ have a keyboard shortcut to “comment out” lines in the program. I’m sure Eclipse also has a shortcut for that, and it’s probably the same key combination.

    meter.calibrate(FACTORY_DEFAULTS);
// meter.adjustVariance(2 * MINIMUM_TOLERANCE);
// Problem with adjustVariance, makes all our tests fail
meter.load(this.preferences);

To do (reminders)

The perfect use of a temporary comment is to remind yourself of something that needs to be done but which, for whatever reason, you don’t have time to do today.

    public Fraction dividedBy(Fraction divisor) {
// TODO: Check divisor is not zero, throw exception if it is
return this.times(divisor.reciprocal());
}
public Fraction dividedBy(int divisor) {
// TODO: Check divisor is not zero, throw exception if it is
return new Fraction(this.numerator, this.denominator * divisor);
}

Planning the program (pseudocode)

We can take the concept of To Do comments to its logical extreme and use them to write our plan for a function or procedure, or even an entire program, before we write even one line of syntactically valid code.

    public static byte symbolLegendre(int a, int p) {
// Check that p is prime
// Compute (p - 1)/2
// Power mod: a^((p - 1)/2) mod p
// If power mod is p - 1, return -1
// If power mod is p, return 0
// If power mod is 1, return 1
return -2; // This is just for the failing first test
}

Comments about flaws in reasoning

You might write something that passes all the tests and works well enough but still have the sense that something is not as efficient or as elegant as it could be.

  for (int i = 0; i < totalTestIntegers; i++) {
try {
result = testIntegers.get(i).times(testConjugates.get(i));
} catch (RuntimeException re) {
result = zero; // Avoid variable may not be initialized error
fail("RuntimeException should not have occurred");
}
assertEquals(testNorms.get(i), result);
}
  for (int i = 0; i < totalTestIntegers; i++) {
try {
result = testIntegers.get(i).times(testConjugates.get(i));
assertEquals(testNorms.get(i), result);
} catch (RuntimeException re) {
fail("RuntimeException should not have occurred");
}
}

Comments as indicators of insufficient granularity

Some people say that no function or procedure in a program should be more than four lines long. That is a bit draconian, in my opinion.

    @Override
public void paintComponent(Graphics g) {
super.paintComponent(g);
// If enough pixels per unit interval, draw grids
if (this.pixelsPerUnitInterval > THRESHOLD) {
// If applicable, draw grid for "half" integers
if (this.ring.hasHalfIntegers) {
int verticalDistance;
g.setColor(this.halfGridColor)
...about 30 lines omitted...
}
// Now the grid for "full" integers
g.setColor(this.fullGridColor)
...another 30 lines omitted...
}
// And now to draw the points
int currPointX, currPointY;
g.setColor(this.primeColor)
...about 250 lines omitted...
}
    @Override
public void paintComponent(Graphics g) {
super.paintComponent(g);
// If enough pixels, draw grids
if (this.gridsOn) {
// If applicable draw "half" grids
if (this.ring.hasHalfIntegers()) {
// Draw "half" grids
this.drawHalfGrids(g);
}
// Draw "full" grids
this.drawFullGrids(g);
}
// Draw points
this.drawPoints(g);
}

License and copyright comments

Perhaps for as long as programming languages have had commenting syntax, programmers have put information about authorship and copyright in comments at the beginning of the program.

/*
* Copyright (C) 2018 Alonso del Arte
*
* This program is free software: you can redistribute it and/or
* modify it under the terms of the GNU General Public License as
...a few lines omitted...
*/
/*
* Copyright (C) 2018 Acme Corporation
*
* All information contained in this source code is technical,
* proprietary, trade secrets. Any employee who willfully discloses
* any of this information is subject to the penalties outlined in
* his/her non-disclosure agreement, including but not limited to
* termination from employment by Acme Corporation.
*/

Documentation comments

I don’t know what programmers and/or technical writers used to document APIs before documentation generation tools existed. But I can easily imagine the sorts of nightmare scenarios that could ensue from a failure to update the documentation in a timely manner.

    /**
* A test of dividedBy method, of class Fraction. This makes
* sure that division by zero causes either
* IllegalArgumentException or ArithmeticException. Any other
* exception, or no exception at all, causes the test to fail.
*/
@Test(expectedExceptions = {IllegalArgumentException.class,
ArithmeticException.class})
public void testDivisionByZero_causesException() {
Fraction frac = new Fraction(1, 2);
frac.dividedBy(0);
}

Comments in tutorials and exercises

One reason comments may be necessary in tutorials is that code in a tutorial might be missing the sort of context that would appear in actual production code.

In summary

With meaningful identifier names and thoughtful documentation comments, the need for permanent clarifying comments in a program is reduced if not altogether eliminated.

is a composer and photographer from Detroit, Michigan. He has been working on a Java program to display certain mathematical diagrams.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store