Proposed additions to coding guidelines

[Ryan Ollos]

Over the past several months I've accumulated in my notes a few items that I would like to add to the coding guidelines (1). I'm seeking feedback on these changes before editing the wiki.

 - Use trailing underscore to avoid conflicts with built-in keywords. I've seen this practice sparingly in the codebase and it's actually suggested in PEP-0008, but we have many instances of variables such as "id", so I think it would be good to add this point to the CodingStyle document.

 - On the trunk (Python 2.6+) we can start using str.format() rather than the string interpolation operator. Should str.format() be preferred?

 - The brackets are unnecessary in Genshi template variable. My suggestions is that $var be preferred to ${var}

 - Generally I seem to prefer putting the properties / attributes before methods in class definitions, but I tend to think that's something I picked-up from C++ and maybe shouldn't be a guideline.

I'll add more item here for comment when I think of them. Thanks for any feedback.

(1) http://trac.edgewall.org/wiki/TracDev/CodingStyle

(2) https://www.python.org/dev/peps/pep-0008/#descriptive-naming-styles

[Remy Blank]

Ryan Ollos wrote on 2015-01-14 03:03:
> Over the past several months I've accumulated in my notes a few items
> that I would like to add to the coding guidelines (1). I'm seeking
> feedback on these changes before editing the wiki.
>
> - Use trailing underscore to avoid conflicts with built-in keywords.
> I've seen this practice sparingly in the codebase and it's actually
> suggested in PEP-0008, but we have many instances of variables such as
> "id", so I think it would be good to add this point to the CodingStyle
> document.

The current practice is to use the trailing underscore when the name
would be a keyword, but not when it would shadow a built-in. In other
words, use it only when you have to. You would therefore write "with_"
or "if_" but "id" is fine, because it isn't a keyword.

I would have a weak preference for keeping this. In particular, the id()
function is only rarely used, and "id" is a very common and useful
variable name.

> - On the trunk (Python 2.6+) we can start using str.format() rather
> than the string interpolation operator. Should str.format() be preferred?

No opinion on this. I'm still using % in my code, because I don't see a
strong advantage for str.format(), but I'm fine with it.

> - The brackets are unnecessary in Genshi template variable. My
> suggestions is that $var be preferred to ${var}

Sounds good. You still have to use the ${} syntax for embedding
expressions (as opposed to simple variables).

> - Generally I seem to prefer putting the properties / attributes before
> methods in class definitions, but I tend to think that's something I
> picked-up from C++ and maybe shouldn't be a guideline.

That's somewhat ill-defined, since you don't need to declare attributes.
I tend to prefer keeping things together that go together, so if a
property is related to some methods, I would define them together and
not necessarily move the property arbitrarily to the top. Especially
since properties often look a lot like methods if you write:

@property
def my_property(self):
...

-- Remy

[RjOllos]

Thank you for the feedback.  I edited the CodingStyle guide in:

http://trac.edgewall.org/wiki/TracDev/CodingStyle?version=25 

[RjOllos]

I added one more addition this evening, and just posting here for transparency in case anyone would like to comment on it.
trac.edgewall.org/wiki/TracDev/CodingStyle?action=diff&version=27

[Christopher Nelson]

I avoid exceptions whenever possible -- I consider them not much
better than GOTO -- so what you suggest is the minimal requirement for
using them.