When I was first learning to code, something that came up a lot was to always comment your code. Code comments have value, but despite what my teachers at the time may have thought, you should try not to rely on comments.

This isn’t to say you shouldn’t communicate to the reader what the code is trying to do, you should just do that by writing readable code rather than relying on comments.

You do this through a variety of methods, some of which I’ve already covered in previous posts. Things like writing descriptive functions, not abbreviating your variable names, simplifying the code by keeping variables close to the functions that use them, and limiting arguments passed to functions and methods. Bascially this:

var scandal = {
  title: "Moon landing a hoax",
  peopleInvolved: [ "Niel Armstrong", "Buzz Aldrin" ],
  evidenceAvailable: [ "back-stage.mp4", "set-photo.jpg", "confession.pdf" ],
  mediaCoverage [ "www.crackpots.com", "www.flateathers.org" ],
  securityStatus: "TOP SECRECT"
}

function coverUpScandal( scandal ) {
  promotePerson( scandal.peopleInvolved[0] );
  destroy( scandal.evidenceAvailable );
  discredit( scandal.mediaCoverage );
  scandal.securityStatus = "Super duper ultra secret";
}

Is better than this:

//Create a scandal object
var scan = {
  // scandel title
  t: "Moon landing a hoax",
  // names of the people involed in the scandel
  pplIn: [ "Niel Armstrong", "Buzz Aldrin" ],
  // evidence avalible
  ea: [ "back-stage.mp4", "set-photo.jpg", "confession.pdf" ],
  // media outlets covering the scanal
  mc [ "www.crackpots.com", "www.flateathers.org" ],
  // security status of the scandal
  ss: "TOP SECRECT"
}

function cus( scan ) {
  // promote Niel Armstrong
  prmtPrsn( scan.pplIn[0] );
  // destory the scandel evidence
  des( scan.es ); 
  // discredit the media coverage
  dis( scan.mc );
  //change the security status of the scandal
  scan.ss = "Super duper ultra secret";
}