This is the mail archive of the
gcc-patches@gcc.gnu.org
mailing list for the GCC project.
Re: Objective C/C++ Compiler Drivers
On Wed, 8 Sep 2010, Philip Herron wrote:
> I'm not quite sure does that mean you looked at it or not? And does
I began looking at it but rapidly found it wasn't in a state that was
worth my while looking at.
When sending patches to the lists, the patches should be aimed primarily
at a human reader - what's important is making it clear to people what the
patch does and why, and the details of the code itself should be
secondary; readability is the most important attribute of almost all code
that anyone is ever going to have to read or maintain in future. I look
first at:
* The patch write-up in the body of the message. For changes to
complicated code with subtle effects on semantics in existing corner
cases, I often find it takes several hours' analysis before starting work
on the patch to identify these cases, and a few hours more to write up the
details of the patch (having kept notes as I went along of issues found
during implementation); there are plenty of examples in my option handling
patch series, e.g.
<http://gcc.gnu.org/ml/gcc-patches/2010-08/msg01399.html>.
* The changes to the documentation. This sort of thing often may not make
any changes that would require adjusting user documentation - making the
write-up increasingly important.
* The new testcases or changes to testcases. The sort of corner cases
such a patch affects may be hard to cover in the testsuite - making it
increasingly important to detail them in the write-up.
* The internal datastructures and interfaces and comments in the patch
that provide a high-level overview of the design being used. At the point
where I saw new functions without their parameters explained, and comments
not formatted in the standard way, I stopped looking at the patch.
Only after this point - if everything above is satisfactory - do the
details of the code become relevant. Code extracts showing the
datastructures and function prototypes with full detailed comments are
much more useful than function bodies without explanation.
> that mean you want a patch that starts implementing/changing the
> existing compiler drivers to use these new shared functions?
Exactly. Whenever you find too many corner cases of behavior might be
affected, that's a sign that you need smaller incremental patches -
possibly having a patch that explicitly fixes a corner case first, before
a patch introducing the use of new infrastructure without changing the
behavior on that case. The minimal step might be a new interface for
appending new or modified options to an array (that automatically resizes)
- with no changes at all to what options get appended in what conditions,
just the removal of code in the various drivers that tries to work out
exactly how many options it will end up adding, in order to allocate
space, separately from adding those options.
--
Joseph S. Myers
joseph@codesourcery.com