So I know by now I do most things in programming in a weird and unconventional way, but somehow that has worked pretty well for me. My sites are definitely a bit more buggy than most, but I ship quite a bit faster too. You can’t have it all.
One thing I never was able to learn properly was commenting my code. The way people usually comment code is this:
This was taken straight from PHP The Right Way. The thing I struggle with is that the deeper you get with indentation, the more of a mess this becomes. What if you’re deep in two foreach loops, how do you have any idea which code part starts and ends where? The issue is that the commenting doesn’t segment the code in any way. You can’t see the end of a piece of code.
You can use functions to summarize code in to one line. That solves a lot of things. But making every little snippet of code into a function can slow you down too.
What if there was a middle ground?
I got inspired by HTML, its code is always very clear because you see when a tag starts and ends. It’s pretty clear. So here’s how I comment based on that:
I use this style of commenting in PHP, JavaScript, Obj-C and even Shell scripts and it’s saved me countless of time quickly figuring out what part of a file I’m actually editing and what it does.
Even more fun is that if you use Sublime Text, you can simply fold down the entire parts between tags like this:
It’s probably wrong in the grand scheme of coding laws written up by the board of bearded men who roam around Hacker News. But that’s fine. I don’t have a beard.
P.S. I wrote a book on building indie startups called MAKE. And I'm on Twitter too if you'd like to follow more of my stories. I don't use email so tweet me your questions. Or you can see my list of posts. To get an alert when I write a new blog post, you can subscribe below:
Follow @levelsio