Commenting style in php

PHP Programming/Commenting and Style

As you write more complex scripts, you’ll see that you must make it clear to yourself and to others exactly what you’re doing and why you’re doing it. Comments and «good» naming can help you make clear and understandable scripts because:

• When writing a script that takes longer than a week, by the time you’re done, you won’t remember what you did when you started, and you will most likely need to know.
• Any script that is commonly used will need rewriting sooner or later. Rewriting is much easier (and in many cases, made possible) when you write down what you did.
• If you want to show someone your scripts, they should be nice and neat.

Contents

The comments [ edit | edit source ]

Comments are pieces of code that the PHP parser skips. When the parser spots a comment, it simply keeps going until the end of the comment without doing anything. PHP offers both one line and multi-line comments.

One-Line Comments [ edit | edit source ]

One-line comments are comments that start where ever you start them and end at the end of the line. With PHP, you can use both // and # for your one-line comments (# is not commonly used). Those are used mainly to tell the reader what you’re doing the next few lines. For example:

//Print the variable $message echo $message; 

It’s important to understand that a one-line comment doesn’t have to ‘black out’ the whole line, it starts where ever you start it. So it can also be used to tell the reader what a certain variable does:

$message = ""; //This sets the variable $message to an empty string 

The $message = «»; is executed, but the rest of the line is not.

One-line Comment Issues [ edit | edit source ]

• One-line comments end by either:

1. a newline (an actual newline, not the \n newline mark ) OR:
2. a closing PHP tag of the ?> variety

• If a one-line comment is closed by a closing PHP tag will not be commented. The following will thus print out «2»:

Multi-Line Comments [ edit | edit source ]

This kind of comment can go over as many lines as you’d like, and can be used to state what a function or a class does, or just to contain comments too big for one line. To mark the beginning of a multiline comment, use /* and to end it, use */ . For example:

/* This is a multiline comment And it will close When I tell it to. */ 

You can also use this style of comment to skip over part of a line. For example:

$message = ""/*this would not be executed*/; 

Although it is recommended that one does not use this coding style, as it can be confusing in some editors.

Multi-line Comment Issues [ edit | edit source ]

