2013/9/1 Mohamed Ashraf mohamed.ashraf.213@gmail.com:

On Sat, Aug 31, 2013 at 11:56 PM, Isaac Bennetch bennetch@gmail.com wrote:

...

On Aug 31, 2013, at 5:09 PM, "J. M." mynetx@users.sf.net wrote:

From: mohamed.ashraf.213@gmail.com Date: Sat, 31 Aug 2013 23:03:50 +0200 To: phpmyadmin-devel@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.