UPDATE: Due to some overwhelming misunderstandings, I’d like to clarify a few things. I’m not against PHPDoc, or Docblock commenting. Nor am I against the no-comment practices. I believe in good coding practices, and good documentation. The main point of this article is if you DO comment, make those comments useful and not just some throw away stuff that will be compiled into docs later. Seriously. I look through thousands of lines of code a day and Laravel saved me a bunch of headaches by the comments listed below. Not because those comments told me 100% what to do, but because of their headlines that allowed me to scan documents fast and locate important parts of it via Sublime Text’s code map tool.
I’m caught here in a cross fire of fundamentalist non-commenters (“Your code should describe itself! Comments are evil!”) and fundamentalist commenters (“Use Docblock! Anything else is against standards and thus useless!”) yet people didn’t get my point. I don’t use comments for formal compiled documentation. Nor do I use comments to untangle my mess of code. Just saying!
Code organization is a huge thing, especially for developers (because they deal with code), and often times it’s a philosophical debate as to how code should be documented, if spaces should be used instead of tabs, what kind of documentation should be used and so on.
Yet, what no one brings up is the dire issue of COMMENTING. We can all agree that comments are essential (and sometimes used to build half-ass documentation on big systems) but what no one really mentions is the fact that people are crappy commenters. From syntax use to descriptions. We just suck, really badly and that’s not the way a Zen Developer should be. Senor Dan Eden touched on this when discussing max.css conventions.
There are a few things you can do to REALLY improve your commenting, to the point where I’ll fall in love with your damn code, will want to fork, rebase it, make it my own, just to have such a great commenting system.
Not only will this be super-damn-awesome but it will be useful, very useful, especially when working on big projects where organization and understanding is key. Like I said, it’s what makes a good web developer.
Having worked with Laravel for the past couple of weeks, I think I found a contender. So here’s how YOU can make your commenting attractive, desirable, and make it feel young and vibrant.
Step 1. Be informative
Like seriously. I had to, in the past, go back and comment someone else’s code (no, not a newb dev, a seasoned ‘pro’) just for it to make sense. If I EVER see this again, I’m going to do something stupid and something very bad (like write this post or an equivalent again):
/* another section */ /* var something <- integer var whateverelse <- string function(int, string) */
No really, that’s commenting? Thanks for letting me know something and whateverelse need to be an integer and string and that the function needs int and string. Genius. How about telling me what this code does and what the something and whateverelse are supposed to be? How about telling me where this is used and what to do about?
Here’s a slight improvement (meant for code documentation)
/* Media Section @something = A variable used to number stuff @whateverelse = A var describing said stuff @function(int,string) = needs something and whatever else */
Better. A bit more useful. Let’s crank it up a bit and see how I comment stuff:
/* MEDIA SECTION something = variable used to number stuff (number of users, number of links etc.) REQUIRED whateverelse = string to describe said stuff such as "Number of Users", "Number of Links". NOT REQUIRED (defaults "Number of stuff") function() = takes in 'something' and 'whateverelse', outputs a neat HTML thing. Does not need to be escaped */
Let’s add a bit of formatting and better semantics:
/* MEDIA SECTION something: * int * numbers stuff * ex: number of users, number of links * REQUIRED for function() * no default whateverelse: * string * describes 'something' * ex. "Number of Users", "Number of Links" * NOT REQUIRED for function() * default: "Number of Stuff" function(int, string) * uses 'something' and 'whateverelse' * outputs a neat HTML thing * ex: <span>4</span> of Number of Links * no need for escaping */
Whoa, holy crap! That’s like a tutorial right there! It all makes sense now. You can minimize the crap out of that javascript right there as long as you leave me THIS kind of documentation!
Let’s look at what Laravel does:
/*
|--------------------------------------------------------------------------
| Application 404 & 500 Error Handlers
|--------------------------------------------------------------------------
|
| To centralize and simplify 404 handling, Laravel uses an awesome event
| system to retrieve the response. Feel free to modify this function to
| your tastes and the needs of your application.
|
| Similarly, we use an event to handle the display of 500 level errors
| within the application. These errors are fired when there is an
| uncaught exception thrown in the application.
|
*/
Event::listen('404', function()
{
return Response::error('404');
});
Their entire framework has a big novel written in it. I know it adds to space but REALLY! Look at this. No, not each line is commented like this but a good amount of the framework is, especially the part a regular developer will deal with (the application config). It really is like a novel, a well written novel that you’re eager to read. I wish more software products were done like this.
Step 2. Formatting
In the previous examples, you can see that FORMATTING has a lot to do with comments too. And that’s what got me start on my article. I LOVE comment separators. I absolutely love them. When you have a big chunk of ASCII that lets you know “HEY, hey, dude, new section. Pay attention to this!”
There are several alternatives and I think, again, Laravel has nailed it. Let’s look at standard commenting conventions:
// Comment Title /* Comment Block Text that spans several lines */
So this is actually pretty good but we’ll kick it up a notch by challenging Twitter’s Bootstrap’s commenting:
// CSS3 PROPERTIES // --------------------------------------------------. // IE7 likes to collapse whitespace on either side of the inline-block elements. // Ems because we're attempting to match the width of a space character. Left // version is for form buttons, which typically come after other elements, and // right version is for icons, which come before. Applying both is ok, but it will // mean that space between those elements will be .6em (~2 space characters) in IE7, // instead of the 1 space in other browsers.
That’s a heading, and that’s a multi-line. How much prettier is that? Not too much extra work (if you’re working in an IDE or Sublime Text at least), you just CTRL+/ or CTRL+K+C it and you’re good to go Image may be NSFW.
Clik here to view.
So, I would appreciate this kind of commenting at the minimum. For coding, include wtf all those things are that you’re using. Thanks!
The thing is, I’m not a hundred percent fan of this. The title does not SEPARATE enough, it’s easy to get lost in. Bootstrap also varies the length of the lines underneath. Not cool.
Let’s kick it up a notch, have you seen this type of commenting?
/****************** ***** TITLE ******** ******************/ /********************************* Multiline Stuff Goes here! *********************************/
As patriotic as this may seem, it’s killing my eyes. Stop it. On top of that, if you change the title name, you deal with hazardous formatting. Here’s my IDEAL:
/*
|--------------------------------------------------------------------------
| Laravel Configuration Loader
|--------------------------------------------------------------------------
|
| The Laravel configuration loader is responsible for returning an array
| of configuration options for a given bundle and file. By default, we
| use the files provided with Laravel; however, you are free to use
| your own storage mechanism for configuration arrays.
|
*/
Laravel\Event::listen(Laravel\Config::loader, function($bundle, $file)
{
return Laravel\Config::file($bundle, $file);
});
Why Laravel again? Here’s why:
- the block title comment does NOT need any special reformatting with a different tile (many comment titles do)
- the description is latched onto the tile and paragraphed with enough space to increase legibility
- it’s easy to copy/paste it and to add more lines
- when scanning through the site, these headings REALLY help separate different sections
SO that’s it, that’s what my beef is today.
I hope everyone appreciates this strange rant on comments!
What I (Selfishly) Expect The Internet People To Do
Make a Sublime Text 2 plugin that will automatically create a a small comments template akin to Laravel’s (which someone informed me exists). Press CTRL+A+C (Control + Awesome + Comment) and bam, you got that neat little structure.
Next, I want someone to create a documentation creating tool that supports markdown and that little sweet commenting structure.
I also expect people to get angry, and virally boom with their anger for developers that don’t comment well and for management that pushes developers not to spend their time commenting!