gotta have style, baby

Not for 'how-to' coding questions but PHP theory instead, this forum is here for those of us who wish to learn about design aspects of programming with PHP.

Moderator: General Moderators

User avatar
llimllib
Moderator
Posts: 466
Joined: Mon Jul 01, 2002 2:19 pm
Location: Baltimore, MD

gotta have style, baby

Post by llimllib »

What does your coding style look like? How do you format your SQL queries? Your HTML output? Do you use inline PHP, or write PHP programs that output HTML? (or when do you use each?)

For my money, the Pear coding standard is the best, but where do you agree/disagree with it? What are some excellent/poor examples of coding style you've seen?

Where do you put your documentation? What type of comments do you use, and why?
jason
Site Admin
Posts: 1767
Joined: Thu Apr 18, 2002 3:14 pm
Location: Montreal, CA
Contact:

Post by jason »

I guess you could say I follow the PEAR coding standard, except I use tabs instead of spaces.

As far as SQL queries go, I am switching to use the Phrasebook pattern for my string handling, including regex, sql, and strings in general.

However, a sample of my prefered SQL code looks like this:

Code: Select all

INSERT INTO
	table_name
(
	field_name,
	field_name2,
	field_name3
) VALUES (
	'value1',
	'value2',
	3
)
For me, that usually reads easily, especially for some big queries. It makes it easy to quickly pick out individual parts.

I am not so much a stickler for which style someone uses as long as it follows two rules:
  1. Enhances readablity.
  2. Consistancy
I also follow a simple naming structure for everything.

Code: Select all

<?php

$variable_name = 'value';
$objectName = new Object();

class Object
{
	var $var_name;
	var $objectName;

	function Object ( $var_name, &$objectName )
	{
		$this->var_name = $var_name;
		/*
		Note, it should be
			$this->objectName =& $objectName;
		...not...
			$this->objectName = &$objectName;
		The name of the variable is not &$objectName. By
		placing the & next to the =, you are defining how the
		= works, which makes more sense.  Also, if you
		include the & next to the variable name, it can make
		it more difficult to read, and even copy/paste.
		*/
		$this->objectName =& $objectName;
	}

	function methodName () {}
	
	/**
	* @param $name type
	* @return unknown
	* @desc Enter description here... should be 1 sentence, or 
	* two if absolutely necessary.
	*/
	function actionMethod ( $name ) {}
	{
		/*
		Methods should always be actions.  That is what a
		method, or function is.  Method names should never
		say actionObject.  For example, if the object name is
		Article, you shouldn't have a method named
		postArticle(), a method named post() should suffice.
		*/
	}
}

?>
These are just some ways I do things.
Doolittle
Forum Newbie
Posts: 19
Joined: Sun May 04, 2003 11:45 pm

Post by Doolittle »

Code: Select all

$var = "x";

if() &#123;
	if() &#123;
		doSomething();
	&#125;
	Something();
&#125;
I'm a bit different... I pretty much do what I find easiest for me to read...
evilcoder
Forum Contributor
Posts: 345
Joined: Tue Dec 17, 2002 5:37 am
Location: Sydney, Australia

Post by evilcoder »

Woah! Have you ever coded a 2000 line program? If so, you wouldn't be coding like that :)

I'm a fan of the old, 5 space tab.

Code: Select all

<?php

if ( $This = "Whatever" )
&#123;
     echo "This is: " . $This . ""; // End like that isn't necessary but looks nice
&#125;
elseif ( $This == "" )
&#123;
     if ( $Is )
     &#123;
          echo $Is
     &#125;
     else 
     &#123;
          echo "Sorry Thats a Null Entry";
     &#125;
&#125;
else
&#123;
     echo "Sorry, Go Away";
&#125;

?>
And i find commenting is ESSENTIAL!
User avatar
volka
DevNet Evangelist
Posts: 8391
Joined: Tue May 07, 2002 9:48 am
Location: Berlin, ger

Post by volka »

just as addition to Jason's stlye of commenting, javadoc comments are very common and tools are available for a huge set of languages and IDEs.
I'm using doxygen to build documentations (although it still has serious problems with php-code).
A slightly extended version of Jason's example is

Code: Select all

