Coding style
When writing Python code for Misago, please familiarize yourself with and follow those documents:
Those documents should give you solid knowledge of coding style and conventions that are followed by Python and Django programmers when writing code.
In addition to those guidelines, Misago defines set of additional convetions and good practices that will help you write better and easier code.
Notes
Originally Misago was writen with 79 character line limit in mind, but recently this convention was dropped for sake of Django's 119 characters line limit.
Misago comes with .pylintrc
file that contains configuration for pylint tool used to lint Misago's codebase.
Single and double quotes
Write messages intented for humans to see using double quotes and all other strings using single ones. Use single quotes for messages for humans if those already contain double quotes.
Models
Fields Order
When declaring model's database fields, start with taxonomical foreign keys followed by fields that make this model identifiable to humans. Order of remaining fileds is completely up to you.
Thread model is great example of this convention. Thread is part of taxonomy (Forum), so first field defined is foreign key to Forum model. This is followed by two fields that humans will use to recognise this model: title
that will be displayed in UI and slug
that will be included in links to this thread. After those Thread model defines additional fields.
When declaring model database fields, make sure they are grouped together based on their purpose. Most common example is storage of user name and slug in addition to foreign key to User model. In such case, make sure both poster
field as well as poster_name
, poster_slug
and poster_ip
fields are grouped together.
Avoid Unmeaningful Names
Whenever possible avoid naming fields representing relation to User
model user
. Preffer more descriptive names like poster
, last_editor
, or giver
.
For same reason avoid using date
or ip
as field names. Use more descriptive posted_on
or poster_ip
instead.
True/False Fields
For extra clarity prefix fields representing true/false states of model with is_
. is_deleted
is better than deleted
.
Serializers
Defining serializers
Model's default serializer should be named after its model, but with Serializer
suffix, ergo serializer for Thread
model should be named ThreadSerializer
. Default serializer should be only serializer defining serialization methods for SerializerMethodField
.
In case that model has more than one serializer, all additional serializers should be named in a way describing their usage. For example serializer for Post
model used to serialize user's posts list could be named FeedPostsSerializer
. This serializer should only define Meta
class with model
and fields
attributes, inheriting serialization behaviour form default serializer.
Fields Order
Order of fields should correspond directly to order of fields on model that serializer handles.
If serializer defines non-model fields, those should be specified last and separated from model's fields with empty line, ergo:
URLs
Serializers may define two special fields used for serialization of url's, url
and api
. The first one should be string containing serialized model's get_absolute_url
or list urls of interest for UI rendering serialized model, like:
Likewise the "api" key should contain the url to item api endpoint (eg. /api/threads/132/
) or list of avaiable endpoints:
Those keys should live at the end of the fields list and be separated from other fields with blank line:
Nested results
Nested results should be included in view or viewset, as part of creating dict of serialized data for Response
object:
The added key should be model's related_name
in respect of model it annotates (defautly its modelname_set
).
Last updated