What do you think about this coding standards document?
Moderator: General Moderators
What do you think about this coding standards document?
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!
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!
Re: What do you think about this coding standards document?
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.
This is simply incorrect.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.
Re: What do you think about this coding standards document?
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.
Re: What do you think about this coding standards document?
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).infolock wrote:What is incorrect about the \n remark?
Re: What do you think about this coding standards document?
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.
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.
Re: What do you think about this coding standards document?
It wasn't *nix until MacOS X.infolock wrote:That's odd, I thought MacOS used \n since it is a unix engine?
- 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?
Yes, Unix was \n, Apple was \r and Microsoft did \r\n. Now Apple is Unix so it's \n.
(#10850)
Re: What do you think about this coding standards document?
I could write an editor that treats \t as newlines it doesn't mean that's how *windows* sees it.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.
- superdezign
- DevNet Master
- Posts: 4135
- Joined: Sat Jan 20, 2007 11:06 pm
Re: What do you think about this coding standards document?
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:
Really, I just feel like this guy felt like ranting in defense of his coding style.
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:
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).Bad ExampleGood ExampleCode: Select all
$first_name = 'John'; $last_name = 'Doe'; $city = 'Cincinnati';
Code: Select all
$first_name = 'John'; $last_name = 'Doe'; $city = 'Cincinnati';
Really, I just feel like this guy felt like ranting in defense of his coding style.
Re: What do you think about this coding standards document?
Superdesign: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: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).Bad ExampleGood ExampleCode: Select all
$first_name = 'John'; $last_name = 'Doe'; $city = 'Cincinnati';
Code: Select all
$first_name = 'John'; $last_name = 'Doe'; $city = 'Cincinnati';
Really, I just feel like this guy felt like ranting in defense of his coding style.
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!
Re: What do you think about this coding standards document?
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
http://pear.php.net/manual/en/standards.php
http://framework.zend.com/manual/en/cod ... ndard.html
Re: What do you think about this coding standards document?
Yeah, Pear's is really close to what we use here. Zend's too, but the curly brace placement is a little different.
- superdezign
- DevNet Master
- Posts: 4135
- Joined: Sat Jan 20, 2007 11:06 pm
Re: What do you think about this coding standards document?
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.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.
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.
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: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.
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: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.
infolock wrote:Finally, as for the thought of ranting and trying to defend a specific way of coding, it's quite the contrary.
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.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.
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.
Maybe I should make my own programming language, too? Or maybe I don't because I don't see any reason to...infolock wrote:maybe you should try making your own?
Re: What do you think about this coding standards document?
On the contrar, such a coding standard would provide higher incentive to not create such snarled methodssuperdezign 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.
- superdezign
- DevNet Master
- Posts: 4135
- Joined: Sat Jan 20, 2007 11:06 pm
Re: What do you think about this coding standards document?
Which methods...?josh wrote:such a coding standard would provide higher incentive to not create such snarled methods