Maybe, just maybe @decorator syntax is ok after all

[Peter Hansen]

Michael Ekstrand wrote:
> Much of that can be accomplished stylistically in the way comments are 
> written (granted, that doesn't accomplish much for existing code that 
> doesn't follow such conventions). But, for example, in my C/C++ code, I 
> always have comments before my functions like so:
> 
> /*
>  * FooClass::foo()
>  *
>  * Fooifies the FooClass instance
>  */
> int FooClass::foo(int parm1, char parm2, char *spam_name)
> ...
> 
> Much of the problem (in any language, then) goes away. You still run 
> into problems with existing code, though.

But it brings other problems.  There's a principle called DRY,
for Don't Repeat Yourself, which comes from observations that
*any* repetition will lead to maintenance problems and other
difficulties, especially when refactoring code.  And I can't
count the number of times I've seen comments such as the above
which were wrong, either through name changes or because of
the inevitable cut-and-paste errors.

At my last place of employment, we abolished all redundant
comments, such as those containing the name of the function or
module.  The code got much shorter and cleaner.

-Peter