Page 1 of 1
Internal Documentation Preferences
Posted: Tue Jun 24, 2008 6:08 pm
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?
Re: Internal Documentation Preferences
Posted: Tue Jun 24, 2008 7:30 pm
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.
Re: Internal Documentation Preferences
Posted: Tue Jun 24, 2008 7:45 pm
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
Re: Internal Documentation Preferences
Posted: Tue Jul 01, 2008 1:05 am
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.
Re: Internal Documentation Preferences
Posted: Tue Jul 01, 2008 2:20 am
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.
Re: Internal Documentation Preferences
Posted: Tue Jul 01, 2008 1:09 pm
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).
Re: Internal Documentation Preferences
Posted: Tue Jul 01, 2008 1:19 pm
by Ollie Saunders
(though I haven't found much use for those phpdoc generated pages)
Yes, I find all of them almost uniformly useless.