Advanced PHP Programming- P2

Tham khảo tài liệu advanced php programming- p2, công nghệ thông tin, kỹ thuật lập trình phục vụ nhu cầu học tập, nghiên cứu và làm việc hiệu quả
Nội dung trích xuất từ tài liệu:
Advanced PHP Programming- P228 Chapter 1 Coding Styles Compare this with the following: NamePosition The second code fragment is cleaner and does not obfuscate the HTML by unnecessari- ly using echo. As a note, using the syntax, which is identical to , requires the use of short_tags, which there are good reasons to avoid. print Versus echo print and echo are aliases for each other; that is, internal to the engine, they are indistinguishable. You should pick one and use it consistently to make your code easier to read. Using Parentheses Judiciously You should use parentheses to add clarity to code.You can write this: if($month == ‘february’) { if($year % 4 == 0 && $year % 100 || $year % 400 == 0) { $days_in_month = 29; } else { $days_in_month = 28; } } However, this forces the reader to remember the order of operator precedence in order to follow how the expression is computed. In the following example, parentheses are used to visually reinforce operator precedence so that the logic is easy to follow: if($month == ‘february’) { if((($year % 4 == 0 )&& ($year % 100)) || ($year % 400 == 0)) { $days_in_month = 29; } else { $days_in_month = 28; } } You should not go overboard with parentheses, however. Consider this example: if($month == ‘february’) { if(((($year % 4) == 0 )&& (($year % 100) != 0)) || (($year % 400) == 0 )) { $days_in_month = 29; Documentation 29 } else { $days_in_month = 28; }}This expression is overburdened with parentheses, and it is just as difficult to decipherthe intention of the code as is the example that relies on operator precedence alone.DocumentationDocumentation is inherently important in writing quality code. Although well-writtencode is largely self-documenting, a programmer must still read the code in order tounderstand its function. In my company, code produced for clients is not consideredcomplete until its entire external application programming interface (API) and any inter-nal idiosyncrasies are fully documented. Documentation can be broken down into two major categories: n Inline comments that explain the logic flow of the code, aimed principally at peo- ple modifying, enhancing, or debugging the code. n API documentation for users who want to use the function or class without read- ing the code itself.The following sections describe these two types of documentation.Inline CommentsFor inline code comments, PHP supports three syntaxes: nC-style comments—With this type of comment, everything between /* and */ is considered a comment. Here’s an example of a C-style comment: /* This is a c-style comment * (continued) */ n C++-style comments—With this type of comment, everything on a line fol- lowing // is considered a comment. Here’s an example of a C++-style comment: // This is a c++-style comment n Shell/Perl-style comments—With this type of comment, the pound sign (#) is the comment delimiter. Here’s an example of a Shell/Perl-style comment: # This is a shell-style commentIn practice, I avoid using Shell/Perl-style comments entirely. I use C-style comments forlarge comment blocks and C++-style comments for single-line comments.30 Chapter 1 Coding Styles Comments should always be used to clarify code.This is a classic example of a worth- less comment: // increment i i++; This comment simply reiterates what the operator does (which should be obvious to anyone reading the code) without lending any useful insight into why it is being per- formed.Vacuous comments only clutter the code. In the following example, the comment adds value: // Use the bitwise “AND” operatorest to see if the first bit in $i is set // to determine if $i is odd/even if($i & 1) { return true; } It explains that we are checking to see whether the first bit is set because if it is, the number is odd. API Documentation Documenting an API for external users is different from documenting code inline. In API documentation, the goal is to ensure that developers don’t have to look at the code at all to understand how it is to be used. API documentation is essential for PHP libraries that are shipped as part of a product and is extremely useful for documenting libraries that are internal to an engineering team as well. These are the basic goals of API documentation: n It should provide an introduction to the package or libra ...