PHPBB coding standard specification
If you have an annotation or suggestion for the original manual, please email nate@phpbb.com; if you have comments or suggestions for translation this article, please contact GAOGAN @ bmy, or email to Kindpuppy@sohu.com.
Editor Settings Naming Code Layout General Specification Back to Top
Editor setting
Table VS space: For this matter as simple as possible, we will use tabs without spaces. Do you safely to set your editor to use how much spaces use the tab, but you must ensure that when you save the file, it saves tabs instead of space. In this way, each of us can make the code display in the way we like, while do not destroy the layout of the actual file.
Return: Make sure your editor saves the file to UNIX format. This means that the line is terminated by changing, not like they use a CR / LF pair like they in Win32, nor is it a way used by any Mac. Any decent WIN32 editor should be able to do this, but this is not necessarily the default. Familiar with your editor. If you want to ask a developer with a Windows Text Editor, just ask a developer. Some people in them do editors in Win32.
back to the top
Naming agreement
In our naming conventions, we will not use any form of Hungary symbol (translator's note: the original text, no understanding). Many of us believe that Hungarian naming is one of the main techniques that lead to code confusion.
Variable Name: Variable Name should be lowercase, and the words are separated by a single underscore. For example: $ current_user is correct, but $ Currentuser and $ currentuser are incorrect. Names should be descriptive and concise. We don't want to use huge sentences as our variable name, but more than a few characters are usually better than what is doubtful.
Cycle counter: The only situation allows the use of a single-character variable is when it is a counter console. In this case, the counter of the outer loop should always be $ I. If there is a loop in the interior of that loop, its counter should be $ J, which is $ k, and so on. This specification does not apply if this loop is used in a variable that exists and has meaningful name. E.g:
For ($ I = 0; $ i <$ outer_size; $ i ) {for ($ J = 0; $ J <$ INNER_SIZE; $ J ) {Foo ($ I, $ J);}}
Function Name: The function should also be named afterwards. Here we are not programmed with C, we do not want to write functions called such as "stristr ()". Again, intervals of single underline separation in words. The function name is preferably a verb. Good function names such as Print_Login_Status (), get_user_data (), and more.
Function parameters: Parameters are subject to the same agreement as the variable name. We don't want a bunch of such functions: Do_stuff ($ A, $ B, $ C). In most cases, we are willing to look at the function declaration to know how to use it.
Summary: The basic philosophy here is not to harm the code in order to lazy. However, this must be balanced by some common sense; for example, Print_Login_STATUS_FOR_A_GIVEN_USER () is overflow - this function can be better named Print_User_Login_Status (), or only print_login_status ().
back to the top
Code layout
The standard head of the new file: Here is a template of a head, it should be included in each phpbb file / *********************** *********************************************************** Filename.php ------------------- Begin: sat June 17 2000 Copyright: (c) 2000 The phpbb group email: Support@phpbb.com $ ID: Codingstandards.htm , v 1.3 2001/06/09 21:00:12 Natec EXP $ *********************************************** ******************************************************************************************************************************************************************************* *********************************************************** ***************** * * This program is free software; you can re-release it and / or Modify it; * or the second edition of the license agreement, or (you choose to choose) any later version. * ********************************************************** ********************************** /
Always include braces: This is because it is lazy to make two characters to bring another situation to the code. Although some of the main part of some structures only have a line, don't throw out bracers. Never do it. E.g:
/ * These are wrong * / if (condition) do_stuff (); if (condition) do_stuff (); while (condition) do_stuff (); for ($ I = 0; $ i Where is the braces: this is a bit of holy war (Note: the intense debate between the network on the network), but we will use a style that can be summarized in a sentence: braces always monoprate. Termination of braces should also be on the same column with the starting braces. E.g: IF (condition) {while (condition2) {...}} else {...} for ($ I = 0; $ i <$ limited; $ i ) {...} while (condition) {... } Function do_stuff () {...} Use space between symbols: This is another simple and easy step without too much effort to maintain code readability. Whenever you write an assignment, expression, wait, always retain a space between the symbols. Basically, write the code as English. Insert a space between the variable name and the operator. Do not bind or terminate the bracket before the start of the arc. Don't add spaces before comma or semicolons. Some examples show this. E.g: / * Each pair gives an error method, keeping with the correct way. * / $ i = 0; $ I = 0; IF ($ I <7) ... if ($ I <7) ... IF (($ I <7) && ($ J> 8)) .. ($ I <7) && ($ J> 8)) ... do_stuff ($ i, "foo", $ b); do_stuff ($ I, "foo", $ b); for ($ I = 0; $ I <$ size; $ i ) ... for ($ I = 0; $ i <$ = $ i ) ... $ I = ($ j <$ size)? 0: 1; $ i = ($ j <$ size)? 0: 1; Operator Priority: Do you know the detailed priority of all operators in PHP? I do not know either. Don't guess. Always enable priority to priority with parentheses, so you know what it will do. E.g: /* what's the result? who knows? * / $ bool = ($ I <7 && $ j> 8 || $ k == 4); / * Now you have determined what I am doing here. * / $ bool = ($ I <7) && (($ J <8) || ($ K == 4))))) SQL code layout: Since we are all using different editor settings, do not try to do trouble such as in the SQL code. What's going to do, no matter what method, put the statement to the separate line. Here is a SQL code that looks like a sample. Pay attention to where to break, uppercase, and parentheses. E.g: Select Field1 As Something, Field2, Field3 from Table A, Table B Where (this = That) And (this2 = That2) SQL INSERT statement: SQL INSERT statement can be written into two different ways. Or you clearly explain the rows you want to be inserted, or you already know the order in the data and you don't have to specify them in detail. We want to use the former method, that is, how to explain which rows will be inserted. This means that our application-level code does not depend on the order in the database, nor does it crash because we add additional fields (of course, unless they are designated as NOT NULL). E.g: # This is not what we want Insert Into MyTable Values ('Something', 1, 'Else') # is correct. INSERT INTO MyTable (Column1, Column2, Column3) Values ('Something', 1, 'ELSE') back to the top General specification Quote string: There are two different ways in PHP to reference strings - use single quotes or use double quotes. The main difference is that the parser executes variable replacement in a string enclosed in a double quota, but does not execute in a string enclosed in a single quotation. Therefore, you should always use single quotes unless you express the variable replacement of that string. In this way, we can save the parser to resolve a bunch of strings that do not need to perform a replacement string. Similarly, if you use a string variable as part of the function call, you don't need to enclose the variable with quotation marks. Similarly, it will only add unnecessary work to the parser. In any case, pay attention to almost all of the escape sequences in double quotes will not work in single quotes. Be careful, rest assured to break this specification if it makes your code difficult to read. For example: / * Error * / $ str = "this is a really long string with no variables for the Parser to find."; Do_stuff ("$ STR"); / * Correct * / $ str = 'this is a really long String with no variables for the paraser to find. '; do_stuff ($ STR); Related arrays: In PHP, use a string on the literally enclosed in quotation as a key value of a correlation array is legal. We don't want to do this - this string should always be enclosed in quotation to avoid confusion. Note that this is just when we use the literal, not when we use the variable. E.g: / * Error * / $ foo = $ assoc_Array [Blah]; / * Correct * / $ foo = $ assoc_array ['Blah']; Note: You should have a comment before each function telling a programmer to use this function to know everything you need. The meaning of each parameter is needed, the desired input, the output of the function is used as a minimized annotation. The behavior of this function should also be given under the wrong condition (and what is the specific error condition). (Note Should be ensured) No one has to view its actual code in order to reconcle this function in his code. In addition, annotation of any skillful, embarrassing or not obvious code is undoubtedly what we should do. Especially important for documents is any assumptions made by your code, or it is the premise it properly. Any developer should be able to view any part of the application and what happened in the reasonable time (execution of the code). Magic Number, constant?): Do not use them. Use a naming constant for any exact value unless there is a significant special situation. Basically, use literal 0 to check if there are 0 elements to be OK. It is not OK to give a number with special meaning and use it everywhere. This affects readability and maintainability. In this specification, we should use constants True and false instead of 1 and 0 on the literal, although they have the same value, logic is more obvious when you use naming constants. Simplified operator: Only simplified operators that cause readability issues are simplified ($ i ) and self-reduction ($ I -) operators. These operators should not be used as part of the expression. However, they can use them exclusively. Use them in expressions (convenience brings) not enough to debug (expense). E.g: / * Error * / $ Array [ $ I] = $ J; $ array [$ i ] = $ k; / * Correct * / $ i ; $ array [$ I] = $ j; $ array [$ I ] = $ K; $ I ; Conditional Expression: Conditional expression should only be used to do very simple things. They are more suitable to be used for assignment, not used to do function calls or any complicated things. If you use improper use, they affect readability, so don't add them to reduce typing. E.g: / * Should not use their places * / ($ j> $ size))? Do_stuff ($ foo): do_stuff ($ bar); / * Use their right place * / $ Min = ($ i <$ j)? $ i: $ j; Do not use uninitial variables: In PHPBB2, we intend to use a higher level of runtime error report. This will mean that variables used for initialization are no longer reported as an error. This problem is easier to check when to check what variables passed by the HTML form. These errors can be avoided by using the embedded ISSET () function to check if a variable is set. E.g: / * Old way * / if ($ forum) ... / * New Measures * / if (Isset ($ forum) ... back to the top
