Improve coder_format to re-format Drupal 6 core without wrong formatting

[GoogleCodeExporter]

One of the things that has an great impact on Drupal's success is the
widely adopted agreement on clean, sophisticated, and well-documented code.
In an abstract view, we are not only using a language (PHP), but also using
a dialect to articulate what we are doing. This means that core developers
and most contrib module maintainers try to ensure that everyone else in the
community understands all parts of the application and is able to fix or
improve the code without language barriers. Without this solid ground, no
one would be able to participate and contribute in the way the Drupal
community members are doing. Many patches against Drupal core are held back
or even rejected because of unsuitable code.

To support developers in using the proper syntax, formatting, naming, and
adhering to all other development guidelines for Drupal, the Code Review
module [1] has been developed, which outputs notices for all code that is
considered wrong in terms of Drupal Coding Standards [2]. While Coder does
only a code review and leaves you with the results, there is also the
coder_format script shipped with the Coder module, that strives to clean
and re-format a whole file to adhere to Drupal's Coding Standards.

Cleaning the coding-style of a contributed module with coder_format is
usually a 5-minute job. Coder_format can be run recursively on all files in
a directory by invoking it with the --batch-replace argument. See inline
documentation in coder_format.php for further information.

However, due to its current beta-state, there are situations where
coder_format applies wrong formatting to some lines or all lines that
follow some lines of complex syntax in a file.

* The goal of this GHOP task is to fix and improve the coder_format script,
so that it can be applied recursively on Drupal 6 core without introducing
wrong formatting (and fixing existing wrong formatting throughout Drupal
core, of course).

* The result of this GHOP task must be a single patch file against
coder_format.inc that is ready to be committed. To clarify in advance: not
a patch against Drupal core -- Patch files against Drupal core are only
needed to communicate the current results/errors of coder_format in this issue.

* To work on this task, you should have a local development environment, be
able to run a PHP script from the command line, know how to access a CVS
server, and how to checkout and create patches against a CVS module. You
should have a (better good) visual diff tool to compare a resulting file
with the original.

* You will have to deal with rather complex regular expressions, Drupal
Coding Standards, reviewing of Drupal core (with and without Coder module),
creating and applying patches, writing helpful inline documentation, and
identifying wrong formatting.

Resources

* First of all, inline documentation in the coder_format script [3].
* Drupal Coding Standards [4] (see also more up to date doc in CVS [5]).
* Coder's issue queue [6] which contains some very valuable information
about proper coding-styles (use Advanced Search to find older
issues).
* PHP's Tokenizer [7] and Tokenizer Tokens [8] which are used to identify
PHP's syntax.
* regular-expressions.info [9] provides a great resource for regex-related
questions and howto's, you will
probably need.
* If you are working on Windows, you might additionally use the
coder_format Windows installer [10], which I'll update with an improved
version when this task has been claimed.

Primary contact
Daniel F. Kudwien (sun) [11]

I'm pretty sure that fellow Drupallers like Doug, Stella, Core developers,
subscribers of the Coding Standards Group [12] and also developers in the
#drupal and #drupal-ghop IRC channels will help out on any questions
related to missing information about Drupal Coding Standards.

Please bear in mind that coder_format is already performing quite well. So
the referenced resources about coding standards are only necessary to find
out how something should look like if there are any wrong formatting. It is
quite hard to believe that the attached patch is already based on a
completely re-formatted Drupal core, which means that all files have been
re-written by coder_format.

Pre- and post-processors are already part of the script, so the mentioned
post-processor for cleaning up lines containing only white-space is
definitely not a big deal. Also, the mentioned bug in drupal_urlencode() is
clearly caused by the pre-processor coder_preprocessor_inline_comment().

References

[1] http://drupal.org/project/coder
[2] http://drupal.org/coding-standards
[3]
http://cvs.drupal.org/viewvc.py/drupal/contributions/modules/coder/scripts/coder
_format/coder_format.inc?revision=1.2&view=markup
[4] http://drupal.org/coding-standards
[5]
http://cvs.drupal.org/viewvc.py/drupal/contributions/CODING_STANDARDS.html?conte
nt-type=text%2Fhtml&view=co
[6] http://drupal.org/project/issues/coder
[7] http://php.net/manual/ref.tokenizer.php
[8] http://php.net/manual/tokens.php
[9] http://www.regular-expressions.info/tutorial.html
[10] http://drupal.org/node/149826
[11] http://drupal.org/user/54136
[12] http://groups.drupal.org/coding-standards-and-performance-optimization

Original issue reported on code.google.com by acli...@gmail.com on 11 Jan 2008 at 6:02

[GoogleCodeExporter]

I claim this task.

Original comment by edwardzy...@gmail.com on 16 Jan 2008 at 3:50

[GoogleCodeExporter]

Ok edwardzyang, it's yours.  Remember, last date to claim a task is next 
Monday...so
work work work :)

Original comment by acli...@gmail.com on 16 Jan 2008 at 3:53

• Changed state: Claimed
• Added labels: ClaimedBy-edwardzyang, DueDate-2008-01-22

[GoogleCodeExporter]

Per http://drupal.org/node/208767#comment-699321, marking this task closed. 
Great
job, ezyang!! :)

Original comment by webchick...@gmail.com on 21 Jan 2008 at 5:28

• Changed state: Closed

[GoogleCodeExporter]

Edward accidentally logged in under a different username for this task. 
Switching the
ClaimedBy to his original address so this counts as credit against his other 
tasks.

Original comment by webchick...@gmail.com on 21 Jan 2008 at 7:11

• Added labels: ClaimedBy-edwardzy...thewritingpot.com
• Removed labels: ClaimedBy-edwardzyang

[GoogleCodeExporter]

Here is a smörgåsbord of patches that represent the best of this task's work. 
The
process spanned multiple commits and lots of bouncing back and forth ideas.

Original comment by edwardzy...@thewritingpot.com on 21 Jan 2008 at 7:12

Attachments:

• coder_format.zip
• coder_format.inc-4.patch
• coder_format-16.patch

[GoogleCodeExporter]

Original comment by acli...@gmail.com on 21 Jan 2008 at 3:59

• Added labels: AdminChecked