Vent: Laravel source code comments

How do you really feel @davestewart ? </sarcasm>

Seriously.. if this is your biggest gripe about laravel, maybe you need to heed your own advice and spend more time with you wife / kids /et al..

I totally expect to get flamed for this. Maybe I should chill on it, but at least it's out there now and I can move on :P

Why do you care? You don't have to write them. Laravel has better documentation and source code commenting than any tool I've ever used.

It's good to vent once in awhile. I agree with all points including Jefferys.

Other docs are by far worse including small JavaScript plugins. Some time you have to go line by line to figure it out.

Yes, Laravel has "hidden gems" that are not documented except in the source code. But the basics are and a lot better then it was.

Why do I care (!) ?

Because I don't know Laravel well enough yet to not have to read the source code, amongst other things.

And before you think I'm just some whining bitch who doesn't know how much effort it is to write a framework, I do. And its documentation.

I think this is a totally valid observation, though possibly not delivered in the most diplomatically-sensitive way, or at least in a way that will encourage meaningful debate in a community I don't yet know well enough.

Some people really put way too much thought into Laravel, if folks would just use it as a shell it is and stick to the MVC pattern and not worry about all kinds of specialized classes, it would be so much easier to use.
I once did jsp, servlets, and beans, but I never tried to over think stuff, I just stuck to using it for crud and database management.
Granted I did have to come up with a few complex queries, but once you get through one, the others are much easier.

Even with "all this magic", Laravel provides an awesome learning curve, not only for the framework itself, but about all principles and methodologies he uses. Principles and methodologies that most students of courses related to software or programming are learning and are able to understand.

Instead of worrying with those things about comments, use your time to study really important things.

@davestewart you really don't need to know all of the inter workings of how the framework works, if that was true you would have to know every line of assembly language that makes an operating system work. I mean I don't know if you use Windows Mac or what but I am sure you have not studied every single line of assembly language that makes it work.
Just using and following the documentation and of course basic PHP and JavaScript you could write a complete complex web application and all without using one specialized class other than models views and controllers. So I am just saying relax and enjoy and welcome how easy Taylor made the framework.

@ricardovigatti Fanboy alert! (Ah, I see you edited your reply to remove the swearing, thanks)

kkk. sorry for that. Anyway, those things i said about Laravel are valid to many other frameworks, using PHP, Java, Ruby, etc.. So, it's not a "fanboy" thing, it's about how Laravel was able to make things easier for us, merely programmers. Try a "Laravel vs" search on Google and compare him with other PHP frameworks, you will understand.

@ricardovigatti, I don't disagree with you at all!

But I can maintain my view on the source code commenting, without being in conflict of others' opinions.

It would be super-cool if the converse was true!

When I get to a bit of code and am forced to read self-indulgent fluff like the following...

Funny, that comment seemed pretty helpful to me. It's plain English and explains a slightly cryptic line of code.

What would you suggest instead, for that example?

Perhaps a few extra lines will make it clearer:

/**
 * Delete a record from the database.
 *
 * @param  mixed  $id
 * @return int
 */
public function delete($id = null)
{
    // If an ID is passed to the method, we will set the where clause to check
    // the ID to allow developers to simply and quickly remove a single row
    // from their database without manually specifying the where clauses.
    if ( ! is_null($id)) $this->where('id', '=', $id);

    $sql = $this->grammar->compileDelete($this);

    return $this->connection->delete($sql, $this->getBindings());
}

The class is Illuminate\Database\Query\Builder, the method is delete(), the parameter is id.

This is pretty typical.