• An unfinished multi-line comment will result in an error, unless it is starting (not closing) within an already existing multi-line comment block (i.e., it is non-greedy but only operates first on a complete open and close set)
  • The following will result in an error:

  /* Starting first comments /* Starting Nested comments Ending nested comments */ Ending first comments */ 

  • One can quickly toggle multiple blocks at a time by combining the styles (though this may not work show as such correctly in a text editor)

  Original text with nothing commented out (thus printing «block one block two»:

   //* print "block "; print "one "; // */ print "block "; print "two"; ?> 

  After taking out a / on the first line, the first block is commented out, printing only «block two»:

   /* print "block "; print "one "; // */ print "block "; print "two"; ?> 

  Since the single line // overrides the multi-line /* .. */ two blocks of code can be switched at the same time back and forth into or out of comment mode.

  Original text (printing out only «block one»)

   //* print "block"; print "one"; /*/ print "block"; print "two"; // */ ?> 

  After taking out a / on the first line, the first block is commented out and the second block is uncommented, printing out only «block two»:

   /* print "block"; print "one"; /*/ print "block"; print "two"; // */ ?> 

  • phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.pkg.html PHPDocumentor uses multiline comments (albeit with the opening immediately followed by an additional asterisk «/**») and other standardized tags within the comment block to create its automatic documentation. See the website for additional instructions. For example:

   /** * This is my new fancy code. * @author Dr. Who * @version 1.0 */ ?> 

  Issues with Either Single or Multi-line Comments [ edit | edit source ]

  When using multi-line comments with the typical «/» as delimiters in a regular expression, it is possible there will be a conflict, as an asterisk at the end of the expression (along with the closing «/» delimiter) could create something that would be parsed as a closer of the comments, thus leaving the succeeding «*/» without an opener:

   /* $subject = "Hi Joe"; $matching = preg_match($subject, '/^Hi.*/'); */ ?> 

  To avoid the problem, one could:

  • Use other regular expression delimiters—delimiters that may be less frequently encountered (and thus also in need of escaping) in most circumstances anyhow (e.g., «@» besides for email matching may be less frequent than «/»)
  • Use an «if» with an impossible conditional that can:

  Avoid regular expression conflicts:

   if (0)  $subject = "Hi Joe"; $matching = preg_match($subject, '/^Hi.*/'); > ?> 

  and also avoid nesting problems:

   if (0)  if (0)  print "Hi "; > print "Bob"; > ?> 

  One disadvantage of the «if» method, however, is that it will most likely not be recognized by text editors as far as code coloring (though this may be an advantage for debugging, if one wishes to see more clearly what is inside the commented out block while running tests on the code).

  Styles [ edit | edit source ]

  The PHP coding styles are defined in the PHP Standard Recommendation.

  Naming [ edit | edit source ]

  Naming your variables, functions and classes correctly is very important to understand the program. By convention, it should be done in camelCase and without any abbreviation.

  If you define the following variables:

  They won’t say much to anyone. But if you do it like this:

  $programmingLanguage = "PHP"; $menuItems = 15; 

  It would be much clearer. But don’t go too far. $programmingLanguage, for example is not a good name. It’s too long, and will take you a lot of time to type and can affect clarity. A better name may be $progLanguage, because it’s shorter but still understandable. A good naming should avoid to write a comment to mark what every variable does.

  For instance, these comments are encumbering the script and should be removed:

  // The programming language used to write this script $progLanguage = "PHP"; // The maximum number of items allowed in your personal menu $maxMenuItems = 15; 

  Magic numbers [ edit | edit source ]

  When using numbers in a program it is important that they have a clear meaning. For instance it’s better to define $menu_items early on instead of using 15 repeatedly without telling people what it stands for. The major exception to this is the number 1; often programmers have to add or subtract 1 from some other number to avoid off-by-one errors, so 1 can be used without definition.

  When you define numbers early on in their usage it also makes it easier to adjust the values later. Again if we have 15 menu items and we refer to them ten times, it will be a lot easier to adjust the program when we add a 16th menu item; just correct the variable definition and you have updated the code in 10 places.

  Spacing [ edit | edit source ]

  PHP ignores extra spaces and lines. This means, that even though you could write code like this:

  if ($var == 1) echo "Good";> else echo "Bad";> 

  It’s better like this, which is the PSR-2 form [1] :

  if ($var == 1)  echo "Good"; > else  echo "Bad"; > 

  Some programmers prefer this way of writing:

  if ($var == 1)  echo "Good"; > else  echo "Bad"; > 

  You should also use blank lines between different portions of your script. Instead of

  $var = 1; echo "Welcome!<br />"; echo "How are you today?<br />"; echo "The answer: "; if ($var == 1)  echo "Good"; > else  echo "Bad"; > 

  $var = 1; echo "Welcome!<br />"; echo "How are you today?<br />"; echo "The answer: "; if ($var == 1)  echo "Good"; > else  echo "Bad"; > 

  And the reader will understand that your script first declares a variable, then welcomes the user, and then checks the variable.

  The directives [ edit | edit source ]

  It’s possible to define certain PHP compiling behaviors by some directives written in the command declare() . [2] For example:

  References [ edit | edit source ]

  Источник

  PHP Comments Tutorial

  In this tutorial we will learn the different styles of documenting your code with comments as well as how other language comments interact with PHP.

  What is a comment?

  Commenting is a way for a programmer to document their code and to enhance its readability.

  PHP comments are ignored by the interpreter, which means the interpreter won’t try to execute any text written inside a comment.

  In general, our code should be written cleanly and clearly enough so that it’s obvious as to what the code does.

  In most cases our code won’t need comments, but there are situations where we should include comments.

  • When learning, we want to comment most of what we’re doing or what specific code is doing. We’re not yet used to how a language operates and even if we know another language, PHP might behave differently to what we’re used to. It helps us understand and remember code functionality. It’s recommended to comment code extensively in your own words when learning programming or when learning a new programming language.
  • When we’re working on projects as part of a group we want to comment our code in such a way that other programmers immediately understand what’s going on. One programmer shouldn’t need to ask another what their code does, it should be obvious or commented. This helps to avoid confusion and increase productivity.
  • When using external libraries it may be useful to comment what certain things do or why they are used so that it’s not necessary to go back and forth to the library’s documentation for lookup in the future.
  • When we’re working with complex code it may not be immediately clear what the code is doing. Commenting in such a case is useful to quickly see what pieces of code is doing or what it’s for.
  • In some cases we may want to temporarily remove a piece of code to either try something different, or to debug problem areas.
  • When planning to create API Documentation.

  How to comment PHP code

  PHP supports C, C++ and Unix shell (Perl style) comments.

  C and C++ style single line comments in PHP

  A single line comment occupies its own line. Everything up to a new line will be a comment and PHP will ignore it.

  With a C, C++ style comment we write two forward slashes // followed by some words.

  Источник