What do you think about this coding standards document?

Coding Critique is the place to post source code for peer review by other members of DevNetwork. Any kind of code can be posted. Code posted does not have to be limited to PHP. All members are invited to contribute constructive criticism with the goal of improving the code. Posted code should include some background information about it and what areas you specifically would like help with.

Popular code excerpts may be moved to "Code Snippets" by the moderators.

Moderator: General Moderators

User avatar
infolock
DevNet Resident
Posts: 1708
Joined: Wed Sep 25, 2002 7:47 pm

What do you think about this coding standards document?

Post by infolock »

I wrote a coding standards document for a team I was involved with a few years back. I've implemented it with 3 companies so far and the devs are kinda happy with them. What do you all think?

Full article here


I realize that there should be naming convensions for classes/functions/variables too, but I just haven't gotten to updating this yet. Anyways, any/all feedback welcomed!
User avatar
Weirdan
Moderator
Posts: 5978
Joined: Mon Nov 03, 2003 6:13 pm
Location: Odessa, Ukraine

Re: What do you think about this coding standards document?

Post by Weirdan »

Too lax to my taste. IMO sentences like this: "Either way is acceptable" are not acceptable in a coding standard document. Especially when it comes to naming conventions.
The default should be set to treat new lines as the Unix \n (new line) instead of the Microsoft default \r (Return). The reason is that \n is a universal default supported in all Operating Systems, so no matter what OS your code is opened up in, the new lines will be nicely available on each new line instead of one concurrent line.
This is simply incorrect.
User avatar
infolock
DevNet Resident
Posts: 1708
Joined: Wed Sep 25, 2002 7:47 pm

Re: What do you think about this coding standards document?

Post by infolock »

Wierdan: thanks for the input man. What is incorrect about the \n remark? The only thing I have found that it doesn't work well with is something like notepad, while IDE's (even vi, emacs, etc) work well with it. I guess the statement is more or less just a way to enforce one method for new lines. I'll update the language on the "either way is acceptable" approach though.
User avatar
Weirdan
Moderator
Posts: 5978
Joined: Mon Nov 03, 2003 6:13 pm
Location: Odessa, Ukraine

Re: What do you think about this coding standards document?

Post by Weirdan »

infolock wrote:What is incorrect about the \n remark?
Microsoft OSes use \r\n (CR+LF) combination to mark up new line, not a single \r(CR) (which is, incidentally, was a standard way to mark new lines on Mac prior to MacOS X). Therefore some editors (most notably Notepad) on windows that expect \r\n would get confused by a single \n (LF).
User avatar
infolock
DevNet Resident
Posts: 1708
Joined: Wed Sep 25, 2002 7:47 pm

Re: What do you think about this coding standards document?

Post by infolock »

That's odd, I thought MacOS used \n since it is a unix engine? i guess i can see how i could use \r, but i would be willing to bet it supports both..

either way, microsoft may use \r\n, but it still can understand \n. as far as ide's go, i understand \n can be an issue. however, the majority of the ones i have used for PHP development all support \n, so i'm not too worried about that.
User avatar
Weirdan
Moderator
Posts: 5978
Joined: Mon Nov 03, 2003 6:13 pm
Location: Odessa, Ukraine

Re: What do you think about this coding standards document?

Post by Weirdan »

infolock wrote:That's odd, I thought MacOS used \n since it is a unix engine?
It wasn't *nix until MacOS X.
User avatar
Christopher
Site Administrator
Posts: 13596
Joined: Wed Aug 25, 2004 7:54 pm
Location: New York, NY, US

Re: What do you think about this coding standards document?

Post by Christopher »

