[wp-hackers] do you guys distinquish between various PHP commenting options?

Jacob Santos wordpress at jacobsantos.com
Sat Jul 19 19:17:04 UTC 2014 

Okay, so, what is the point of comments? When you use /** */ you are saying
to PHP and the PHP tool processing the file, "This comment exists for the
benefit of documenting this block of code to be outputted in an API
documentation site." You should always have /** */ comments. These are
called PHPdoc comments, I guess from PHPdocumentator application.

Single line and multiple line comments exist to inform programmers reading
your code the reason you did something a certain way or to further clarify
code.

You don't need a comment:

// Add one to variable
$var += 1;

The reason you don't need a comment is because the comment merely restates
what the code already makes clear.

You may need a comment:

switch(true) {
    case false: // this code existed for some time and wasn't documented,
should probably be removed.
         some_function_that_did_things();
         break;
   case $var === true: // Fall through
   case $var === 1:
        do_something_when_true();
        break;
}

The reason you need both comments is to tell developers why you have dead
code area (generally bad practice). Usually when you fall through using a
switch, it is a good idea to inform people that this is intentional.

Dead code is bad practice for the same reason commented out code is bad
practice. You should be using Version Control anyway and if you are, then
you don't need to ever worry about "losing code", because as long as you
commit before you remove, the code will always be there. It might be
difficult to find, but it will always be available.

The reason you could document switch fallthrough is because of C/C++ and
languages that don't allow fallthrough. The coding practice was to always,
always break for each case. Always. The reason was so that you don't forget
and so that the programmer after you can correct your mistake. If you
always do something, then someone knows when you forgot. Why is this
important? Fall through is great because you could put multiple options on
multiple lines, cleaning up the code and allowing the same action to be
performed for all of the options that fall through.

There are no few bugs involving a fall through when there should not have
been. Documenting when you mean for code to fall through helps people
realize when something might not actually be a bug.


The other area where comments are helpful is for you, when you are new to a
concept and need help remembering what code does. Sadly, for me, that is
bitwise operations and remembering why I did a certain action. Even when I
finally realize bitwise operations, I will still write and keep comments,
because those are specific enough that you might have to tell people what
the bitwise operation is supposed to do. These obscure code are ripe for
comments, because they inform you later what you meant when you wrote the
code and it informs other programmers, so they don't look at the code
confused or thinking you made a mistake.

Jacob Santos

Programmer



On Sat, Jul 19, 2014 at 5:29 AM, Haluk Karamete <halukkaramete at gmail.com>
wrote:

