DEV Community

loading...
Cover image for Getting a comment right

Getting a comment right

rossangus profile image Ross Angus ・1 min read

I love code comments, and think of them as just enough documentation for the dev at that particular moment. They're also, of course, where you explain yourself to your peers and future self.

Today, I needed to switch a dialogue window from being position: fixed to position: absolute I wasn't quite sure if this would turn out to bite me in the arse or not. So I needed to add an unambiguous comment, for future me (hate that guy) to read. Here's how that went:

.dialog {
  position: absolute; // Was fixed
  top: 50%;
  transform: translate(-50%,-50%);
  width: 90%;
}

Hang on - that's not right. It looks like the element was fixed at some point in the past. I'll try quotation marks:

.dialog {
  position: absolute; // Was "fixed"
  top: 50%;
  transform: translate(-50%,-50%);
  width: 90%;
}

Oh God - that just looks sarcastic. I'll type the whole thing out:

.dialog {
  position: absolute; // Was position: fixed
  top: 50%;
  transform: translate(-50%,-50%);
  width: 90%;
}

That colon could be missed in a skim-read and mistaken for bad English. I'll try quotation marks again:

.dialog {
  position: absolute; // Was "position: fixed"
  top: 50%;
  transform: translate(-50%,-50%);
  width: 90%;
}

That'll do, I guess.

Discussion (0)

pic
Editor guide