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
Post by Haluk KarameteThanks 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 //.
Post by Jacob SantosIt is discouraged in the coding standards, because you should only use
one
Post by Jacob Santossingle 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,
Post by Jacob Santosif 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.
Post by Jacob SantosIn practice, this is rarely done and most programmers reading the code
are
Post by Jacob Santosnot 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
Post by Jacob Santoswhat 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
Post by Jacob Santosdocumented when it should.
Jacob Santos
Programmer
Post by Ankit TiwariUsing # for single line commenting is discouraged in wordpress as well
as
Post by Jacob SantosPost by Ankit Tiwaripear coding standards.
You can use any method from the remaining two, but a common practice is
to
Post by Ankit Tiwaricomment a single line using // and multiple lines using /**/
Ankit Tiwari
Open Source Developer
Post by Nikola NikolovI prefer // for single-line comments and usually go with /**/ for
multi-line comments(although if I'm quickly commenting a couple of
lines
Post by Ankit Tiwariof
Post by Nikola Nikolovcode while I'm working, I'd use the quick insert/remove comment
function
Post by Ankit Tiwariof
Post by Nikola NikolovSublime 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
Post by Ankit TiwariPost by Nikola Nikolovobscured in any way) - as far as I know the decreased file size won't
make
Post by Nikola Nikolova huge difference in performance or anything.
On Fri, Jul 18, 2014 at 11:33 PM, Haluk Karamete <
Post by Haluk KarameteCommenting is great...
But do you have personal guidelines as to which of the 3 commenting
options
Post by Haluk Karametethat 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
download
3.9.1
Post by Jacob SantosPost by Ankit Tiwariper
Post by Nikola NikolovPost by Haluk Karametese.
I'm just curious how that discussion went - if any.
_______________________________________________
wp-hackers mailing list
http://lists.automattic.com/mailman/listinfo/wp-hackers
_______________________________________________
wp-hackers mailing list
http://lists.automattic.com/mailman/listinfo/wp-hackers
_______________________________________________
wp-hackers mailing list
http://lists.automattic.com/mailman/listinfo/wp-hackers
_______________________________________________
wp-hackers mailing list
http://lists.automattic.com/mailman/listinfo/wp-hackers
_______________________________________________
wp-hackers mailing list
http://lists.automattic.com/mailman/listinfo/wp-hackers