PHP Classes

Description

Recommend this page to a friend!

      PHP Classes blog  >  More Exposure to Inno...  >  All threads  >  Description  >  (Un) Subscribe thread alerts  
Subject:Description
Summary:The description is rewritten from scratch
Messages:4
Author:Dan Negrea
Date:2011-10-26 19:55:54
Update:2011-10-27 00:49:03
 

  1. Description   Reply   Report abuse  
Picture of Dan Negrea Dan Negrea - 2011-10-26 21:19:16
The description is rewritten from scratch based on the reviewer understanding. It's a good approach, but you must consider that the author of that class has spend maybe an hour, maybe more creating a description - he doesn't do this often :)

The solution would be to insert at the bottom of the rewritten description something like: Author description (one, two sentences).


  2. Re: Description   Reply   Report abuse  
Picture of Manuel Lemos Manuel Lemos - 2011-10-26 21:34:46 - In reply to message 1 from Dan Negrea
That would be often redundant and confusing for the user.

The only case where the original description is kept is when it is not in English and the class does something specific for some country.

In most cases the descriptions entered by the author are not objective. Often they contain hype and big claims about what the class does, or do not tell what the class does in enough detail, and that is not helpful for the user because he the user needs to figure if the class is useful without looking at the code and often the original description of the author does not allow that.

For authors that want to keep their original descriptions for some reason, they are free to add read me files to the packages so what they want to pass to the user is preserved.

  3. Re: Description   Reply   Report abuse  
Picture of Dan Negrea Dan Negrea - 2011-10-26 23:59:44 - In reply to message 2 from Manuel Lemos
I will give you an example of a sentence that can mean a lot. But first let's see how the description of my class appears:

"This class implements CAPTCHA validation using RetinaPost service.

It generates HTML to display challenge that they must respond to demonstrate they are real human users using the RetinaPost service.

The class can also send an HTTP request to the RetinaPost API Web server to verify whether the user response for the given challenge is correct."

The above is absolutely correct description but doesn't say all.
Add this:

"It works based on text taken from a feed or a custom message that will appear inside the challenge displayed to the user".

No big words. Just some details for those who don't want to open the API to learn more.


  4. Re: Description   Reply   Report abuse  
Picture of Manuel Lemos Manuel Lemos - 2011-10-27 00:49:03 - In reply to message 3 from Dan Negrea
If you feel that a class was approved with a description that needs to be improved somehow, you can always edit the description. Your description changes will be moderated and if they make the description better they will be approved.