do you guys distinquish between various PHP commenting options?

classic Classic list List threaded Threaded
8 messages Options
Reply | Threaded
Open this post in threaded view
|

do you guys distinquish between various PHP commenting options?

Haluk Karamete
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
[hidden email]
http://lists.automattic.com/mailman/listinfo/wp-hackers
Reply | Threaded
Open this post in threaded view
|

Re: do you guys distinquish between various PHP commenting options?

Nikola Nikolov
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 <[hidden email]>
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
> [hidden email]
> http://lists.automattic.com/mailman/listinfo/wp-hackers
>
_______________________________________________
wp-hackers mailing list
[hidden email]
http://lists.automattic.com/mailman/listinfo/wp-hackers
Reply | Threaded
Open this post in threaded view
|

Re: do you guys distinquish between various PHP commenting options?

J.D. Grimes
In reply to this post by Haluk Karamete
For single line comments, use //. I couldn’t find it in the coding standards (http://make.wordpress.org/core/handbook/coding-standards/php/), but I think # is discouraged. At any rate, // is what is generally used in core. The /* */ comments are extra writing, unless your comment has to be in the middle of a line of code (which it almost never does), so you need to close it.

As far as minifying the PHP source, this would reduce download time, but it would also increase confusion, and make debugging more difficult. WordPress core isn’t that large, so it isn’t worth it. Even if a user is never going to be looking at the code, if they get an error it is easier to help them debug if the line the code is coming form is unambiguous. All you need to know now is the version. If minified code was offered, then you’d also need them to tell you whether they had the minified version or not, which they probably wouldn’t even know. One of the great things about WordPress is it’s very low entry point for new developers. Minifying the code would make it a lot harder for someone to just start hacking on their site. And actually, now many web hosts provide a one-click installer thingy, so many users aren’t even downloading the source to start with.

-J.D.

On Jul 18, 2014, at 4:33 PM, Haluk Karamete <[hidden email]> 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
> [hidden email]
> http://lists.automattic.com/mailman/listinfo/wp-hackers

_______________________________________________
wp-hackers mailing list
[hidden email]
http://lists.automattic.com/mailman/listinfo/wp-hackers
Reply | Threaded
Open this post in threaded view
|

Re: do you guys distinquish between various PHP commenting options?

Ankit Tiwari
In reply to this post by Nikola Nikolov
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" <[hidden email]> 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 <[hidden email]>
> 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
> > [hidden email]
> > http://lists.automattic.com/mailman/listinfo/wp-hackers
> >
> _______________________________________________
> wp-hackers mailing list
> [hidden email]
> http://lists.automattic.com/mailman/listinfo/wp-hackers
>
_______________________________________________
wp-hackers mailing list
[hidden email]
http://lists.automattic.com/mailman/listinfo/wp-hackers
Reply | Threaded
Open this post in threaded view
|

Re: do you guys distinquish between various PHP commenting options?

Jacob Santos-3
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 <[hidden email]>
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" <[hidden email]> 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 <
> [hidden email]>
> > 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
> > > [hidden email]
> > > http://lists.automattic.com/mailman/listinfo/wp-hackers
> > >
> > _______________________________________________
> > wp-hackers mailing list
> > [hidden email]
> > http://lists.automattic.com/mailman/listinfo/wp-hackers
> >
> _______________________________________________
> wp-hackers mailing list
> [hidden email]
> http://lists.automattic.com/mailman/listinfo/wp-hackers
>
_______________________________________________
wp-hackers mailing list
[hidden email]
http://lists.automattic.com/mailman/listinfo/wp-hackers
Reply | Threaded
Open this post in threaded view
|

Re: do you guys distinquish between various PHP commenting options?

