gotta have style, baby
Moderator: General Moderators
gotta have style, baby
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?
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?
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:
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:
These are just some ways I do things.
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
)I am not so much a stickler for which style someone uses as long as it follows two rules:
- Enhances readablity.
- Consistancy
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.
*/
}
}
?>Code: Select all
$var = "x";
if() {
if() {
doSomething();
}
Something();
}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.
And i find commenting is ESSENTIAL!
I'm a fan of the old, 5 space tab.
Code: Select all
<?php
if ( $This = "Whatever" )
{
echo "This is: " . $This . ""; // End like that isn't necessary but looks nice
}
elseif ( $This == "" )
{
if ( $Is )
{
echo $Is
}
else
{
echo "Sorry Thats a Null Entry";
}
}
else
{
echo "Sorry, Go Away";
}
?>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
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....
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.
*/
}
}I style my commenting differently to most people.
Code: Select all
#######################################
# Function Name : code
# Parameters : 2 ї $var , $value ]
# Description : This function is a
# ::::::::::::::: blah thing that does
# ::::::::::::::: Blah blah blah
#######################################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.
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...Woah! Have you ever coded a 2000 line program? If so, you wouldn't be coding like that
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.
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.
- protokol
- Forum Contributor
- Posts: 353
- Joined: Fri Jun 21, 2002 7:00 pm
- Location: Cleveland, OH
- Contact:
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.evilcoder wrote:And i find commenting is ESSENTIAL!
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.
HE HE HE
Do you mean by this for example a 1768 lines script, that you are working on a 14" monitor,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.
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
No, you really didn't make your point.
Your HTML example is weak, as this can easily be done in PHP.
Really, you don't need to comment:
Really that is useless. And what happens if someone comes along and changes the code, and forgets to change the comment.
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:
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.
or
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?
What about now?
And now?
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.
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.
*/
}
?>Code: Select all
<?php
// I am checking to see if the file is readable
if ( is_readable($file) ) {
?>Code: Select all
<?php
// I am checking to see if the file is readable
if ( is_readable($file) && is_writeable($file) ) {
?>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) ) {
?>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']);
?>Code: Select all
<?php
$comment = strip_tags($_POST['comment']);
$subject = strip_tags($_POST['subject']);
?>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];
}
?>Code: Select all
<?php
// Printing out users' names from $arr_s
for ( $x = 0; $x < $c; $x++ ) {
echo $arr_s[$x];
}
?>Code: Select all
<?php
for ( $x = 0; $x < $maximum_display; $x++ ) {
echo $users_names[$x];
}
?>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.
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.
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.