News Feed
Sections




News Archive
feed this:

Looking for more information on how to do PHP the right way? Check out PHP: The Right Way

Allan MacGregor:
Working with Psysh
April 14, 2014 @ 09:24:34

Allan MacGregor introduces you to Psych in his latest post today. Psysh is a runtime developer console, interactive debugger and REPL for PHP.

Psysh is actually more than a simple REPL it's also an interactive debugger; which means you can say goodbye to the endless barrage of var_dump() and die() statements. But do we really need another REPL for PHP, well honestly we could probably get by with the solutions currently available however Psysh has an extremely interesting Ace under the sleeve, it can also function as a realtime debugger.

He includes a few terminalcasts showing some of the commands Psysh offers from the expected output of variable value out to a handy link to the PHP documentation. An example of the useful object output is also included, enabling the showing of methods and properties.

0 comments voice your opinion now!
psysh repl debugger console documentation debugger

Link: http://coderoncode.com/2014/04/03/working-with-psysh.html

SitePoint PHP Blog:
Keeping Your PHP Code Well Documented
February 19, 2014 @ 10:15:19

The SitePoint PHP blog has a new post by Jacek Barecki talking about documenting your code and some suggestions for keeping this documentation useful.

Pretty much every PHP developer writes comments along with the actual code. But the language itself doesn't impose any rules on how to do so. You just have to wrap them around some specific tags and then you can write any content you want. So what exactly should be put in the comment blocks to keep them useful? Which parts of the code should be documented and which shouldn't? In this article I will present some important rules which may help you in keeping your PHP code well documented and understandable.

There's three suggestions included in the article, each with a bit of explanation and a few screenshots to illustrate:

  • Write code that explains itself
  • Keep the balance
  • Remember about the doc blocks
0 comments voice your opinion now!
documentation understandable useful tips tutorial

Link: http://www.sitepoint.com/keeping-php-code-well-documented/

SoftLayer Blog:
Four Rules for Better Code Documentation
September 24, 2013 @ 12:07:56

On the SoftLayer blog today there's a new post with some recommendations for better code documentation - four tips to help make things clearer and cleaner.

Last month, Jeremy shared some valuable information regarding technical debt on SLDN. In his post, he discussed how omitting pertinent information when you're developing for a project can cause more work to build up in the future. One of the most common areas developers overlook when it comes to technical debt is documentation. This oversight comes in two forms: A complete omission of any documentation and inadequate information when documentation does exist. Simply documenting the functionality of your code is a great start, but the best way to close the information gap and avoid technical debt that stems from documentation (or lack thereof) is to follow four simple rules.

Their four recommendations cover several aspects of documentation:

  • Know Your Audience
  • Be Consistent - Terminology
  • Forget What You Know About Your Code...But Only Temporarily
  • Peer Review

They've also provided some examples of what they're talking about with PHPDocumentor-formatted comments.

0 comments voice your opinion now!
code documentation rules suggestion phpdocumentor phpdoc

Link: http://blog.softlayer.com/2013/four-rules-for-better-code-documentation

Community News:
phpDocumentor2 Celebrates their (Stable) Version 2.0 Release
August 09, 2013 @ 12:04:35

As is mentioned in this new post to the project's releases, Mike van Riel and the contributors to the phpDocumentor2 project have released version 2.0 - the first stable release!

We have spent the past two months fixing bugs, adding tests and writing a brand new template. With this release it is now easier than ever to generate your documentation. And as a special party gift we bring you a brand new template, called Clean. Can't wait to see what it looks like? Then come over and see the demo.

He talks about some of the things yet to come for phpDocumentor including more features based on the PHPDoc standard, improving performance and making the existing systems (and templates) more robust and usable. You can find the full roadmap here. phpDocumentor is one of the most widely used PHP-based tools for generating automated documentation from docblocks already in your code.

0 comments voice your opinion now!
phpdocumentor documentation automated stable release

Link: https://github.com/phpDocumentor/phpDocumentor2/releases/tag/v2.0.0

PHPClasses.org:
Lately in PHP, Episode 35 - Better Documentation for PHP internals
May 09, 2013 @ 09:12:10

On PHPClasses.org today they've posted the latest episode of their "Lately in PHP" podcast series - Episode #35, "Better Documentation for PHP internals".

With the inclusion of Zend Optimizer+ extension in PHP 5.5, the need for better documentation of PHP internals became more evident, so PHP contributors can write extensions that take the most of the core PHP features. That is one of the topics discussed by Manuel Lemos and Ernani Joppert in the episode 35 of the Lately In PHP podcast. They also talked about having more optimized PHP opcodes, some interesting PHP feature proposals that got rejected, as well the article about the top version control systems used by PHP developers.

You can listen to this episode in a few different ways - either through the in-page player, by downloading the mp3 or by watching the video of the recorded Google Hangout session.

0 comments voice your opinion now!
better documentation internals latelyinphp podcast phpclasses

Link: http://www.phpclasses.org/blog/post/207-Better-Documentation-for-PHP-internals--Lately-in-PHP-podcast-episode-35.html

Francesca Krihely:
On the Developer Experience
May 03, 2013 @ 09:22:07

In a new post to her site Francesca Krihely starts looking at the developer experience - how developers relate to your service and product and what kinds of things you need to be doing to help engage them.

