How to Write Comments

Denis Krukovsky writes "Should I write comments? What is a good comment? Is it possible to comment a class in 5 minutes? See " Everybody knows that good code is self documenting- which is why my prof in college demanded we write in Ada. I instead suggest commenting in haiku.

Comments

Re:Reading

[jmony]

Problem with Slashdot comments is like code comments... too few is bad, too much is bad. // This line outputs the result

How many times can we see a line like this... that's just writing comments without any reason.

I prefer function header comments which describe what the piece of code as whole does. Not everyline, as teachers say it should be done.

Re: Good code is self documenting...

[bunratty]

Yeah, right. I recently debugged some code that did matrix calculations. It turns out that the matrix involved was always positive definite, and therefore the calculation could be done by performing Cholesky decomposition rather than explicitly taking the inverse of the matrix. Needless to say, there were no comments explaining any of this, and it took me hours to reconstruct the thoughts and derivation behind the original code.

Here's the original code:
L = Cholesky(cov0);
th1 = L.i() * th0;
lrt = (th1.t() * th1).Trace();

which is supposed to compute the same answer as the code:
lrt = (th0.t() * cov0.i() * th0).as_scalar();

I do agree that in general code should be self-documenting when possible, but sometimes you need a few lines of comments to explain a single line of code, or a few paragraphs of comments to explain a few lines of code. I added 17 lines of comments to that part of the program to explain 3 lines of code.

Overcomment everything

[Animats]

Of course you write comments. Usually more comments than code. Don't look for excuses not to comment.

Some comments I've written:

• From a physics engine:

  // The contact force component is aligned with the vector between
  // the two closest points. The frictional force is in a plane
  // perpendicular to that vector and through the midpoint of pnt0-pnt1,
  // The frictional force vector is opposite the velocity vector
  // component in the friction plane.

  // Witness point checks.
  // All witness points must be on their polyhedron's side of the
  // separating plane.

  Here the purpose of the comments is to explain the math.

• From the control code for a DARPA Grand Challenge vehicle. Here's some code I wasn't happy with, so that's clearly noted.

  // constructPath2 -- reactive obstacle avoidance and path planning
  // - the hard cases
  //
  // Called when we have to do some obstacle avoidance
  //
  // Path is an output only.
  //
  // First pass tries to find some path that will work within the turning limits.
  // If that fails, we try "brake then steer" mode - look for the longest path
  // in any direction, regardless of dynamics limits, and slam on the brakes
  // while turning. The actual steering command will be limited later.
  // ***MAKE SURE THAT CHECK IS MADE***
  //
  // ***NEEDS WORK***
  // ***SEARCHING OUTSIDE LIMITS WILL ALWAYS FAIL***
  //

• Finally, here's some Perl code, part of the code that runs Downside.

  #
  # extractsecurityclass -- extract class of a NASDAQ security
  #
  # Foreign and bank securities aren't filed with the SEC, so
  # we need to note this. There are also test and statistics items that
  # aren't real securities.
  #
  # Note that the test for "bank" is rather poor. NASDAQ used to
  # identify banks using a column in the table, but they no longer do so.
  #
  sub extractsecurityclass($)
  { my $vals = shift;
  ## Check for symbols that don't file with the SEC
  if (${$vals}{'test_issue'} ne 'N') { return('test'); } ## is test

  (We have to stop there; Slashdot's "lameness filter" rejects Perl code.)

All code should have well-written comments. As Wirth pointed out years ago, people who can't express themselves well in their native language are generally poor programmers.