On Wed, Nov 18, 2015 at 4:49 PM, Adam Williamson
Just as a general note on this thread: if you're a packager and
have a genuine reason why people should be careful about touching your
package, or follow some specific process when doing so, or there's
something that people might think they should change but they
shouldn't, there is already a pretty effective way of dealing with
** PUT A COMMENT IN THE SPEC FILE **
this is extremely easy to do, and extremely difficult for anyone who
touches it to claim they didn't see.
I know this thread is a bit old, but thought I'd add a note when I
checked my backlog and saw it.
A comment in the code accompanying the change itself can also be
invaluable, especially for changes that should propagate upstream.I
cannot count the number of patches that have *nothing* in the patch
content, only in the comments preceding the patch itself. I'm
personally exhausted with people who refuse to document, whose API has
to be deduced from the code, and especially whose code could fit
*mutliple* workflows. And worse, when the API they think they're using
isn't the one they've actually written, and they get upset when you
don't code to this non-published API.
That's cost me a job I rather liked.
Package builds in a community distro are really just like F/OSS
you should assume other people are going to be looking at it and poking
it and trying to do stuff with it, and any time it's doing something
that isn't extremely obvious or diverges from the general conventions,
it makes sense to comment it.
Yes, lordie, please, "the code is the documentation" is an attitude
I've encountered far, far too often, and I consider it the sign of a
dangerous programmer. It's afraid it's a job security thing: by
refusing to document you protect your turf.