Commenting Your PHP Code

About two years ago I started working for a local web firm. It was small, at that time there we’re only 3 of us, and I was the only PHP developer on staff. We had one client who used our services, combined with another web vendor. Normally we just spit out regular static HTML pages for them, until one day something happened, and we were passed a job that required editing some PHP code from the other vendor.

I honestly don’t remember who the client was, or what the PHP that I was editing was used for, all I remember is that it was the worst code I had ever come into contact with. Nothing made sense, the coding method was random, nothing was optimized, and I wanted to re-write the whole thing and start over. Time did not permit a total re-write, so I was stuck editing the nasty code that was before me. So as I made my edits, I started commenting the code, it went something like this…

1
2
3
4

# I don't know what these moron's where thinking here, but it should work like this...
{some php code}
# Were they smoking crack when they tried to set this up?
{some php code}

I fixed the PHP coding problems, uploaded the files and everything worked as the client requested. I thought nothing else about the project until my boss was on the phone with the other web vendor, trying to explain how I had fixed their code.

What I realized was that my boss was on the phone with the `morons` – as I had called them in my PHP comments – who wrote the horrible PHP code that frustrated me. My boss got off the phone and I asked him… so how mad were they? He didn’t know what I meant. I confessed to my having adding some rude comments in the code as I fixed it. He laughed, and said they never said a word about it.

The moral to this story is that if you comment your code, whether your a moron, or really smoking crack when you write it, chances are someone will better understand what you were thinking when you wrote it and have an easier time maintaining your code.