[Phpmyadmin-devel] Documentation standard for error reporting server

[Dieter Adriaenssens]

2013/9/1 Mohamed Ashraf <mohamed.ashraf.213 at gmail.com>:
>
>
>
> On Sat, Aug 31, 2013 at 11:56 PM, Isaac Bennetch <bennetch at gmail.com> wrote:
>>
>>
>>
>> On Aug 31, 2013, at 5:09 PM, "J. M." <mynetx at users.sf.net> wrote:
>>
>> From: mohamed.ashraf.213 at gmail.com
>> Date: Sat, 31 Aug 2013 23:03:50 +0200
>> To: phpmyadmin-devel at lists.sourceforge.net
>> Subject: [Phpmyadmin-devel] Documentation standard for error reporting
>> server
>>
>> Is there some documentation standard for the error reporting server or
>> should I create one. Also if we are using a template made for php docs,
>> special treatment must be given to controller actions since they normally do
>> not return anything and have a lot of metadata connected to them through the
>> router in the form of the urls that lead to them.
>>
>> --
>> Mohamed Ashraf
>>
>>
>> I favorite Readthedocs - Can the team member who had set this up,
>> elaborate, please?
>> - JM
>>
>>
>> I believe Michal set this up, but he has limited email access this week.
>> That's for user documentation; if Mohamed means developer documentation that
>> can happen in the wiki in the Devel namespace. That's of course in addition
>> to the in-line function block comments. Mohamed, perhaps you can elaborate a
>> bit and we can help further — if you need wiki space I certainly can assist
>> you in finding the right place to put things.
>
>
> I am talking about the mandatory doc blocks for created functions in the
> phpmyadmin codebase. I am asking if there was something of the sort for the
> error reporting server codebase or not. I am talking about developer docs
> for someone who needs to fix a bug somewhere and needs to understand what a
> function does. I normally rely on other developers reading the code and
> understanding it. However that was not the direction you seem to be going
> with in the phpmyadmin codebase so I was wondering how will we go along with
> the error reporting server codebase.

The error reporting server is completely new, so we'll have to define
a coding style for this.
I would suggest to use the same structure for the DocBlocks as we use
in phpMyAdmin, but the cakePHP uses a different coding style, so it's
better to follow the example of what's done in cakePHP. Did you have a
look at how the DocBlocks in cakePHP are defined?

But code documentation is not just the DocBlock describing what a
method does, but also putting enough comments in the code, explaining
what is happening, why it is done this way, or just structuring your
code.

Relying on other developers* to read code and understand everything
that is there is time consuming. Well documented code can be read
quickly, thus making future code maintenance quicker.
(* this includes you in 6 months time when you don't remember exactly
how fe. that format string is constructed, or what all the parameters
of that method are for)

That said, a rule of thumb for documenting your code : if you need
time to remember what a line of code does, or took you some time to
write it (fe. going through all the different parts of an
if-statement, reading a regexp, or why you have to call some method
before calling another one), add some comments about what it is
supposed to do. I'm not saying you have completely explain 'bit by
bit' what is happening, unless you feel it is necessary to do so in a
given case. ;)

I hope this helps.

-- 
Kind regards,

Dieter Adriaenssens