[drupal-devel] [feature] Remove ?>
Morbus Iff
drupal-devel at drupal.org
Fri Aug 26 20:30:59 UTC 2005
Issue status update for
http://drupal.org/node/29385
Post a follow up:
http://drupal.org/project/comments/add/29385
Project: Drupal
Version: cvs
Component: other
Category: feature requests
Priority: normal
Assigned to: chx
Reported by: chx
Updated by: Morbus Iff
Status: patch (ready to be committed)
chx: ANY tricky code needs to be commented. If a piece of code makes you
go "hmmm...", then yes, it needs to commented. Unlike, however, our
internal documentation which can be traced to a solution (for your
bracket/SQL example), there is no traceable way to find why the ?> is
missing. Sure, I could spend an hour Googling around, just like I could
spend a month reading everything about regexps to try and decipher what
the hell is going on with an uncommented core regexp. But this is why
every language has a commenting feature: to explain tricky code. This
code is "tricky" because it makes people ask questions, it is not
immediately obvious, nor has it affected every single user out there.
Likewise, it's certainly not a popular snippet that can be seen in tons
of other pieces of PHP coding.
Likewise, you talk about this like it's some sort of major feature that
everyone should be aware of. If we go back to Gabor's page on php.net
(http://us3.php.net/basic-syntax.instruction-separation), you'll notice
that it is merely a "Note". If this were really a full-fledged feature,
as opposed to just "something you could do", it'd be a lot more than a
"Note". A "Note" is something you say "Oh, yeah, you could also...", a
side effect, a clarification of something else entirely.
And finally, Gabor's page, assuming people do find it by browsing
through Google, doesn't even explain why WE, Drupal, are choosing to do
this - it's an off the cuff "oh, yeah, it's optional, and occasionally
useful when you use includes". The impression people will get is that
it's an optional stylistic trick, NOT that it is actually fixing a bug.
Because of this, it'll become equivalent as check_markup: few third
party modules will actually use it because no one understands WHY they
should.
Morbus Iff
Previous comments:
------------------------------------------------------------------------
Mon, 22 Aug 2005 13:37:25 +0000 : chx
Attachment: http://drupal.org/files/issues/no_question_more_at_the_end.patch (20.22 KB)
I finally decided that it's best to remove all ?> from the end of all
files. I set this to ready to be commited as there is not a single line
of code which is modified and we have debated this to death on the devel
list.
TODO: update the coding style guidelines.
------------------------------------------------------------------------
Tue, 23 Aug 2005 01:55:21 +0000 : Uwe Hermann
Patch applies, seems to work (a quick check trying various things on a
test-site succeeded).
------------------------------------------------------------------------
Thu, 25 Aug 2005 21:13:51 +0000 : Dries
Committed to HEAD. Marking this 'active' until the coding guidelines
have been updated.
------------------------------------------------------------------------
Fri, 26 Aug 2005 05:22:10 +0000 : chx
Attachment: http://drupal.org/files/issues/leftovers.patch (1.77 KB)
I have not patched *.php so that templates won't get hurt. But this
meant a few files are left out... here.
------------------------------------------------------------------------
Fri, 26 Aug 2005 17:11:14 +0000 : Thomas Ilsche
What do you think about leaving a comment at the end of every file like
// end tag intentionally omited
------------------------------------------------------------------------
Fri, 26 Aug 2005 18:47:36 +0000 : Uwe Hermann
+1. This will prevent lots of questions in the forums...
------------------------------------------------------------------------
Fri, 26 Aug 2005 18:57:04 +0000 : Morbus Iff
No, it won't. It'll just turn "why is the thing missing" to "so, uh,
what's the reason it''s missing?" Intent has nothing to do with
explanation. If we include a comment like this, we should include a
page in the docs explaining exactly why, and then include that URL in
the comment. Only then will it pre-empt questions.
------------------------------------------------------------------------
Fri, 26 Aug 2005 19:08:31 +0000 : webchick
Even better would be something like:
// end tag intentionally omitted - see
http://lists.drupal.org/archives/drupal-devel/2005-08/msg00648.html
Note: 2 "t"s in omitted.
This would stop both the "Hey, you guys forgot to put ?>s at the end of
your files!" as well as the "Hey, WHY is the end tag intentionally
ommitted?"
The only problem is that's now an extra ~100 bytes X however many core
files there are + contrib module files, etc.
I agree that this information definitely needs to be available (and in
a very prominent place) in order to address forthcoming
questions/concerns, but I'm not sure if appending to the end of each
file is necessarily the best way...
------------------------------------------------------------------------
Fri, 26 Aug 2005 19:14:35 +0000 : kbahey
Angela.
I was just thinking the same thing.
A better arpproach would be to summarize the mailing list dicussion to
a Drupal.org page in the FAQ section, and point to it.
// End PHP tag intentionally omitted. See
http://drupal.org/faq/something for details.
------------------------------------------------------------------------
Fri, 26 Aug 2005 19:21:58 +0000 : nedjo
An FAQ addition is a good idea, but I think we can safely document and
not append a message. The same message in every file is bloat (unless
it's needed for e.g. licensing). People will figure it out.
------------------------------------------------------------------------
Fri, 26 Aug 2005 19:29:01 +0000 : Morbus Iff
Well, if we're not gonna have an explanatory message inline, I'd prefer
something like:
<?php
//
?>
commented; see
http://drupal.org/faq/tricky_code_that_requires_explanation
?>
Note: I'm still not a fan of this ;)
------------------------------------------------------------------------
Fri, 26 Aug 2005 19:30:00 +0000 : Morbus Iff
Grr. Well, that screwed up. Sure wish Preview worked ;) Let's try this:
// ?> http://drupal.org/faq/tricky_code_that_requires_explanation
------------------------------------------------------------------------
Fri, 26 Aug 2005 20:15:50 +0000 : chx
Folks, this is simply silly. Next what, we add a comment to every single
SQL query explaining what's {} around the table names? (It's not in the
db_query docs, it is in db_prefix_tables.)
Or we begin to pick label some features of the PHP language as
"strange" and comment them like no tomorrow? For example the
"alternative syntax" in templates? Heredoc syntax (if we use that at
all)? Write lengthy essays about what our pregs do just because they
are hard to understand? Forget this but please commit my patch :)
More information about the drupal-devel
mailing list