// Why comment lines in your code are so important, or are they?

I’ve always appreciated clean code and good comments, but I have to admit I can be a messy code commentator.

This post is a promise to myself: I will comment my code in a better way.

What way, though?

Although programming languages can be very different I believe they have one thing in common: if they are not well organised, they are hard to read.
This includes the way developers write and lay out the code and their comments to it.

After reading few articles online (see list at the bottom of this post), I came up with this top 7 checklist, which is basically a list of how to avoid my bad habits at coding and commenting.

In order to achieve the goal to radically improve my coding abilities I’ll try to follow my own advice and I’ll be more than happy to hear your say!

  • Separate blocks of code with comments
    /* =Structure ------------------- */
body { padding: 0 2em; }
/* =Header ------------------- */
#site-title { width: 40%; margin: 0 0 0 165px; }
  • Comment while you edit
  • Delete the commented lines of code (guilty!)
    background: #fff;
// maring-right: 2em; < DELETE ME!
Use TODO while prototyping (and remove it as soon as it’s done!)
.three-columns {
  // TODO > define the 3 columns style
}
  • Make code as self explanatory as possible (that I do, yay!)
  • Edit your comments if you edit your code
  • Avoid obvious comments
    .game-results {
  margin: 1.5em; // add margin around box < no kidding
}

List of interesting articles on the matter

Oh and happy Saint Valentine’s Day to those who celebrate it.