/** @class Object
* Useful description of the purpose of class Object
* @author Volker Krause, ...
* @brief basic documention example
* @version 1.0
* @date 2003
* @bug never worked, ...
* @warning if you find any purpose in this class, you really should take care of your RL
* @todo unit tests would be more than helpful
* @deprecated superceded by class ObjectEx 
*/
class Object
{
	var $var_name; /**< description of var_name */
	var $objectName; /**< description of objectName */
	
	
	/** @brief Construction, setting essential members
	*  Constructing a new Object..(something more useful here)
	*
	* @param $var_name ...
	* @param &$objectName ...
	*
	*/
	function Object ( $var_name, &$objectName )
	{
		$this->var_name = $var_name;
		/*
		Note, it should be
		$this->objectName =& $objectName;
		...not...
		$this->objectName = &$objectName;
		The name of the variable is not &$objectName. By
		placing the & next to the =, you are defining how the
		= works, which makes more sense.  Also, if you
		include the & next to the variable name, it can make
		it more difficult to read, and even copy/paste.
		*/
		$this->objectName =& $objectName;
	}
	
	/** ...description...
	* @param $name type
	* @return...
	* @since 1.0
	* @desc Enter description here... should be 1 sentence, or
	* two if absolutely necessary.
	*
	* /code
	* $r = $obj->actionMethod( 'param' );
	* switch (gettype($r))
	*		...
	* /endcode
	*/
	function methodName ($name ) {}
	

	/** ...description...
	* @param $name type
	* @return unknown
	* @deprecated reason
	* @see methodName($name)
	*/
	function actionMethod ( $name ) {}
	{
		/*
		Methods should always be actions.  That is what a
		method, or function is.  Method names should never
		say actionObject.  For example, if the object name is
		Article, you shouldn't have a method named
		postArticle(), a method named post() should suffice.
		*/
	}
}
What your coding style may be, never forget to mark changes. This must include who,when,where,why. You might be able to understand your own code as long as it was written as one set. As soon as you change something in there, things become much more difficult....
evilcoder
Forum Contributor
Posts: 345
Joined: Tue Dec 17, 2002 5:37 am
Location: Sydney, Australia

Post by evilcoder »

I style my commenting differently to most people.

Code: Select all

#######################################
# Function Name : code
# Parameters    : 2 &#1111; $var , $value ]
# Description   : This function is a 
# ::::::::::::::: blah thing that does
# ::::::::::::::: Blah blah blah
#######################################
jason
Site Admin
Posts: 1767
Joined: Thu Apr 18, 2002 3:14 pm
Location: Montreal, CA
Contact:

Post by jason »

Evilcoder: The problem with that comment is the difficulty in maintaining the comment. Changing a comment shouldn't require work, it should be easy to do, and be intuitive. This is my major gripe with all the JavaDoc style comments out there. They all suck. They are NOT easy to use, nor are they intuitive.
User avatar
volka
DevNet Evangelist
Posts: 8391
Joined: Tue May 07, 2002 9:48 am
Location: Berlin, ger

Post by volka »

But you're still using them? ;)
Doolittle
Forum Newbie
Posts: 19
Joined: Sun May 04, 2003 11:45 pm

Post by Doolittle »

Woah! Have you ever coded a 2000 line program? If so, you wouldn't be coding like that
Never developed programs... But lets say for example for current project, its up to 1400 lines or so... I just leave really obvious comments of whats going on and give space for different tasks... And I seem to do fine... I guess you could call it a bad habit, but its the way I like it... :)
jason
Site Admin
Posts: 1767
Joined: Thu Apr 18, 2002 3:14 pm
Location: Montreal, CA
Contact:

Post by jason »

Yup, I use them. Why? Because a lot of tools are written for them.

I use the Zend DE, which means I can right-click, and add the function comments that way. My biggest problem is the * before every line. It's annoying, and completely useless.

However, I might just use the Tokenizer in PHP and build my on docu engine.
User avatar
volka
DevNet Evangelist
Posts: 8391
Joined: Tue May 07, 2002 9:48 am
Location: Berlin, ger

Post by volka »

aye, the leading asterisks are annoying.
Fortunatly they are optional not only for doxygen but since version 1.4 for javadoc, too
User avatar
protokol
Forum Contributor
Posts: 353
Joined: Fri Jun 21, 2002 7:00 pm
Location: Cleveland, OH
Contact:

Post by protokol »

evilcoder wrote:And i find commenting is ESSENTIAL!
Well, I would have to say that if you are writing code, then the best way to write it would be to make it self-documenting.

What I mean by this is to use meaningful variable names and function names. Also, indentation and consistency in style are key.

