Of course I'm going to write something about the new Symfony Best Practices book that was written by Fabien Potencier, Ryan Weaver and Javier Eguiluz. It got a lot of negative responses, at least in my Twitter feed, and I think it's a good idea to read Richard Miller's post for some suggestions on how to deal with an "early preview release" like this and how we can be a bit more positive about it.

Staying positive

One of the most important things we have to keep in mind: you don't have to agree with everything in this document. There are so many different ideas about "how to do things best", it would have been impossible to write a set of best practices everyone agrees upon.

As you can imagine (if you read my blog posts or have seen my presentations), I myself don't think many of the practices in the book could be described as "best". But then again, what is "best", and what is the type of project and/or team you have in mind when you decide that they are "best"? So, I really don't care about the document in this way. What the Symfony team thinks is best, they are allowed to label as "best".

But

But, and this is one huge "but": the way they introduced this book was very unfortunate (emphasis mine):

[...] community resources - like blog posts or presentations - have created an unofficial set of recommendations for developing Symfony applications. Unfortunately, a lot of these recommendations are in fact wrong.

To say such a thing in an official text is such a bad move, I don't understand why none of the reviewers has been able to convince the authors to remove this particular paragraph. Still, it is apparently such an important phrase, that not only is it part of the book itself, it is also being quoted in the article that first introduced the book.

You know, I have invested countless hours into working with Symfony, finding out how some parts of it work, writing about it (the Security Component documentation, Cookbook articles, 90 blog posts), talking about it in public, preaching Symfony to my team members and employers, finding new and better ways to do things with Symfony, and so on and so on.

Now I have always known that what I think is good, probably is not what Fabien thinks is good. But still, to actually read this in a public, official document - "a lot of these recommendations are in fact wrong" - well, that is just something that's very hard to process.

It is totally not necessary to write such a thing. It is a very mean thing to say to a community at large. It makes the authors look like old-fashioned managers, walking by the desks of their personnel, saying "you're wasting your time there, buddy", "you know, traditionally, Symfony developers used to do that, but we know better now" and "you are over-complicating things, get out!"

Let's not get all emotional

I totally agree with Richard Miller as he correctly states:

However, I do see no reason not to remove some of the more emotional and inflammatory language as soon as possible.

And, yes, I have to admit, I just used a bit of emotional and inflammatory language myself. But this article is not an official recommendation. It is a personal, opinionated blog post, so I feel totally entitled to do so.

Recommendations

To me the introductory paragraph and several other parts of the text communicate the message that "you're doing it wrong". It didn't have to be that way! It could have just been like, "you know, we think, this is the right way". So my first recommendation to the authors would be: change the text to reflect this community-friendly attitude. Even if the motivation to write the book was the "wrongness" of the approaches suggested by community authors like me, you should definitely hide that motivation, since it doesn't do any good to your relation with the community.

In general, there is no need for a best practices book like this to be opposed to anything really. It's not necessary to point out "mistakes" made be community people. And it only causes negative feelings in the reader's mind if they have to read about "things Symfony developers traditionally do", while they actually do those things, and don't know what would be "wrong" about that. Finally, it makes no sense to label a common approach as "overcomplicating things" or "over-kill". So just provide a list of the best practices and don't mention all the things you find a bad practice.

Good luck

At the end of this post, you may still call me a Symfony developer. I really hope the authors of this book will take my complaints seriously. Then I think that this book will have a long and prosper future and will serve as a good book for people to get started with the Symfony framework. When you've finished it, I recommend you to read my own book, A Year With Symfony, to get some more advanced insights into Symfony and how to work with it. Afterwards, I hope you will practice your coupling radar, learn to recognize the touching points between your code and the framework of your choice, and to actually break free from it, because:

It's not your code that needs the framework, it's you. And you need a good one. So choose Symfony.