2013/9/1 Mohamed Ashraf <mohamed.ashraf.213(a)gmail.com>om>:
On Sat, Aug 31, 2013 at 11:56 PM, Isaac Bennetch <bennetch(a)gmail.com> wrote:
On Aug 31, 2013, at 5:09 PM, "J. M." <mynetx(a)users.sf.net> wrote:
Date: Sat, 31 Aug 2013 23:03:50 +0200
Subject: [Phpmyadmin-devel] Documentation standard for error reporting
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.
I favorite Readthedocs - Can the team member who had set this up,
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
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.