As for commenting the code, I'd say the only time it's really necessary to comment the code is if it's not readily apparant what exactly a block of code is doing.

Just my 2 cents.
netcrash
Forum Newbie
Posts: 4
Joined: Mon May 19, 2003 8:09 pm
Location: Portugal

HE HE HE

Post by netcrash »

As for commenting the code, I'd say the only time it's really necessary to comment the code is if it's not readily apparant what exactly a block of code is doing.
Do you mean by this for example a 1768 lines script, that you are working on a 14" monitor,
so it's hard to see the code.
In that case i would say "Thank you comments".

It helps a lot to know when a part of code that checks ( example ) for permissions on the file to write and other part that controls database ...

Ok very bad example in this case it would be great to do every thing has a module . but anyway,
it's good to have comments they make it easy and saves time to anyone that comes read the code .

Imagine you working on an webpage that has lots of services like polls, news, forum, etc.
It would be good to know even in html comments where does one part start and ends.

Think i made my point .
This was my 2 dollars :) LOL
jason
Site Admin
Posts: 1767
Joined: Thu Apr 18, 2002 3:14 pm
Location: Montreal, CA
Contact:

Post by jason »

No, you really didn't make your point.

Your HTML example is weak, as this can easily be done in PHP.

Code: Select all

<?php

function functionName ()
{
	/*
	Code goes here.  It's easy to see where this starts and
	stops.  functionName() deserves a 1 line description of what
	it does, and that's it.
	*/
}

?>
Really, you don't need to comment:

Code: Select all

<?php
// I am checking to see if the file is readable
if ( is_readable($file) ) {
?>
Really that is useless. And what happens if someone comes along and changes the code, and forgets to change the comment.

Code: Select all

<?php
// I am checking to see if the file is readable
if ( is_readable($file) && is_writeable($file) ) {
?>
Or, even if I remember to change the comment, now it's two things for me to change.

Commening Rule #1: Comments that require maintenance are bad comments.

This is the easiest to read and understand:

Code: Select all

<?php
if ( is_readable($file) && is_writeable($file) ) {
?>
As far as your 14 inch monitor example: it's not a problem, unless you aren't designing your code properly.

A block of code shouldn't be longer than one screens length, or about 25 lines. Nor should you let your code go beyond 80 characters. A function that is longer than 25 lines probably is written correctly. Their are exceptions, but I look at my own code, where 9 in 10 functions are less than 25 lines.

There is also the assertion that comments should be sprinkled into code, and that more comments are better. This is a poor assertion at best. It simply isn't true.

Commening Rule #2: More comments means your code is less readable.

Code: Select all

<?php
// stripping HTML for protection
$comment = strip_tags($_POST['comment']);
$subject = strip_tags($_POST['subject']);
?>
or

Code: Select all

<?php
$comment = strip_tags($_POST['comment']);
$subject = strip_tags($_POST['subject']);
?>
There is also the case of the highly complex code that needs a paragraph to describe what it does. This is usually a sign the programmer has to do some refactoring.

Also, can you tell me what this is printing out? Not "A string" but rather, what is that string that it's printing out?

Code: Select all

<?php

for ( $x = 0; $x < $c; $x++ ) {
	echo $arr_s[$x];
}

?>
What about now?

Code: Select all

<?php

// Printing out users' names from $arr_s
for ( $x = 0; $x < $c; $x++ ) {
	echo $arr_s[$x];
}

?>
And now?

Code: Select all

<?php

for ( $x = 0; $x < $maximum_display; $x++ ) {
	echo $users_names[$x];
}

?>
You see, not only is the third easier to understand, but we learn that $c wasn't the total amount of users' names, but rather, the maximum we wanted to display. Now the block of code is easy to understand, and we don't need comments.

One final rule:

Commening Rule #3: Comments are written in another language from the code. When reading through code littered with comments, it's like reading through a book in two languages.

This is not to suggest that you should never use comments. Rather, deploy comments with care.
[]InTeR[]
Forum Regular
Posts: 416
Joined: Thu Apr 24, 2003 6:51 am
Location: The Netherlands

Post by []InTeR[] »

I'm working in a company with 5 programma's, some freelancers that work @ home.
A few things in comment are needed.
- Who build it?
- When?

And if somebody changes something, explains his changes @ the top of the document with his name, date, what he changed, and the most needed... Why...

The rest of the code is without comment, only if whe are doing some weird stuff what is not logic.
Post Reply