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

Jacob Santos wordpress at jacobsantos.com
Sat Jul 19 05:56:10 UTC 2014


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
>


More information about the wp-hackers mailing list