| Re: Major trouble with PhpDocumentor [message #182318 is a reply to message #182316] |
Sun, 28 July 2013 12:05   |
Jerry Stuckle
Messages: 2598
Registered: September 2010
Karma:
|
Senior Member |
|
|
On 7/28/2013 12:04 AM, Fiver wrote:
> On 2013-07-28 04:59, Jerry Stuckle wrote:
>> On 7/27/2013 10:45 PM, Fiver wrote:
>>> On 2013-07-28 04:22, Jerry Stuckle wrote:
>>>> Personally, much of my code is documented before any code is written
>>>> (it's called a "design"). It may or may not be a complete design,
>>>> depending on the complexity of the project. But the rough outlines are
>>>> there. Then I add any additional details as I go along.
>>>
>>> Okay, but what do you use to process your inline documentation?
>>> Design, documentation and tests first is a nice principle, but I've
>>> never seen a (non-trivial) project go from design to production without
>>> significant changes. Having to maintain separate documentation files in
>>> parallel to the source is asking for trouble, IMHO. But to each their own.
>
>> None of my projects require *significant* changes, unless it is due to
>> changes from the client. But then I started a long time ago (when
>> flowcharts were popular) and have quite a few projects under my belt.
>> And I do *complete* designs - not just some minimal scratches on a
>> notepad. It saves me a lot of time because I write code once and am
>> done. I don't need to keep going back to change things because of
>> something I didn't consider previously.
>>
>> And no, maintaining separate documentation files is *critical* to a good
>> project. These are the documents the test group use to ensure the code
>> is written according to the documentation. It is also the first place
>> changes due to client requests or design deficiencies are applied. The
>> code is written to support the design.
>>
>> The test group doesn't even look at the code. It looks at the
>> documentation to ensure the code runs according to the spec. It's
>> harder to separate coding from testing when you do both jobs, but it can
>> be done (and becomes easier with practice).
>
> You're clearly talking about an entirely different type of documentation
> here. This sound more like a specification than what I had in mind: an
> API reference. The documents you're describing answer the question "What
> should this part do?", whereas what I'm talking about answers questions
> like "What type of parameters does this method accept?" and "What's the
> name of the method that returns a list of Foo objects?". A developer
> reference. The typical case for inline documentation.
>
Nope, part of the design also the API. It includes input parameters,
what it does, and return values. It makes for great inline developer
documentation.
> I have to admit that I'm tremendously impressed by the way your projects
> work out. No significant changes; projects don't evolve over the years;
> everything turning out as planned from the start - it sounds fantastic.
> Practically unique in the world of large-scale software development. Kudos.
>
As I said - no significant changes unless they come from the client.
When the client makes changes, those changes are applied to the
documentation first. Then you know exactly what needs to be changed in
the code.
>> And no, I doubt very much anyone here uses PHP Documentor. And if it
>> ever was the "number one documentation generator for php", it still
>> wasn't very popular. You're one of the few people I've ever heard of who
>> uses it.
>>
>> You can hang around all you want - no one's going to stop you. But
>> you're going to get better help through their support structure.
>
> I'm beginning to suspect that you're right about that, judging from the
> feedback I got so far. Nevertheless, I'll wait and see if I can get a
> reply from someone who has actually used a tool to generate
> documentation before. It's not that much of an outlandish idea.
>
I have tried tools to generate documentation. All of them have done a
poor job compared to proper design documentation.
> If you're unsure of what I mean, here are some examples (using
> PhpDocumentor/DocBlox):
>
> http://framework.zend.com/apidoc/1.11/
> http://apidocs.sugarcrm.com/api/6.7.1/pro/
> http://pear.php.net/package/Mail/docs/latest/
> http://roundcube.net/doc/phpdoc/
> http://www.agavi.org/apidocs/index.html
>
> You've probably heard of these projects before. You can find more
> examples by searching the web for "This documentation was generated by
> PhpDocumentor" or "This documentation was generated by DocBlox". If
> you're entirely new to the concept, look up JavaDoc.
>
> regards,
> 5er
>
Oh, I'm familiar with documentation generators. I'm also aware most PHP
programmers (and a lot of programmers in general) are "code and go".
They don't create designs ahead of time. As a result, they spend a lot
of time rewriting code and experimenting to try to get things to work.
Designing the system up front takes time - but not nearly as much as
trying to design around code you've already written.
I've seen the same on some large (multiple programmer) projects. I've
even had managers tell me "If my programmers aren't writing code, they
aren't being productive".
It's a lot like telling a carpenter "Build me a house" without hiring an
architect first. But programmers seem to think it's ok to waste a lot
of time.
--
==================
Remove the "x" from my email address
Jerry Stuckle
JDS Computer Training Corp.
jstucklex(at)attglobal(dot)net
==================
|
|
|
|
Calendar
Search
Help
Members
Register
Login
Home
]