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

Jacob Santos wordpress at jacobsantos.com
Sat Jul 19 19:32:37 UTC 2014 

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 <wordpress at jacobsantos.com>
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 <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