Python guidelines #17
Conversation
|
Couple quick things: Single-Letter VariablesI think all single-letter variables should be allowed. Restricting to i and j is a little arbitrary (remember the zero/one/infinity rule!). PyCharm will complain if you're forced to reuse these "anonymous" variables within the same outer block. For instance, you've got an iteration over i, with a nested iteration over j, and then you reuse one of those in a later lambda function (e.g. While not explicitly defined in I'm pretty sure the standard practice is that numeric variables start at i and increment through the alphabet, while lambda arguments start at x and increment. Rather than create two restrictive subsets, I think it just makes sense to leave this one to common sense and collaboration, since there's an appropriate place and time for it in pythonic code. Sphinx Documentation FormatI'd like to encourage that we go one step further than PEP257 and to use the Sphinx documentation format as our standard documentation format. There's a ton of advantages to this:
That's all I've got. Thanks for reading! |
|
+1 on Sphinx docstrings. I'm not too keen on the 120-character line length, though. I work with a bunch of Vim splits and I value screen real estate. Adjusting from the standard 80 characters would cut down the number of panes I can have open by a third. If you follow PEP-8, there should be very few scenarios in which lines longer than 80 characters are unavoidable. What's the advantage of pylint over flake8? |
|
Gonna have to give a 👎 on reducing the string length. That's On Tue, Apr 15, 2014 at 10:55 AM, tristaneuan notifications@github.comwrote:
|
|
Single-letter variables: I'm fine with allowing single-letter variable names, but I would like to add a warning in the document about their overuse. I definitely think they're great for iteration and for lambdas, but I hate reading code that has a ton of ambiguously named variables. Sphinx docstrings: I agree about the Sphinx docstrings. I kind of wanted to be a little lenient about docstrings, because I feel like that's often the type of thing people find most annoying about coding conventions. I think for now, I'd like to make it simply a recommendation, and not imply that it's a requirement. Are you guys fine with that? You can still pick on people when they don't use it. 😉 80 vs. 120 character line length: I have to agree with Robert on this. Sorry. Feel free to write your own code to be 80 characters or less, but you're going to have a hard time convincing other people to do it. Let's see what everyone else says. By the way, 120 is the limit we're using for other languages, and it's also pretty much the perfect width for browsing code on GitHub. |
|
I think not requiring sphinx docstrings makes sense. Explicitly On Tue, Apr 15, 2014 at 11:10 AM, Jonathan Robson
|
|
@tristaneuan (forgot to answer your last question): The reason we chose pylint is simply because it seemed like the most popular tool of its type. I'll look at flake8 and see if it provides anything that we would want that pylint doesn't already do. At some point, I'll probably create a module that wraps our various code checkers and automatically uses our settings to make it easier for people to use. |
|
Now take some screen shots in PyCharm ;) On Tue, Apr 15, 2014 at 11:15 AM, tristaneuan notifications@github.comwrote:
|
|
This conversation is going to become a scrolling nightmare if we post a bunch of screenshots. @tristaneuan, you're not going to convince me. Sorry. Let's just wait and see what everyone else says. Remember, these are just guidelines for all of Wikia. If you want to require 80 character line lengths in a project, then you can work it out with the people involved in just that project. |
|
+1 for 80 column line lengths. I know our JS style guidelines are at 120, but personally, I find 80 much more readable. |
|
Since it's a tie, -1 for 80 column line lengths. It's 2014, guys. |
|
2014 is a hell long line |
|
@gabrys 👅 |
|
Looks ok, great work. I'm also for allowing single-letter var names for counters and iterators, this is a common practice in Python. I also like prepending protected and private method names with single/double underscores, but that's already covered by Google guidelines. |
|
Good job. 👍 for 120 column line lengths. What the thread thinks about adding the following?
|
|
@federico-lox: I don't want to include that info right now. As I said in the PR description...
There's still some debate about the best way to organize projects. Robert, Nelson, and I have been discussing this and doing related research. I don't want to have that conversation here though. This is just coding conventions for now. The other stuff will come soon after this. |
|
@jnrbsn gotcha 👍 |
|
Ok. I've made the changes agreed upon in the conversation here. I'm going to merge it now. |
8 participants
Please don't merge yet!
This pull request is to add the Python dev guidelines that I wrote. I've also moved everything into subdirectories for each language.
@Wikia/platform-team, @relwell, @tristaneuan: Please review this as well as the pylintrc file I wrote.
Click here to see the rendered version of the markdown, which is easier to read.
I want to eventually write some documentation on the recommended way to organize projects, setup virtual environments, deploy projects, etc. @nmonterroso and I are working out the details for that using the job queue project as a test.