Haluk Karamete
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 <[hidden email]>
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 <[hidden email]>
> 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" <[hidden email]> 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 <
> > [hidden email]>
> > > 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
> > > > [hidden email]
> > > > http://lists.automattic.com/mailman/listinfo/wp-hackers
> > > >
> > > _______________________________________________
> > > wp-hackers mailing list
> > > [hidden email]
> > > http://lists.automattic.com/mailman/listinfo/wp-hackers
> > >
> > _______________________________________________
> > wp-hackers mailing list
> > [hidden email]
> > http://lists.automattic.com/mailman/listinfo/wp-hackers
> >
> _______________________________________________
> wp-hackers mailing list
> [hidden email]
> http://lists.automattic.com/mailman/listinfo/wp-hackers
>
_______________________________________________
wp-hackers mailing list
[hidden email]
http://lists.automattic.com/mailman/listinfo/wp-hackers
Reply | Threaded
Open this post in threaded view
|

Re: do you guys distinquish between various PHP commenting options?

Jacob Santos-3
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 <[hidden email]>
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 <[hidden email]>
> 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 <[hidden email]>
> > 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" <[hidden email]>
> 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 <
> > > [hidden email]>
> > > > 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
> > > > > [hidden email]
> > > > > http://lists.automattic.com/mailman/listinfo/wp-hackers
> > > > >
> > > > _______________________________________________
> > > > wp-hackers mailing list
> > > > [hidden email]
> > > > http://lists.automattic.com/mailman/listinfo/wp-hackers
> > > >
> > > _______________________________________________
> > > wp-hackers mailing list
> > > [hidden email]
> > > http://lists.automattic.com/mailman/listinfo/wp-hackers
> > >
> > _______________________________________________
> > wp-hackers mailing list
> > [hidden email]
> > http://lists.automattic.com/mailman/listinfo/wp-hackers
> >
> _______________________________________________
> wp-hackers mailing list
> [hidden email]
> http://lists.automattic.com/mailman/listinfo/wp-hackers
>
_______________________________________________
wp-hackers mailing list
[hidden email]
http://lists.automattic.com/mailman/listinfo/wp-hackers
Reply | Threaded
Open this post in threaded view
|

Re: do you guys distinquish between various PHP commenting options?

Jacob Santos-3
I suggest reading Clean Code for more on when comments are needed and not
needed. I don't believe the author goes to deeply into this subject as it
is mostly subjective. I believe most of what is said, is contained in my
previous email. You don't have to follow everything in Clean Code, because
some of the suggestions may violate coding standards and practices of the
team you are on.

Read and have an open mind. The book contains concepts from professionals
that, if you practice, will put you on the same level as professionals and
in some cases, above them. If you code this way, then few people will doubt
your level. There are code smells which may also make you a better
programmer.

Jacob Santos


On Sat, Jul 19, 2014 at 2:17 PM, Jacob Santos <[hidden email]>
wrote:

> 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 <[hidden email]>
> 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 <[hidden email]
>> >
>> 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 <[hidden email]>
>> > 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" <[hidden email]>
>> 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 <
>> > > [hidden email]>
>> > > > 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
>> > > > > [hidden email]
>> > > > > http://lists.automattic.com/mailman/listinfo/wp-hackers
>> > > > >
>> > > > _______________________________________________
>> > > > wp-hackers mailing list
>> > > > [hidden email]
>> > > > http://lists.automattic.com/mailman/listinfo/wp-hackers
>> > > >
>> > > _______________________________________________
>> > > wp-hackers mailing list
>> > > [hidden email]
>> > > http://lists.automattic.com/mailman/listinfo/wp-hackers
>> > >
>> > _______________________________________________
>> > wp-hackers mailing list
>> > [hidden email]
>> > http://lists.automattic.com/mailman/listinfo/wp-hackers
>> >
>> _______________________________________________
>> wp-hackers mailing list
>> [hidden email]
>> http://lists.automattic.com/mailman/listinfo/wp-hackers
>>
>
>
_______________________________________________
wp-hackers mailing list
[hidden email]
http://lists.automattic.com/mailman/listinfo/wp-hackers