Yes, Unix was \n, Apple was \r and Microsoft did \r\n. Now Apple is Unix so it's \n.
(#10850)
josh
DevNet Master
Posts: 4872
Joined: Wed Feb 11, 2004 3:23 pm
Location: Palm beach, Florida

Re: What do you think about this coding standards document?

Post by josh »

infolock wrote:That's odd, I thought MacOS used \n since it is a unix engine? i guess i can see how i could use \r, but i would be willing to bet it supports both..

either way, microsoft may use \r\n, but it still can understand \n. as far as ide's go, i understand \n can be an issue. however, the majority of the ones i have used for PHP development all support \n, so i'm not too worried about that.
I could write an editor that treats \t as newlines it doesn't mean that's how *windows* sees it.
User avatar
superdezign
DevNet Master
Posts: 4135
Joined: Sat Jan 20, 2007 11:06 pm

Re: What do you think about this coding standards document?

Post by superdezign »

We already have coding standards...

And they don't include placing underscores between every word. Camel-casing is faster to type. Also, isn't it standard to differentiate member variables from local variables with a prefix ("m_" for C++, "_" for PHP, "__" for AS)? Not that we need to in a language that understands the "this" keyword in all contexts (unlike C++), since it is a coding standard to always use the "this" keyword in reference to them. Another thing: is it standard to use 2-space tabs nowadays? I always thought that was just a Java/JS (and possibly C#) thing. Also:
Bad Example

Code: Select all

$first_name = 'John';
$last_name = 'Doe';
$city = 'Cincinnati';
Good Example

Code: Select all

$first_name = 'John';
$last_name  = 'Doe';
$city       = 'Cincinnati';
I thought that this was incorrect. This sort of formatting requires reformatting if one were to increase the length of a variable name. The only time I feel this sort of lining up is appropriate is in the declaration of large arrays in PHP (which he mentions after this).

Really, I just feel like this guy felt like ranting in defense of his coding style.
User avatar
infolock
DevNet Resident
Posts: 1708
Joined: Wed Sep 25, 2002 7:47 pm

Re: What do you think about this coding standards document?

Post by infolock »

superdezign wrote:We already have coding standards...

And they don't include placing underscores between every word. Camel-casing is faster to type. Also, isn't it standard to differentiate member variables from local variables with a prefix ("m_" for C++, "_" for PHP, "__" for AS)? Not that we need to in a language that understands the "this" keyword in all contexts (unlike C++), since it is a coding standard to always use the "this" keyword in reference to them. Another thing: is it standard to use 2-space tabs nowadays? I always thought that was just a Java/JS (and possibly C#) thing. Also:
Bad Example

Code: Select all

$first_name = 'John';
$last_name = 'Doe';
$city = 'Cincinnati';
Good Example

Code: Select all

$first_name = 'John';
$last_name  = 'Doe';
$city       = 'Cincinnati';
I thought that this was incorrect. This sort of formatting requires reformatting if one were to increase the length of a variable name. The only time I feel this sort of lining up is appropriate is in the declaration of large arrays in PHP (which he mentions after this).

Really, I just feel like this guy felt like ranting in defense of his coding style.
Superdesign:

Thanks for the input!

A few remarks though. Camel Case for some is great, K&R for others is great. The coding standard defined clearly states that CamelCase is one type of naming convention but it is not what's used. Each has their own methods of naming variables and functions and whatnot, but this document does not use that. So, while it may not be something you'd be happy with, it's something that lays a foundation for not just one person but the team. The point is, while you may not like camel case, had it been used in the document someone else may not like camel case and would want it to be K&R with underscores. I chose to follow one covention and stuck with it. Those coming from the camel case world will think it's a bit odd, but for others they will find it's easier to read definitions since each word is seperated, making it easier to read. Again, this is just one of those things that some developers feel strongly about on both sides.

2 Spaces for tabs was used to try and minimize the amount of wasted space on a page, reduce wrapping, and keep code more compact. If you view differences between a well formatted PHP script with indentions and then compared against a PHP script that has no spaces at all, you'll see an obvious speed increase. The 2 spaces (while it may not be much) tries to give the developer the ability to write code that is still spaced and tabbed for eye appearance, but also attempt to reduce the whitespace in a piece of code. 2 spaces is not only used in Java and JS and C#, but also PHP and others. It's actually even something programmers are gradually going to. I'm not saying that I read thousands of articles about it, but I've read a few, and not to mention the guys where I work have already been doing that on their own. While some can say that 4 spaces is better to keep it more seperated, again this goes along with setting a standard in stone that all must follow who use this standard.

As for the lining up of variable equal signs, it's used for "like" definitions. If I have a block of definitions, they will be lined up to help the readability. Whlie it does add spaces and seems to condradict the earlier argument of 2 spaces and reducing whitespace, we also have to remember we have humans reading this code. 2 tab spaces won't hamper that redability. But if we have a list of variables, array definitions, etc that take up a few lines of code, not having the equal signs lined up puts a lot more strain on your eyes to read their definitions. Lining it up, for the sake of this standard, is one of the pieces I'm very happy with. It makes the code look so much nicer and well put together.

Finally, as for the thought of ranting and trying to defend a specific way of coding, it's quite the contrary. While working for various companies in my area, I took pieces I learned from many who where senior to me at the time, many articles I've read, and noticing how developers code in general. I also take pride in saying that I changed my own methods of coding over time from one method I learned and was accustomed to, and instead adapted to code as the team coded in order to try and make my code easier to read, debug, and maintain for the others. I put all this knowledge together to make one document that is intended to help a "team" environment. While I have no intentions of making everyone happy, the goal was instead to create a standard that the team can use, that the team will follow, and help create a more structured coding environment that will reduce the need for developers to have to format code in order to suit their own coding styles.

Either way, some may find it useful, others may not. I just hope it helps some teams out who care to try it out. There are hundreds of other PHP (and other languages) coding standards to try. This is just one of many, and it just happens to be one I made. maybe you should try making your own? I would be very interested in seeing other ideas rather then the ones I've already read.

Cheers!
User avatar
Eran
DevNet Master
Posts: 3549
Joined: Fri Jan 18, 2008 12:36 am
Location: Israel, ME

Re: What do you think about this coding standards document?

Post by Eran »

Did you go over Pear's coding style? or the one used in the ZF (which is built on it)? I use those in all my project, its pretty comprehensive and well thought-out
http://pear.php.net/manual/en/standards.php
http://framework.zend.com/manual/en/cod ... ndard.html
User avatar
infolock
DevNet Resident
Posts: 1708
Joined: Wed Sep 25, 2002 7:47 pm

Re: What do you think about this coding standards document?

Post by infolock »

Yeah, Pear's is really close to what we use here. Zend's too, but the curly brace placement is a little different.
User avatar
superdezign
DevNet Master
Posts: 4135
Joined: Sat Jan 20, 2007 11:06 pm

Re: What do you think about this coding standards document?

Post by superdezign »

infolock wrote:Camel Case for some is great, K&R for others is great. The coding standard defined clearly states that CamelCase is one type of naming convention but it is not what's used.
But why attempt to state that a coding standard for one language should be the coding standard for another? Languages have different syntax and semantics. Making one global standard for all programming languages isn't possible.

And if it was, camel-casing is still superior in that it separates words just as well as underscores, but it is also quicker to type.
infolock wrote:2 Spaces for tabs was used to try and minimize the amount of wasted space on a page, reduce wrapping, and keep code more compact.
For interpreted languages like JavaScript and PHP, I agree with you. In terms of wrapping, there are coding standards for that too, like having no more than 80 characters per line in C++.
infolock wrote:As for the lining up of variable equal signs, it's used for "like" definitions. If I have a block of definitions, they will be lined up to help the readability.
That is very subjective. It all depends on the way that you read the code. You argue that extra whitespace in the interest of matching up blocks of definitions increases readability. But this, to me, is like having a table of contents page without having the series of periods connecting a topic with it's page. One's mind actually needs to count the lines or relate one line to another in order to find the page number that they are looking for, especially in large listings. To me, placing the page number right next to the topic allows me to find the page quicker without any difficulties of wandering eyes.
infolock wrote:Finally, as for the thought of ranting and trying to defend a specific way of coding, it's quite the contrary.
infolock wrote:I also take pride in saying that I changed my own methods of coding over time from one method I learned and was accustomed to, and instead adapted to code as the team coded in order to try and make my code easier to read, debug, and maintain for the others.
When going from one language to another, it is professional to adhere to the best-practice standards of the language. But to create your own standards based off of other languages does not apply.

Everything that you mentioned is used in other languages. Since PHP is a new-age language, many of its developers have programmed in other languages and are familiar with other coding standards. The coding standards that we use are not based purely off of style or cosmetic appearance. They are based off of the most efficient coding standards. I'd say Java's standards are much closer to PHP's than C++'s, and that is partially because Java is more modernized and refined than C and C++, though based off of them.

Camel-casing is faster to type than underscores and, using your argument of saving space, uses less characters.
Not lining up "related" declarations also saves space.
Spaces are used instead of tabs so that code looks the same in all editors (i.e. Notepad).

The best practice coding standards are all laid out here and are very clear and brief.
infolock wrote:maybe you should try making your own?
Maybe I should make my own programming language, too? Or maybe I don't because I don't see any reason to... :roll:
josh
DevNet Master
Posts: 4872
Joined: Wed Feb 11, 2004 3:23 pm
Location: Palm beach, Florida

Re: What do you think about this coding standards document?

Post by josh »

superdezign wrote: That is very subjective. It all depends on the way that you read the code. You argue that extra whitespace in the interest of matching up blocks of definitions increases readability. But this, to me, is like having a table of contents page without having the series of periods connecting a topic with it's page. One's mind actually needs to count the lines or relate one line to another in order to find the page number that they are looking for, especially in large listings. To me, placing the page number right next to the topic allows me to find the page quicker without any difficulties of wandering eyes.
On the contrar, such a coding standard would provide higher incentive to not create such snarled methods
User avatar
superdezign
DevNet Master
Posts: 4135
Joined: Sat Jan 20, 2007 11:06 pm

Re: What do you think about this coding standards document?

Post by superdezign »

josh wrote:such a coding standard would provide higher incentive to not create such snarled methods
Which methods...?
Post Reply