I had a great brainstorm a few weeks back with the members of the Developer Evangelists meetup on the topic of the User Journey, or as I'll call it now, the Developer Experience. The main problem we wanted to solve was how we convert new users into experts or awesoms users. In many ways, a Community Manager and/or Developer Evangelist is responsible for driving user adoption and making users successful, so this is a topic near and dear to all of our hearts. I walked away with three key things that help improve the developer experience: Great Product, Great Support and Empowerment.

This post talks about the first point - the "great product" - and notes that, if the product isn't useful and enjoyable to use, even developers won't bother with it. She also talks some about the need for quality documentation and how it can be seen as a sort of "marketing" to developers.

Work on making your product fit for an awesome developer experience. If you build it, they will come.
0 comments voice your opinion now!
developer experience product support empowerment documentation marketing

Link: http://francescak.me/blog/2013/05/02/on-the-developer-experience

Zend Framework Blog:
Help us improve the documentation!
March 29, 2013 @ 11:07:53

On the Zend Framework blog they're asking for your help with the project's documentation. They're looking to the users and community members around the framework to help them make the documentation more useful and stay up to date.

A piece of software is only as good as its documentation. The Zend Framework team and a dozen or so contributors are working hard to improve the Zend Framework 2 documentation, but we still want you to help us improve it even more. Any kind of help is welcome and greatly appreciated.

Most of what they're looking for is clarity - they want to ensure that what's in the manual makes sense (and is correct for the release it relates to). They're also looking for feedback on what helps you learn best - tutorials, user guides, API docs, etc. Issues and suggestions should be posted to the issue tracker in github. If you're not sure where to start, check out the contributors guide.

0 comments voice your opinion now!
improve documentation help zendframwork github


Symfony Blog:
Symfony Docs Hack Day Needs You on March 30th
March 21, 2013 @ 12:05:19

On the Symfony blog there's a post from Ryan Weaver about an upcoming event the project is hosting and how you can help - the Symfony Docs Hack Day (on March 30th).

The first commit to the Symfony documentation was over 3 years ago, and since then, we've grown to include a full book, lots of cookbook entries, and sections for most of the individual components. [...] But as we grow, we want to stay aggressive and continue to improve the quality of the docs. This means ensuring that code examples are accurate and pages are easy to understand, balancing the info you need with excess technical clutter. [...] And this is where we need your help! Whether you're a seasoned-Symfony veteran, a beginner, or even if you don't think your English is very good, we'd like you to join us on March 30th for our first ever Symfony Docs Hack Day.

The event is a virtual one - everyone will meet up on the Freenode IRC network in the #symfony-docs channel on March 30th from 9am through 5pm Central EU time. Everyone's invited, not just those who are experts in the framework. Documentation updates are a great way to learn more about a framework too! If you're interested in what kind of updates they're looking for, check out this list of open issues with the docs on Github.

0 comments voice your opinion now!
symfony documentation hackday irc freenode update


Scott Mattocks:
D is for Documentation
March 04, 2013 @ 09:30:16

Scott Mattocks has wrapped up his series about LUCID development with the final letter of the acronym - D is for Documentation.

Despite mankind's best efforts, writing code is still clearly an exercise for talking to computers. It has not evolved to the point where talking to a computer is as easy and natural as talking to other people. That's why documentation is so important. Programming languages are just a translation of a developer's intent into something a computer can execute.

He points out that even a little documentation can go a long way (even in presentations with code in the slides). It provides context and the intent of the code, not just details about what it's doing. He proposes a compliment practice to test-driven development (TDD) that turns the documentation process around - Documentation Driven Development. This is essentially writing up what the code does first, then writing tests to check it and only then writing the code to make it happen.

If you're interested in the rest of the articles in the series, check out the LUCID article on his site with links to each letter's article.

0 comments voice your opinion now!
lucid development principles documentation tdd


Matthew Weier O'Phinney:
RESTful APIs with ZF2, Part 3
February 25, 2013 @ 12:21:30

Matthew Weier O'Phinney has posted the third part of his series about making RESTful APIs with Zend Framework 2 (parts one and two). In this latest part of the series, he talks more about documenting the API and what commands can be executed.

In this post, I'll be covering documenting your API -- techniques you can use to indicate what HTTP operations are allowed, as well as convey the full documentation on what endpoints are available, what they accept, and what you can expect them to return. [...] hy Document? If you're asking this question, you've either never consumed software, or your software is perfect and self-documenting. I frankly don't believe either one.

He covers a few reasons why you should document your API and where he thinks it should live to be the most useful. He includes a few different ideas and two things he definitely thinks should exist for your API - the use of OPTIONS and end-user documentation. The first is a HTTP header (ZF2 code example included) that tells the API consumer what they can do with an endpoint. The second type is more useful for the human reader, giving them a better overall perspective on what the API can do - still served through the API but in a bit more understandable format.

0 comments voice your opinion now!
zendframework2 rest api tutorial series documentation options enduser



Community Events





Don't see your event here?
Let us know!


framework install series laravel bugfix unittest community podcast library release interview introduction zendserver language tips package opinion api symfony deployment

All content copyright, 2014 PHPDeveloper.org :: info@phpdeveloper.org - Powered by the Solar PHP Framework