How comments in programs are used these days

Image for post
Image for post
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

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

To do (reminders)

    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)

    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

  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

    @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

/*
* 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

    /**
* 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

In summary

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