A few years ago I sold all my stuff to explore the world, creating 12 startups in 12 months and building $1M+/y in companies as an indie maker such as Nomad List and Remote OK. I'm also a big pusher of remote work and try to analyze the effects it will have on society. Follow me on Twitter or see my list of posts. My first book MAKE is out now.
May 04, 2015

My weird code commenting style based on HTML tags

Tech, Tutorials

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:

Subscribing you...
Subscribed! Check your inbox to confirm your email.
Follow @levelsio

How I sped up Nomad List by 31% with SPDY, CloudFront and PageSpeed

Now is probably the time to make HTTPS the default on all your sites and apps