Index

Day 3 - Comments

• The proper use of comments is to compensate for our failure to express ourself in code

Good comments

• Legal comments (copyright, author, …)
• Explanation of intent (useful information about the implementation and intent behind a decision)
  // This is our best attempt to get a race condition
// by creating large number of threads.
  Useful also when you leave an empty block
  

  try {
      toSending();
  } 
  catch (SocketException e) {
      // normal. someone stopped the request
  }
  catch (Exception e) {
      addExceptionAndCloseResponse(e);
  }

• Warning of consequences
  // Don’t run unless you
// have some process to kill
• TODO comments
• Amplification (amplify the importance of something that may otherwise seen inconsequential)

Bad comments

• Mumbling (comments bad written)
• Redundant comments (// this variable is a variable)
• Misleading comments
• Mandated comments (it is bad to have a rule that says that every function must have a javadoc, or every variable must have a comment)
• Journal comments (use git instead)
• Don’t use a comment when you can use a function or a variable
  // does the module from the global list depend on the
// subsystem we are part of?
if (smodule.getDependSubsystems().contains(subSysMod.getSubSystem()))
  ->
  ArrayList moduleDependees = smodule.getDependSubsystems();
String ourSubSystem = subSysMod.getSubSystem();
if (moduleDependees.contains(ourSubSystem))

• Position markers (used to mark a particular position in a source file - use it only when the benefit is significant)
• Closing brace comments (use subroutines instead)

              } // for
          } // try
      } // if
  } // while

• Attributions and bylines (use git instead)
• Commented-out code (to be super avoided - nobody will delete it!)
• HTML comments
• Nonlocal information (the comments have to describe the code it appears near)
• Too much information
• Function headers (small functions don’t need much description)