https://bz.apache.org/SpamAssassin/show_bug.cgi?id=7981
--- Comment #24 from Michael Storz <sa-...@lrz.de> --- (In reply to Loren Wilton from comment #22) > > 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. Loren, you are absolutely right, it needs to be documented what return codes are expected and what role got_hit and rule_ready play. And that people just take a plugin and deduce how to write a plugin instead of reading the documentation is also my experience after 46 years of programming :-) (started with Fortran IV on a CDC 6600 and a Cyber 176 from Control Data). So I have been thinking for the last hours how such a description can look like. Unfortunately, an exact description can't be written down in 10 lines. But you can surely make an extract of it and add a link to the exact description. -- You are receiving this mail because: You are the assignee for the bug.
