[wp-hackers] Proposal for a function commenting convention

[Jacob]

In the technical sense, comments are whitespace and compilers are built 
to quickly move over whitespace. The only drastic impact would be the 
increased file size, which would have to be loaded. This is really the 
file system issue and not that of PHP, if your file system sucks, then 
yeah, you'll probably feel something, if your server CPU also sucks.

This isn't JavaScript we are talking about here. In any case, the gains 
by having comments far outweigh the illusion of speed decrease. You show 
me a user that would actually notice the difference and I'll show you a 
host that sucks.

With any sort of opcode caching this would be a mute point since the 
file would be interpreted and compiled, in most cases, only once.

To reiterate, the bottlenecks are from file system to memory (small) and 
database queries (much larger). Parsing PHP does not even come close in 
comparsion.

Jacob Santos

Matt wrote:
> Ya... but... would documenting all (or most) of the functions make a huge
> impact on load times on the files since they'll be loaded with useless (in
> the executing sense) comments?
>
> On 10/13/07, Jacob <wordpress at santosj.name> wrote:
>   
>> Err, yeah. Have you any thoughts of how the version which functions were
>> added are going to be found? I'm not even sure the devs would know about
>> every function. You'll find that checking repository log is neat for
>> files, but doesn't really tell you much about functions. Unless of
>> course you check each repository commit.
>>
>> (After some contemplation, one could perhaps, download or find an old
>> 1.5 version and just start from there. Use the 1.5 version and just say
>> that any and all functions that existed in that version started with
>> that version and ignore the previous versions.)
>>
>> Good luck with that. I would advise against trying it, because I can see
>> into the future and I can tell you straight up and right now that you're
>> not going to get very far before you give up. I know I would and you
>> would have to be completely diehard and god-like to do so. Meaning that
>> if you were to complete such a task, I would build a shine in your honor.
>>
>> I think that going forward, it would be a good idea. Going back and
>> adding @since isn't going to do any good, since well, plugin authors
>> already know that their plugins don't work.
>>
>> Besides that. I think that if you were (and by you, I mean we) going to
>> add phpDoc comments, it should also include information about the
>> function. What the function does and what it is used for and how in the
>> code is more useful than @since (not that I'm saying @since is useless,
>> because it isn't, it is more useful for future documentation than past).
>>
>> In which case, I agree that the convention should be
>>
>> /**
>> * function_name() - Short description
>> *
>> * Long Description
>> *
>> * @param Stuff here
>> * @return Stuff here
>> * @since Version here (if known. Taxonomy should be updated to include
>> @since 2.3)
>> */
>>
>> The reason for this convention is that the first thing a person wants to
>> know is what the function purpose is without the filler crap. The second
>> thing a coder wants to know after they've decided upon that, is more
>> about what it does and how to use it. If you are really hardcore, you'll
>> add (@example Code) or (@tutorial Text ... Code).
>>
>> Meaning, while the "function_name()" portion is redundant in the
>> phpDocumentor context, it is still useful for the reader browsing the
>> code. You don't have to keep scrolling down to see what the function is,
>> it is just right there at the top!
>>
>> I did some work on the Taxonomy documentation. I would like very much if
>> someone else would work on that. In that case, would it be neat if we
>> picked a file and assigned functions to whoever wants them to write
>> documentation for it? I'll be more willing to take up the task, if I
>> knew others were undergoing the same torture I was.
>>
>> Cheers,
>>
>> Jacob Santos
>>
>> Jared Bangs wrote:
>>     
>>> On 10/13/07, Ozh <ozh at planetozh.com> wrote:
>>>
>>>       
>>>> On 10/13/07, Robin Adrianse <robin.adr at gmail.com> wrote:
>>>>
>>>>         
>>>>> PHPDoc has a @since variable, which was made specifically for this
>>>>>
>>>>>           
>>>> purpose.
>>>>
>>>> But I'd really like at least a simple "// added in WP 2.4" even for
>>>> basic non phpdoc'ed stuff :)
>>>>
>>>>         
>>> +1 for using PHPDoc as a standard way of doing this. If we're going to
>>>       
>> go
>>     
>>> back through and add comments to the existing code, it should definitely
>>>       
>> be
>>     
>>> in a consistent format.
>>> _______________________________________________
>>> wp-hackers mailing list
>>> wp-hackers at lists.automattic.com
>>> http://lists.automattic.com/mailman/listinfo/wp-hackers
>>>
>>>       
>> _______________________________________________
>> wp-hackers mailing list
>> wp-hackers at lists.automattic.com
>> http://lists.automattic.com/mailman/listinfo/wp-hackers
>>
>>     
>
>
>
>