Jsonnet Style Guide

[davidzchen]

Since we have the reformatter, let's also write a style guide.

[fare]

Until we have an official well-written style guide, can we already get answers to questions such as:

1- What is the official indentation? (Looks like you use 4 spaces per indentation level, comma as terminator in multiline lists, etc.)

2- What is the official naming convention? (std uses camelCase for functions, but many examples use snake_case for functions and/or objects, whereas others use CamelCase for some data structures) Are there conventions for naming predicate functions? Higher-order functions?

3- What is the convention for documenting those functions?

I'm certainly forgetting a lot of points, but yes, even a misformatted incomplete draft or a comment on this thread would be better than no style guide at all.

[sparkprime]

In Lieu of an official Jsonnet style guide I would repurpose the parts of PEP8 that are appropriate. Why PEP8? Because much of Jsonnet is designed syntactically (and semantically) to be familiar to Python programmers. May as well be familiar on the style front as well.

Of course a blind application of PEP8 would be no good, we have to use our common sense as well, knowing which rules to ignore and what new rules to have. But I think it's a good start and a lot of it is re-usable. E.g.:

4 char soft tabs, snake_case for everything except class names (OK we don't have classes but if you give a mixin a name it's pretty much a class)

For documenting functions, I would use a /** */ comment block like Javascript or Doxygen. It's not that hard to implement real support for this, since the comments are preserved by the parser. We have no concept of a Python docstring.

[fare]

PEP8 says 79 characters per line. In #111 you mention 100 characters per line. Can you clarify the official style guide with this respect?

[sparkprime]

I wouldn't interpret #111 as anything official :)

Go with PEP8, This means a lot of the Jsonnet in the repo is non-compliant but we are where we are.

Since you're looking into this in some detail, if you start accumulating a list of additions to PEP8 or things which are not reasonable to use from PEP8 then that would be very interesting to discuss.

[sparkprime]

Now we have a formatter and a linter, I think the rules they enforce suffice for our purposes. A more detailed style guide has been made available by databricks: https://github.com/databricks/jsonnet-style-guide

[seh]

Unfortunately, the Databricks guide prescribes camel case in lieu of snake case. Decisions, decisions...

[sparkprime]

I don't think we can mandate any style that doesn't have tool support. But local variables are something that the formatting tool could conceivably rename. It would have to make sure the new name is not already in scope, but that is not hard. Fields on the other hand are generally not possible to automatically rename and a lot of the time we are beholden to 3rd party JSON formats anyway.

[sbarzowski]

Actually most style guides specify the preferred naming convention while formatting tools that I know are completely ignoring that. I know a few linters that issue warning, but that's it.

snake_case for everything except class names (OK we don't have classes but if you give a mixin a name it's pretty much a class)

Since we are using camel case in stdlib perhaps we should just go with camel case everywhere, since this seems to be what people do anyway. Simple recommendation, no nuances, compatible with stdlib, DataBricks guide and ksonnet...