(Don't think I need to say much more)

(Don't think I need to say much more)

Well, you still haven't actually said what you would have done. Remove the comment? Write it differently? Show us your version.

A better, less distracting, comment would simply be:

// add `where` clause

But you're missing the point.

This comment satisfies all 5 points I made in the original post.

In short: this code does not need annotation; the effort required to create and coral 3 lines of verbosity into a self-documenting method could have been put in elsewhere... or simply omitted.

Anyway, now I sound pedantic!

This conversation is more about putting the info where it's needed.

Effectively, making Laravel better, believe it or not :D

Though quite happy to move on, for anyone else wishing to bring this thread back to the front page...

Look at it like this a lot of folks are brand new to Laravel and I think Taylor put in some extra comments to help a new user out, that doesn't mean comments like that actually need to be in the code you write. Many times these comments are very helpful until you learn that particular technique.

In short: this code does not need annotation; the effort required to create and coral 3 lines of verbosity into a self-documenting method could have been put in elsewhere... or simply omitted.

Okay.

Well, I prefer the code with the "verbose and unnecessary" comment. I like how it's written and I think it's helpful. To some extent it's a matter of taste.

And I really don't think this is occupying much of Taylor's time.

And I really don't think this is occupying much of Taylor's time.

I tried commenting an entire class with the 3-line thing a few months ago, and it took longer to write and re-write the comments than it did to get the class working!

The most generous position I'll adopt is "it's sub optimal".

But if it makes the framework's creator happy, I can live with that.

( Having vented, that is! :P )

I found the comment in the snippet you posted fairly helpful - horses for courses ;-) I remember Taylor being asked about the 3-line-each-shorter thing on a podcast and he said it didn't take him any time at all, it's just kind what he does naturally. I'm currently sitting with a 70,000 line long legacy PHP app with a single comment in it which is '// is this needed?' at the end of a function - so I'll take all the comments I can get ;-)

I tried commenting an entire class with the 3-line thing a few months ago, and it took longer to write and re-write the comments than it did to get the class working!

Yeah, I had a go once myself and it was ridiculous. No chance I'm ever doing that for my own code.

But as @ohffs said, somehow Taylor has the knack for it.

If you don't like it, write your own framework.

As for the layout of the comments: I think it's a funny detail, and it shows how much Taylor cares for nice looking code. So it's also a "marketing" thing I guess. (little things matter) Anyhow, nobody is forcing you to write your comments that way. And I'm certainly not doing it. But taylor stated (on the podcast) that it doesn't take him much time at all, because he is used to it. So you can hate it, but it doesn't make the framework any worse, so yeah. Why bother?

As for the content of the comments (or the comment you gave as an example in particular), it's just explaining, in plain english, what's happening below. It's saying:

"look, you can call delete() on a model instance, and we'll delete it, but if you call delete($id) on a model, it'll delete that particular row. That's what this code is doing, so there"

That's exactly what a comment is supposed to do.

It's saying: "look, you can call delete() on a model instance, and we'll delete it, but if you call delete($id) on a model, it'll delete that particular row. That's what this code is doing, so there"

@Prullenbak hilarious! It doesn't say that at all (the Query Builder doesn't know about Models) so thanks for inadvertently reinforcing my point :)

And I know this is rumbling on, and I'm genuinely sorry it's taking up so much time (seeing as no one really cares) but something else that struck me today, whilst looking at the config (which is all 3-line Comment Haikus).

Some comments are intrinsically more important that others. Generally, if something needs more explaining, it will be longer, or broken out onto a few lines. If something is not as important, it may only be a few words.

By dogmatically enforcing 3-line comments, cute as it is, that affordance is lost. It makes scanning code a less intuitive act, as each comment block has exactly the same weight. Rather than the brain being able to judge which comments may indicate "more explanation needed here!" it's all resolutely uniform.

That is a major drawback, in my opinion.

Anyway, the prevailing wind in this thread is "Laravel is brilliant; why complain?".

So consider this complaint out of steam (I'm off to write some comments of varying size and shape) :P

yeah, hilarious. I could totally see that the code came from querybuilder... [/sarcasm]

Admit it, you're making a big deal out of nothing. The comments in laravel are generally very helpful, and if you don't like the format that Taylor uses, that's fine. But it's totally not worth complaining about.

Ah, it was brought up later in the thread, thought you had seen that.

And there's nothing to admit, I've said several times that this has gotten bigger than it should have done.

I wonder if the next developer who comes to your work and says "I only write comments in the form of limericks, hope you're cool with that" how you'll feel though :P

I'd love that :-D

public function delete($id = null)
{
    // there once was an id from a user
    // for a row he wanted to lose(r)
    // he passed it in quick
    // (although he could skip)
    // and now he's gone off to the boozer! (pub, for non Brits in here)
    if ( ! is_null($id)) $this->where('id', '=', $id);

    $sql = $this->grammar->compileDelete($this);
    return $this->connection->delete($sql, $this->getBindings());
}

This is way more fun!

PR: and now he's gone off to the boozer! ;-) There's a leanpub book in the making... ;-)