Login   Register  
PHP Classes
elePHPant
Icontem

why not just all?

Recommend this page to a friend!
Stumble It! Stumble It! Bookmark in del.icio.us Bookmark in del.icio.us

      PHP OAuth API  >  PHP OAuth API package blog  >  Moving OAuth Server C...  >  All threads  >  why not just all?  >  (Un) Subscribe thread alerts  
Subject:why not just all?
Summary:data separated from code should be a must
Messages:7
Author:Daniele Cruciani
Date:2014-02-04 07:08:34
Update:2014-02-04 09:15:17
 

  1. why not just all?   Reply  
Picture of Daniele Cruciani
Daniele Cruciani
2014-02-04 07:08:34
I can guess there are part that have to be elaborated, or conceptualizated, but i think there are no priority, neither performance drawback on moving data to a conf file

  2. Re: why not just all?   Reply  
Picture of Manuel Lemos
Manuel Lemos
2014-02-04 07:30:04 - In reply to message 1 from Daniele Cruciani
Yes, ideally I agree. The point is that many people using this class are not experienced developers and sometimes they get lost in simple details that prevent them to use the class.

For instance, this class requires the HTTP class. That is written in this package page, it is written in the download page, but less experienced users were not noticing it. They expect something that is self-contained and works by itself.

So, if now I move all the server definitions to a separate file, some of them will start complaining that the class started giving errors just because they did not realize they needed an extra configuration file.

That is why I intend to keep the definition of the most popular servers inside the class. Hopefully that will avoid more needless support requests.

  3. Re: why not just all?   Reply  
Picture of Daniele Cruciani
Daniele Cruciani
2014-02-04 08:16:09 - In reply to message 2 from Manuel Lemos
I am using your class and I am almost enthusiast, I am part of the class of people who had problem because of missing dependecies, but really what make me crazy was the absurdely detailed documentation in the source file, instead of make me understand the purpose of each method the long paragraph of documentation deny me from understand what damn the class does. Well, I removed all doc strings, and tried to guess what was the problem adding some print ... it was my plan but then I see new http and catched the dependency.

Lot of example is very good, but that ipertrophic documentation make code unreadable. Well, this is OT, but would suggest to add a line in comment, yes add, to say: run the script at http:.... to remove all document, that would be invaluable.

Instead it would be very clean 2 lines at begin of code that say:
/* replace the following requirement according to your code: */
require_once "http.php";
require_once "services-def.json";

I understand the documentation need but there is a trade off when it is too long

  4. Re: why not just all?   Reply  
Picture of Manuel Lemos
Manuel Lemos
2014-02-04 08:26:43 - In reply to message 3 from Daniele Cruciani
Well, the documentation is in a separate file but it is extracted from the main class source so it is always in pair with the documentation. Still the documentation in the class file is inside comments, so it does not get in the way of the class code.

If people are checking the source code to understand the class, that is because the documentation failed.

Still many people did not get the habit of checking the documentation first. So the dependencies problem was solved by putting a comment in the examples of where to get the http.php file.

Unfortunately PHP did not start with a package installer standard. Now there is composer. It installs packages and dependencies. Both packages are in PHPClasses composer repository but very few people use composer.

  5. Re: why not just all?   Reply  
Picture of Daniele Cruciani
Daniele Cruciani
2014-02-04 08:45:30 - In reply to message 4 from Manuel Lemos
I read about the composer, maybe a good idea, but the reality is that one need just a class, and include composer could be not viable.

Also I work with code, not with documentation, readibily is a valuable characteristic of the code. But I understand that this matter could be arguable and sensitive.

Back to the propose, given the win of documentation over the code, if people read and understand documentation, if documentation does not fail, then they would understand that configuration file is needed.

(my hint is: no one would read that annoying documentation, we are hacker and we want to read schemas, diagrams, use cases, and ... code, not annoying words)

  6. Re: why not just all?   Reply  
Picture of Daniele Cruciani
Daniele Cruciani
2014-02-04 08:48:01 - In reply to message 5 from Daniele Cruciani
That said, I favor your propose to divide configuration in a separate file.

  7. Re: why not just all?   Reply  
Picture of Manuel Lemos
Manuel Lemos
2014-02-04 09:15:17 - In reply to message 5 from Daniele Cruciani
If you do not intend to change the class to make it better somehow, you should not be reading the code to understand how it works.

OAuth is so complicated that you will hardly can understand the class just looking at the code. That is why I wrote previous articles to complement the documentation.

Anyway, if you want to hack the class, as I said the documentation is inside comments. A good text editor can color the documents in a different way and even fold the comments so they do not get in the way of reading the code.