> Thanks guys for your input..
>
> I digged this article which also inlines with your insight as to leaving
> the comments in the code is OK.
> phplens.com/lens/php-book/optimizing-debugging-php.php -> Useless
> Optimizations
>
> As to the #, // thing...
> I now know why it would not make sense to use them in a mix and match
> format,
> When it comes to multi-line commenting, surely, going with /* */ is a
> no-brainer.
> But for the single lines, I guess it comes down to individual choice which
> one to adapt or when to use which?
>
> My choice is ...
> I'd like to be able to distinquish the type of comment I'm typing in - so
> I'd be using all 3 in the same file.
>
> /* big section headings */     <- I follow this with 2 or more blank lines
> before or after major sections in the code
> # sub section comments                  <- I use this for sub sections. I
> follow this with only 1 blank line - before or after
> // copy-paste var_dump       <-no lines before or after. this is the only
> one I use on the same line
>
> As I said when it comes to multi-lines, there really is no point to use #
> or //.
>
>
>
>
>
>
> On Fri, Jul 18, 2014 at 10:56 PM, Jacob Santos <wordpress at jacobsantos.com>
> wrote:
>
> > It is discouraged in the coding standards, because you should only use
> one
> > single line comment token. Code should look like it was written by one
> > person, so that developers don't create a mess of the code based on
> > personal preference.
> >
> > If you have code where the comments have '#' sometimes and '//' other
> > times, then it isn't clean and it draws the programmer who is reading the
> > code out of their flow of thought (maybe). Some resources recommend using
> > the other rarely when you have a reason to note something. So, for
> example,
> > if you used '//' all the time and only used '#' only when you had a
> > warning, then it would make sense. The programmer reading the code would
> > understand, eventually, that they need to pay attention to '#'
> characters.
> >
> > In practice, this is rarely done and most programmers reading the code
> are
> > not going to read the coding style guide, so won't know the difference
> > between when to use '#' or '//'. They will just assume that you don't
> know
> > what you are doing or don't have a coding style.
> >
> > As an aside, Python only has '#' for comments and doesn't have a separate
> > token for multiple line comments. Although, you can use """ ... """ for
> > documentation and to comment out large sections of code. The latter is
> > strongly discouraged. I suppose the point is that code should be self
> > documenting, and therefore shouldn't have many comments. What it actually
> > does, is make it a burden to add comments to code, so a lot of code is
> not
> > documented when it should.
> >
> > Jacob Santos
> >
> > Programmer
> >
> >
> >
> > On Fri, Jul 18, 2014 at 10:26 PM, Ankit Tiwari <ankittiwaari at gmail.com>
> > wrote:
> >
> > > Using # for single line commenting is discouraged in wordpress as well
> as
> > > pear coding standards.
> > >
> > > You can use any method from the remaining two, but a common practice is
> > to
> > > comment a single line using // and multiple lines using /**/
> > >
> > > Ankit Tiwari
> > > Open Source Developer
> > > On Jul 19, 2014 2:36 AM, "Nikola Nikolov" <nikolov.tmw at gmail.com>
> wrote:
> > >
> > > > I prefer // for single-line comments and usually go with /**/ for
> > > > multi-line comments(although if I'm quickly commenting a couple of
> > lines
> > > of
> > > > code while I'm working, I'd use the quick insert/remove comment
> > function
> > > of
> > > > Sublime Text and it will just add // at the beginning of all selected
> > > > lines).
> > > >
> > > > I'm not sure if there's a reason why you'd need a minified version of
> > > > WordPress(not sure if the license allows the WordPress source code to
> > be
> > > > obscured in any way) - as far as I know the decreased file size won't
> > > make
> > > > a huge difference in performance or anything.
> > > >
> > > >
> > > > On Fri, Jul 18, 2014 at 11:33 PM, Haluk Karamete <
> > > halukkaramete at gmail.com>
> > > > wrote:
> > > >
> > > > > Commenting is great...
> > > > >
> > > > > But do you have personal guidelines as to which of the 3 commenting
> > > > options
> > > > > that come with PHP when you comment on SINGLE LINES?
> > > > >
> > > > > We got 3 to choose from.
> > > > >
> > > > > #
> > > > >
> > > > > //
> > > > >
> > > > > /*  */
> > > > >
> > > > > There must be a reason why we have 3 choices I'm thinking...
> > > > >
> > > > > And I'm also curious if a leaner version of WordPress (with 0
> > comments
> > > &
> > > > 0
> > > > > unnecessary white space ) has been considered as an optional
> download
> > > for
> > > > > those who choose to do so (from the repository) discussed any
> > earlier.
> > > > >
> > > > > For example, one can choose to download the minified version of
> 3.9.1
> > > per
> > > > > se.
> > > > >
> > > > > I'm just curious how that discussion went - if any.
> > > > > _______________________________________________
> > > > > wp-hackers mailing list
> > > > > wp-hackers at lists.automattic.com
> > > > > http://lists.automattic.com/mailman/listinfo/wp-hackers
> > > > >
> > > > _______________________________________________
> > > > wp-hackers mailing list
> > > > wp-hackers at lists.automattic.com
> > > > http://lists.automattic.com/mailman/listinfo/wp-hackers
> > > >
> > > _______________________________________________
> > > wp-hackers mailing list
> > > wp-hackers at lists.automattic.com
> > > http://lists.automattic.com/mailman/listinfo/wp-hackers
> > >
> > _______________________________________________
> > wp-hackers mailing list
> > wp-hackers at lists.automattic.com
> > http://lists.automattic.com/mailman/listinfo/wp-hackers
> >
> _______________________________________________
> wp-hackers mailing list
> wp-hackers at lists.automattic.com
> http://lists.automattic.com/mailman/listinfo/wp-hackers
>

More information about the wp-hackers mailing list