Sr. Web Developer
mediabistro.com
US-NY-New York

Justtechjobs.com Post A Job | Post A Resume

Comments for: stefano20000824

Message # 1013102:
Date: 08/27/02 03:17
By: Aivar Annamaa Profile
Subject: Doc generation can become additional burden

Generated documentation saved to files is great for stable libraries. But if you need to have quick and up to date overview of some work in progress then static documentation generation is likely to introduce more hassle: "did I (or other guy) updated the documentation after that change?, need to check it".

A good solution would be live documentation, which always shows documentation for your current skripts. Yes, Pear phpdoc can be too slow for that. I haven't read phpdoc code but I don't believe its current performance is the best possible. But if this parsing needed is really so difficult, then why not to simplify doc format?

But the best solution for having quick overview of work in progress (and web apps tend to be in progress forever) is to write self documenting code and use comment documentation mostly for information which can't be easily expressed in programming language (for example the purpose of a class or function).

You should get answers to your questions while looking at the skript. This needs careful code structuring. Code and documentation needs to be organized into hierachical layers, for example: program (ie. directory) --> subsystem (directory) --> class (file) --> public methods --> private methods and helper classes. Having such structure would allow easily to find needed info. Remember the performance difference between searching form trees and searching from arrays? Having poorly structured code would result searching from array of functions or even from array of source lines.

I don't propose to pay little attention to comments (non-code documentation), to the contrary: In every directory, there should be a document with information about context and purpose of skripts in this directory. Every script file should have in its beginning a short overview of its purpose, how it's related with other scripts. If there is one class per file this goes to class description. Every public method of class should have about same kind of description.

So, comments are important but the key is to avoid redundancy which can lead to incompatibilities between what's said and what is. Don't describe lower level items in higher level documentation, because the lower level items can change. For example, don't list files in directory document, your file browser lists them for you. Another example: often algorithm steps and rules of a public method are described in documentation. You don't need this if the method is clean and short (difficult things delegated to helper functions with meaningful names), you can look up outline of the algorithm from code. And if you need more details, you can always dive deeper. With separate documentation you hawe two places to search for info and two places to update if you change some rules in the algorithm.

Try to keep the top layers of your code as readable as separate documentation would be. Code never lies but documentation often does. Separating documentation from code can reduce its reliability.

Although I mentioned classes, the same principles apply to structured programming.

Once again, the thoughts above apply mostly to custom program code, which is changed often.

Previous Message | Next Message


Comments:
RE: Too many PHPDocs...Nightowl03/19/03 06:15
phpDocGen: simple and reliable doc generatorwiart10/11/02 04:19
Orcale Connectivity problemFaisal Abbas10/02/02 00:03
apostrophe'sjohn's09/26/02 15:48
doxygenmatej hron09/02/02 12:26
Doc generation can become additional burdenAivar Annamaa08/27/02 03:17
Too many PHPDocs...Luiz Rocha07/15/02 11:16
RE: The best automatic PHP Documentor (NO!)Shanx07/04/02 01:10
phpDocumentor 1.1.0rc2 releasedGreg Beaver06/18/02 12:10
PHPDocumentor 1.0.0 STABLE releasedGreg Beaver05/25/02 13:15
The best automatic PHP DocumentorGreg Beaver05/07/02 03:10
RE: PHPDoc v.2.3.5 releasedBrandon Blackmoor04/28/02 19:01
PHPDoc in PEARTim Gallagher04/05/02 19:52
Php how toMahmood Neshati02/24/02 04:44
Media player control in PHP:Jes02/22/02 08:44
a student admire the authortuan02/03/02 08:45
RE: how to starting the PHP sourceGHAN01/29/02 11:29
WINDOWSJason11/16/01 06:18
Windows98Malcolm Clark09/08/01 04:02
RE: Yet more choiceguibod09/03/01 00:33
RE: PHPDoc v.2.3.5 releasedAndy Chapman07/18/01 01:41
PHPDoc v.2.3.5 releasedChristian Calloway06/14/01 08:12
RE: phpdoc v.2.0jose04/08/01 05:41
cannot reterieve image on web pagevishal03/27/01 06:49
Yet more choiceGeoff Caplan03/16/01 15:40
RE: phpdoc v.2.0Shashank Tripathi03/13/01 01:48
phpdoc v.2.0christian calloway02/08/01 14:27
Try www.phpdoc.deTim Strehle11/29/00 16:38
var tab errorsAaron Oathout11/28/00 14:10
yet another choicechristian10/23/00 23:48
Another ChoiceJoshua Eichorn09/13/00 03:23
RE: no need to compile docs..Stefano Locati09/03/00 04:55
RE: Multiple @class elements?Stefano Locati09/03/00 03:58
RE: Multiple @class elements?Frederic De Leersnijder09/02/00 10:02
Multiple @class elements?Frederic De Leersnijder09/02/00 10:01
Multiple @class elements?Frederic De Leersnijder09/02/00 09:30
shambalaMarek Dlugozima09/01/00 14:28
Thanks!Yamilo08/30/00 11:33
Excellent Article !!Ikke Pe Ikka08/29/00 23:11
no need to compile docs..Keith08/28/00 22:46
install for beginnersLen08/28/00 20:55
RE: Good StuffJeff McDonald08/26/00 22:15
Good StuffJeff McDonald08/26/00 22:14
 

If you are looking for help, please post on the appropriate forum here. Your questions will be answered much more quickly.

Add A Comment:

Name:

Email:

Subject:

Message:

To reduce spam posts, messages are now manually approved

You are not [logged in]. That means your account will not get credit for this post.