Internal Documentation Preferences

Not for 'how-to' coding questions but PHP theory instead, this forum is here for those of us who wish to learn about design aspects of programming with PHP.

Moderator: General Moderators

Post Reply
User avatar
VirtuosiMedia
Forum Contributor
Posts: 133
Joined: Thu Jun 12, 2008 6:16 pm

Internal Documentation Preferences

Post by VirtuosiMedia »

I know discussion on the topic may be subjective, but I'm curious as to what everyone feels is sufficient internal documentation for coding. For you personally, how much is too much and how much is too little? What kind of things do you provide commentary for in your own code? When you look at other people's code, what drives you crazy?
alex.barylski
DevNet Evangelist
Posts: 6267
Joined: Tue Dec 21, 2004 5:00 pm
Location: Winnipeg

Re: Internal Documentation Preferences

Post by alex.barylski »

Old habits die hard. When I programmed in C/C++ I used comments extensively, also favouring Hungarian notation and other such conventions.

Then I started to learn assembler and learned (through osmosis) that commenting things like:

Initialize variable to value ZERO

Eventually I started commenting more than I wrote code, I was over zealous some might say. :)

These days I don't comment at all, unless I have performed a hack or I leave behind a TODO note.

For example, I found this in my code just today:

Code: Select all

// TODO: Make sure to check result of $total
I also found this:

Code: Select all

// HACK: Make sure to refactor inline INI code into some external profile class
If code is to complex to figure by just reading it, it is usually a sign your solution is to complex, especially in the context of PHP. Although I do occasionally comment some algorithms/implementations if they rely on a system caveat or hack. I will typically leave bhind a few lines such as this:

Code: Select all

/**
  NOTE: The following loop is difficult to change because of the concrete dependecy on object X, Y, Z which also rely on each other   explicitly. If we change one, the others will be affected. Any changes made here should be made with upmost caution and interest in related objects.
*/
I am thinking I should maybe start to document my model's if anything, so as to avoid having to find the object in question and just look up some docs. Although I would prefer to use a auto-doc generator like Doxygen or phpDocumentor for that one, as all I'm looking for is the API and arguments really, not a detailed description.

What drives me crazy about others code is the complexity. Personally I prefer many simple objetcs described in a document pre-joining a project. I find most projects are lesser but more complex objects with too much or too little comments describing how the system works.
User avatar
Eran
DevNet Master
Posts: 3549
Joined: Fri Jan 18, 2008 12:36 am
Location: Israel, ME

Re: Internal Documentation Preferences

Post by Eran »

I use phpDoc style exclusively. For each class I add a general description and some tags like authoer, package, license if relevant. I document methods by providing a short description and a recap of optional parameters if they exist. I add type declaration for methods parameters and return.

Zend Studio makes my life much easier as it can generate most of the content from the method declaration. I just need to add the description
User avatar
Ollie Saunders
DevNet Master
Posts: 3179
Joined: Tue May 24, 2005 6:01 pm
Location: UK

Re: Internal Documentation Preferences

Post by Ollie Saunders »

I make sure to write my code well enough so that it doesn't need a comment to understand what it's doing. If I'm writing an API/library of some sort I'll write comments on top of the majority of methods and classes in addition to this.
User avatar
onion2k
Jedi Mod
Posts: 5263
Joined: Tue Dec 21, 2004 5:03 pm
Location: usrlab.com

Re: Internal Documentation Preferences

Post by onion2k »

I recently started learning phpDoc so I can document PHPImage in a standardised way. It seems pretty decent. The only problem is that I really, really don't enjoy writing documentation, even the little bit that phpDoc needs. It's a necessary evil I guess.
koen.h
Forum Contributor
Posts: 268
Joined: Sat May 03, 2008 8:43 am

Re: Internal Documentation Preferences

Post by koen.h »

phpdoc for me.

-Works well with editors like Zend Studio. Actually that's how I first got into it. They wanted me to use it because Zend Studion used it to aid in autocompletes and argument hints etc. As if that is what commenting is all about. But it is a benefit.
-Can be regarded as a standard. Others will benefit from the standards approach and you'll benefit if they use the same.
-Create phpdoc with it (though I haven't found much use for those phpdoc generated pages).
User avatar
Ollie Saunders
DevNet Master
Posts: 3179
Joined: Tue May 24, 2005 6:01 pm
Location: UK

Re: Internal Documentation Preferences

Post by Ollie Saunders »

(though I haven't found much use for those phpdoc generated pages)
Yes, I find all of them almost uniformly useless.
Post Reply