Coding style change proposals

[Augie Fackler]

On Sat, May 13, 2017 at 03:07:00PM -0700, Sean Farley wrote:
> 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.

I'd like to allow it - I think it's a lot easier, and can imagine it
makes an even bigger difference for nonnative speakers. I'd be in
favor of this.

>
> > 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).

Given that we already have a mix, I'd like to propose that we embrace
UPPERCASE for all new constants, and don't bother rewriting existing
ones until we have a good way for blame to skip revisions (which I
know Sid still plans to finish).

>
> > 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.

I don't feel strongly - on the whole I think I'd like to be more
standard going forward.

>
> > 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.
>

Indeed. At least for now.

> _______________________________________________
> Mercurial-devel mailing list
> Mercurial-devel at mercurial-scm.org
> https://www.mercurial-scm.org/mailman/listinfo/mercurial-devel