consistent variable names and capitalization

[wholmgren]

Let's try to agree on the variable names and capitalization rules for all terms in the library. PEP8 is a good place to start, but it may be reasonable to break those rules for some terms.

I don't expect that we can come to agreement on everything in this issue, but let's at least write down the terms and rules for which we do agree and change the code to reflect whatever consensus emerges.

A wiki would probably be a good place to put the results.

In no particular order, here are some problems that I'm aware of:

• Acronyms such as DNI, GHI, DHI, AOI.
• Beam irradiance and similar could be Eb, beam, beam_irrad, irrad_beam. I know that at least two those are currently in use.
• diffuse, sky_diffuse, diffuse_ground, In_Plane_SkyDiffuse, aoi_projection, etc.
• airmass, AM, or am? I think we may be using all three. How do we use a modifier like relative or absolute?
• lat, latitude
• tz, TZ
• surf_az, surfazi, surfaceazimuth
• Variables that are closely tied to a particular equation (see many of the pvsystem functions).
• temp, T, Tcell.
• Vmp, V_mp, vmp, v_mp.

Fixing this without breaking things requires good tests.

[uvchik]

I would use existing conventions like PEP8 because this is easier for new contributors. For variable names I like the convention table of pylint: http://pylint-messages.wikidot.com/messages:c0103

Pylint is a program to check your code. It marks all lines where you broke the rules. You can integrate pylint in many IDEs or editors (http://docs.pylint.org/ide-integration) or use it as a standalone tool to check your modules.

Breaking the rules makes it more difficult for contributors from other projects.

But it's your project, if the convention is clear I will keep to the code.

[wholmgren]

I'll put a few of my preferences here, going from perhaps least to most controversial.

Everything that is not an acronym or a complicated variable in an equation should be lower case. This is just good PEP8, and most of the code actually follows this already. Of the list above, the only change would be that In_Plane_SkyDiffuse becomes in_plane_skydiffuse or similar.

Airmass should just be called airmass since it's one word and it's not that long.

Up to about 10 characters, I prefer longer names to shorter names. So, I prefer to spell out words like latitude and longitude.

I like diffuse_ground over e.g. diff_gr, but I like surf_az over surface_azimuth. I can't justify this.

I would make most (all?) acronyms lowercase, including dni, ghi, aoi, tz, etc.

Use of terms like V_mp should minimized, but it's probably unavoidable for complicated variables in complicated equations and I'm not sure what the appropriate rules should be.

We may also consider that rules for parameters and returned values could be different than rules for the code. Abbreviations and acronyms can make code more readable.

@uvchik It's very much a community project, a few of us just have push privileges.

[bmu]

It would be great, if we could agree on naming conventions! And we could have something like a table of definitions in the wiki or documentation.
In a first step these definitions coul be used by developers.

As an idea, they could possibly also be used by users in the future, if we would switch to dataframe inputs for some functions or a different kind of api. This would enable us to include som e "magic" functions, e.g the signature of the ominous globalinplane function could look like this:

def globalinplane(df, surface_tilt, surface_azimuth, diffuse_model='perez', 
                  decomposition_model=None):
    """Determine GPOA from either GHI and DHI or from GHI only

    Parameters
    ---------------
    df : pandas.DataFrame
          A DataFrame containing all necessary columns acoording to naming conventions
          (maybe surface_tilt and surface_azimuth could also be contained in the df, 
           e.g. for tracking systems.) 
    decomposition_model : None or str
          The model to use if only GHI is given in the DataFrame
    ....
    Returns
    -------
    The input DataFrame plus columns `direct tilted`, 'diffuse tilted`, `GPOA` ...
    """"

This function could look which columns are in the DataFrame and compute all necessary columns (e.g. if time is given as local time, compute utc or true solar time).

From my experience this is usefull for beginners because there are quite a lot of simulation steps required to calculate GPOA from GHI (maybe convert times, decomposition in direct and diffuse, diffuse model, ground reflection, direct tilted, ...?).
And there are other options, e.g. claculate expected energy yield from only a system description, Location and a DataFrame containing GHI and ambient temperature.

This is just an idea, not sure about the difficulties. There may be some complexity when implementing something like this (more on the definitions, not necessarily from a programmers point of view) and maybe this is difficult to explain to users.

[bmu]

For pylint we could include a pylintrc in the repository (maybe also for other code checkers like pep8, pyflakes ... or decide which one we want to use).

[wholmgren]

Yes, I would really like to see some new high level functions that utilize the API and standardizing names will make this much easier. I'll suggest a new issue(s) for scoping out those functions, though.

I'm ok with adding a pylintrc or similar file, but I want to be pragmatic about this. I think that using good PEP8 practices for API-relevant things is a lot more important than removing extra spaces from the end of lines or putting spacings between every operation or after item in list (which can often reduce readability, in my opinion). I think that the important PEP8 rules are too often drowned out by many silly violations. Maybe you all have had better experiences and can show me the way.

[uvchik]

1. I agree with @wholmgren, that it is easier to read the code if the variables are spelled out. Abbreviations are okay for often used phrases like diffuse but we should avoid them. Standard acronyms are okay for me. Maybe we could create a table with the most important variable names, so that we and all new developers get an overview of how the naming works. Example: Variables-and-style-rules
2. I really like the rules, even though my own rules would be different. But everybody has his own preferences and discussions about these rules can be very long. I my experience it is very useful to follow PEP8, because you get used to that style. After a while it was a lot easier for me to read foreign PEP8-code then non-PEP8-code. The less exceptions, the less discussions, the less confusion.
3. I definitely like the idea of @bmu to write a magic globalinplane function, but could you create a new issue (feature) for that.

[wholmgren]

The table is a good start. Can you keep going with your specific suggestions for the rest of the parameters discussed above? I'll add mine after that. I think we all agree that we should follow pep8 but that still leaves room to differ on some parameters.

[robwandrews]

Hi Folks, I agree with the conversation above, and think that for the majority of the time we should be sticking to PEP8.

However, another topic came into this thread, which is to look at implementing a dataframe input method for the functions. This is a topic that came up earlier in the project, that we decided to steer away from, though it could be revisited. I've opened up a new issue to talk about this #39

[uvchik]

I think the variables should be lower case but I'm not sure with the keys of the DataFrame. They could be camel case. It might make things even clearer in the documentation but I'm not sure. I updated the wiki. What do you think? Please add or comment.

[dacoex]

a question:
Alternatively to the wiki the variables could be added to the documentation or dedicated module where variables will be defined as a dictionary or table...

Offeres the possibility to use it in the documentation or even the code.