Coding Style

Introduction

Our project code runs correctly under some linting tools, eg: pylint pycodestyle flake8 mypy pytype. We follow linting tools rules, but there are some other coding styles. The following code styles are recommended.

list variable name

There are two ways to name it. s suffix and list suffix. We have some disscusion about it.

> Huan :

We are using a naming style as room_id_list instead of room_ids because the _list postfix can make the variable type more explicit.

So I'd like to suggest let's follow this naming style.

Please feel free to let me know what you think, thanks.

> wj-mcat:

I have notice the name style from ts-wechaty. But I sugguest to name list variable with the plural of whatever's in it.

stackoverflow

reasons:

• **_list variable means colletion type, plural also means it.
• **s variable defaultly means list type. eg: names (List[str]), ids(List[str]).
• **s is shorter than **_list
• **s is more english readable than **_list

> Huan :

Ok, I'll not consist of it.

I use list instead of the plural is because _list is more readable and can differentiate with the single variable better.

For example: room vs rooms is not as clear as room vs room_list.

> wj-mcat:

I think the discuss on variable name style is interesting.

First, I reviewed some open source project code in python just now. They almost name the colletion variable with s suffix. I think all developers are familiar with english, and plural words means collection is the basic gramma. So one from gramma aspect, another from word aspect. Two way can be accepted.

Second, readable can be a cognitive problems, if a word is rich in meaning, the name is important because it will influence the understanding. But if a word is simple, the name should be simple too.

# first way
room_list = search_room_list(query)
for room in room_list:
    # do something
# second way
rooms = search_rooms(query)
for room in rooms:
    # do something

Personally, I think second way can be concise, shorter and simple 😂😂😂.

> Huan :

Good to read your sharing and thoughts.

I agree with you that the variable name with s suffix for collections is concise, short and simple. On the other side, the _list suffix will be a little verbose but make a strong meaning for the variable: it's a collection.

log style

There are some conventions in log name and output format.

• how to get log in specific module?

# RoomInvitation.py
import logging
log = logging.getLogger('RoomInvitation') # got by module_name

• how to output log information?

log.info('topic() <%s>', self) # log with function name -> func() <%s>