https://bz.apache.org/SpamAssassin/show_bug.cgi?id=7981
Loren Wilton <lwil...@earthlink.net> changed:
What |Removed |Added
----------------------------------------------------------------------------
CC| |lwil...@earthlink.net
--- Comment #22 from Loren Wilton <lwil...@earthlink.net> ---
> This is necessary because it was not clear before and the plugins do not
> return the correct codes in many places. I now have changes for about 25
> plugins.
Henrik, if I might make a suggestion: When you patch these 25 (or I assume
more) plugins to return the correct values, could you include in the patch a
boilerplate description of the "proper return values" for the various common
scenarios? I'm envisioning something like 4 to 10 lines of boilerplate comment,
so nothing huge. This could be put near the front of the plugin where someone
working on the plugin would have a good chance of seeing it when first touching
the code.
I suspect the alternative to having a comment in each module is to assume that
anyone patching the plugin will know that the current return values are correct
in all cases, and will correctly deduce the rule from reading the code. From
about 50 years of coding experience I consider this a suspect idea. Given that
a lot of return values are wrong now, it seems unlikely that authors will
intuit the correct return values, or assume the code they are looking at is
correct.
An alternative is to put these values in some wiki or documentation page on
some web site. That might be a good thing to do, but I strongly suspect that
most people that want to make a plugin are just going to grab an existing
plugin and modify it, and will have no clue that external documentation exists.
I know adding documentation in code is burdensome when coding, but from the
previously mentioned 50 years of being a coder, I've found that it is a lot
more effective than assuming a newbie will intuit the interfaces correctly from
raw code.
--
You are receiving this mail because:
You are the assignee for the bug.
