Coding style change proposals

[Sean Farley]

Gregory Szorc <gregory.szorc at gmail.com> writes:

> I'd like to formally propose some changes to the code style in order to
> make the code more readable, similar to other Python projects, and more
> friendly to non-English speakers.
>
> I think each naming proposal below can be considered independently. So
> please don't wholesale reject this email because you don't agree with one
> part.
>
> Proposal 1: use underscores in names. Today, our names are
> "anamewithoutanypunctuation." I want to change that to
> "a_name_with_punctuation." This is vastly easier to read, especially for
> non-English speakers and is similar to how the rest of Python does it.

Hmm, I'm not sure it's easier to read, personally. But I wouldn't block
this one either.

> Proposal 2: uppercase constants. Right now, constants are a mix of
> lowercase with some exceptions using uppercase. I'd like to standardize on
> using uppercase for all constants. Since Python doesn't really have the
> concept of constants, differentiating constants via naming helps reinforce
> that they are not regular, local scope variables. If I see mutation of an
> UPPERCASE variable when doing code review, that's a quick sign that
> something is wrong. It's harder to do that when the name is lowercase.
> Uppercase constants is how most of the Python universe does it.

I agree with this (and am a bit surprised we don't already do that).

> Proposal 3: CamelCase class names. Today, all names are lowercase except
> for error classes. I'd like to switch to CamelCase class names. This will
> help differentiate variables and functions from types, which improves
> readability. This is how most of the Python universe does things.

I'm most unsure about this one. I kind of like 'context' as lowercase.

> If we adopt any of the proposals, a question becomes what to do about
> reformatting existing code. We can't easily do that because of API
> compatibility concerns. For internal names, we could certainly do that. But
> for public and more common APIs, we should be conservative so we don't
> break the world. I propose using the new style for new code and updating
> the style for old code when making significant changes. e.g. if you are
> rewriting a function, you would update names within first, then refactor.
> Or, you would refactor, updating names inline, and write a follow-up patch
> to clean up remaining names for consistency. This will result in mixed
> style throughout the code base, which is ugly. But I think we can manage
> until we're willing to take a mass API breakage hit.

Man, this is hard. I'm not too sure how much this is worth it for so
much code churn.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 800 bytes
Desc: not available
URL: <http://www.mercurial-scm.org/pipermail/mercurial-devel/attachments/20170513/6b165d81/attachment.sig>