On the Symfony blog they've posted an update about recent advancements in their diversity initiative. They share a few different updates, resources and changes that have been made to help improve the overall diversity of the community around this popular framework.

Updates included in the post cover:

• Respectful Review Comments (a guide on writing them)
• Mentorship program
• Code of conduct and enforcement process
• Context and Slack discussions
• New slack channels

The post ends with a few "final words" from Lukas Kahwe Smith about another initiative that's been started to help improve the representation from specific groups in the Symfony community and ecosystem.

Dylan Bridgman has posted a few helpful tips on writing code that's "highly readable" and easier for both developers inside and outside the project to understand.

We are always told that commenting our code is important. Without comments other developers will not be able to understand what we did and our future selves will recoil in horror when doing maintenance. Readable code, however, is not only about comment text. More importantly it is about the style, structure and naming. If you get into the habit of writing easily readable code, you will actually find yourself writing less comments.

He breaks it up into a few different categories to keep in mind as you're writing your code:

• the overall style of the code
• the structure of the application (directories, libraries used, etc)
• naming conventions for variables, methods and classes

Finally, he talks about comments and how they should fit into the ideas of readable code. He suggests that they should stay as high level as possible and explain the intent of the code, not what the code is doing (yes, there's a difference).

On the /r/php subreddit frm Reddit.com, phpdevster proposes an interesting opinion - that an event system, set up with a listener and defined events, has become more of an anti-pattern in its most common implementation.

If events are only meant to be additional functionality that ALWAYS ALWAY ALWAYS should happen after a primary action is taken, how often is code really that absolute? Why are events not implemented in more flexible ways by frameworks? - that is implementing some inversion of control which would allow callers to determine which listeners would be relevant to the given context.

He illustrates his point with an example user registration system that fires a "user-was-registered" event that, in turn, fires off a series of events via a listener. He points out a pretty large flaw, though. While the functionality involved in the event is decoupled (the event itself), the behaviors defined by that event are not. Comments on the post offer some different options and solutions to the same problem including:

• Further decoupling of the eventing process
• Using objects with settable properties rather than just event name strings
• The idea of using an "event store" to handle decoupling rather than more immediate code-based solutions

Have some thoughts of your own on events and decoupling? Go over and share them too.

If you've ever looked at your code an wondered about its commenting, if there was a kind of "best practice" to follow when it comes to its structure, you should read this article from Andrew Podner about docblocks.

The subject is how to properly document code with PHP comments and docblocks. This one took a while for me to really just accept as a part of the development process. To me now, the comments are now just as much a part of the application as the code is. I believe it is that important. With IDE’s today, there really is no reason not to have good documentation in your source code.

He talks some about his own reluctance at first to use comments and how it helped him remember what his thought process was behind parts of this code. He includes an example of a typical docblock structure, showing the general description, parameters and a "return" value. He also includes something interesting in the topic of documentation - good variable names. There's links included to two tools that can take these standardized comments from your code and build HTML documentation from it - phpDocumentor and ApiGen.

You can find out more about the PHP docblock standards from this site.

In this new post to his site Vinícius Krolow shares some tips he thinks will help to make your PHP code more readable in the long run.

What about code readability, from my point of view is one of the most important thing in the code. Who writes code that is easy to read, writes good code. Probably reading code is where you spent most part of your time, and not only your code, probably code of your team mates, or maybe code from the open source community, so write code that is simple and is easy to understand it’s really important.

His tips (seven of them) are:

• Comment before write your code (DocBlock)
• Return frequently, Return early
• Break, Continue
• Code Standard / Name conventions
• Throw Exception
• Comment often, but not write stupid comments
• Methods can be always smaller than they are

It's a little difficult to read as the English isn't the speaker's native tongue, but it gets the point across. He also recommends reading this if you'd like more information about writing better OOP code that's easier to read.

In his latest post Jake Bell talks about why he thinks annotations in PHP are a bad idea (not the concept of them, but how developers are currently using them. He's in favor of officil support though).

Both the Symfony 2 and Doctrine 2 libraries and components make liberal use of what have come to be called annotations - special code comments, usually prefixed with an @ that are actually interpreted by the application and affect its functionality. [...] This trend needs to die.

He points out that the use of code comments like this isn't a good practice and applications should never have to rely on them for functionality. He mentions issues with syntax/language functionality (can't use "php -l" on them, can't var_dump an annotation) and that it makes it more difficult to read and interpret the code. He includes an example from Ruby of an alternative and a possible solution in PHP involving a static "mapping" variable.

Matt Frost has posted a few of this thoughts about effective code commenting and how it can help make your application easier to follow and maintain in the long run.

Code comments are strange things; they can be invaluable or they can make the code they're describing more confusing. They can be necessary, unnecessary, explanatory or muddled and some times they're neither; they just are. [...] Code comments have their place, don't get me wrong; but I don't usually come across good comments.

He talks some about the two cases for comments - when to use them (and do it effectively) and when not to use them (yes, there's a time for this too). He notes that, sometimes, if you feel like you need to comment excessively on your code, you might be doing it wrong - that there's a simpler, more understandable way.

The goal should always be to add value to a codebase, whether than be in the form of code, comments or documentation. Bad comments are just as bad as poorly written code and good comments can take poorly written code and make it more easily understandable.

In this discussion on Reddit, there's talk about the user comments feature on the PHP.net site and the value they provide to the language and community.

The question, however, has always been "how useful is this feature really and does it bring more harm than good?". It's not that easy to answer since there are so many notes submitted by a wide range of users and some will likely go unnoticed while others seem to get undue attention due to their positioning near the top of the user-notes section of a particularly trafficked page.

The poster proposes a few things that could help make them a bit more effective (and useful overall) including voting on the note contents, flagging potential issues and sorting the notes based on popularity/age. He's put together a proof of concept as seen here with some of the new features.

On the Programmers Community Blog there's a post (with quite a bit of feedback) that lists twenty controversial opinions about programming and programmers in general that have been proposed over the years.

One of the very first ideas we had for this blog was to convert some of the wonderful gems of the early era of our site, the undisciplined period, to blog posts. Questions that were once enthusiastically received by the community, but no longer fit Programmer’s scope.

The post has the top twenty answers to the "What’s your most controversial programming opinion?" question as proposed on StackOverflow and includes things like:

• Programmers who don’t code in their spare time for fun will never become as good as those that do.
• The only "best practice" you should be using all the time is “Use Your Brain".
• Not all programmers are created equal.
• If you only know one language, no matter how well you know it, you’re not a great programmer.
• Your job is to put yourself out of work.
• Readability is the most important aspect of your code.

Check out the full post for the complete list...and for the 100+ comments that have been added to it by programmers with both agreeable and disagreeable opinions.

In this new post Antonin Januska shares some reminders about what good code comments should look like - what needs to go in and what needs to stay out (you comment all your code, right?)

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.

There's two topics he touches on that (surprisingly) it's easy for developers to forget when writing their code - "be informative" and "use consistent formatting". A lot of the issues could be helped if developers made more use of DocBlock formatting which many IDEs already have support for.