Re: New: CR16 Port (Take 3)

["Joseph S. Myers" <joseph at codesourcery dot com>]

On Wed, 26 Sep 2007, Michael Meissner wrote:

> 2) You have no comments for each of the standard macros.  Its up to you, but I
>    generally find it easier when hacking on a port to have the defintion of the
>    macro in comments, so that I don't have to refer to the documentation of
>    each individual field.

Definitions of standard macros should only have comments where there's 
something to say about that port's definition of the macro.

They should not have comments duplicating the documentation of the general 
semantics of that macro from the manual; such comments inevitably get out 
of date as the manual changes, ports are far too full of comments pasted 
from a variety of old manual versions.

Copies of default definitions of macros, or commented-out definitions of 
macros, are even worse; they interfere with searching to see what ports 
use a particular feature if most of what turns up are ports not doing 
anything different from the default.

If you start with a template with generic comments and definitions when 
writing a new port, all the generic comments and default or commented-out 
definitions should be removed before contributing that port.

-- 
Joseph S. Myers
joseph@codesourcery.com