Document how to contribute private things

[lvh]

The CONTRIBUTING file, once merged, suggests PEP 8, which suggests underscores:

Even with __all__ set appropriately, internal interfaces (packages, modules, classes, functions, attributes or other names) should still be prefixed with a single leading underscore.

However, on the initial repo pull request, @alex commented:

I hate naming modules with an underscore prefix. I think not documenting c should be enough. I agree that OpenSSL is an implementationd etail.

FWIW, I disagree on both counts:

• I love the _ prefix because it's unambiguous and impossible to miss. A note in a module somewhere is easy to miss, and no note at all even easier :)
• Undocumented is not the same as private, it's just undocumented.
• Private things ought to be documented too (particularly since we're doing crypto, and using things the wrong way is typically disastrous)

... but that's just my two satoshis.

Either way, this should be documented in the CONTRIBUTING file.

[hynek]

I rather like explicit _ everywhere too.

[alex]

I like _ everywhere except module names, but if everyone disagrees with me I'm happy to be overruled.

[dreid]

+1 for _ in module names.

[Ivoz]

everything that's intended to only be used internally should be 'behind' a _ at some point, whether module, class, method or attr. It clearly delineates what is for public consumption and what isn't.

Go does this on a syntax level with Uppercase and lowercase symbols, and I think that works brilliantly for creating clear APIs; and _ is python's equivalent convention.

Also helps make things clear when someone is doing API discovery through dir() >_>

My 2c

[reaperhulk]

Our conventions have become relatively clear in the past 6 months so I'm closing this bug for now. If there's anything left to discuss feel free to reopen it!