[Cogs] Cog model restructure

[quachtridat]

Cog model restructure

Summary

File structure is important for separation of code logic. By splitting logics into separate chunks of code in different code files based on the logic and functionality of the code, we can make our code base easier to understand, follow, and allow for better development and testing experience. A cog is a Python class inheriting redbot.core.commands.Cog, and typically has its core business logics, event handlers, command handlers and instance variables. Instead of having all logics inside the cog class, we can write classes in separate files and let the cog class inherit them.

Event handlers and command handlers are cog instance methods that take specific Python decorators to be hooked to the Ren bot when the cog is loaded. This makes it hard for us to unit test because these methods are transformed into different Python callables, and we cannot invoke them directly. However, by separating cog logic (see details below), we can unit test these methods without worrying so much about decorators.

As we are encouraging and moving towards automated testing for Ren, and as discussed sideband in several Rengineer sessions, this change is necessary and shall be done for all cogs created and maintained by Rengineers. This document proposes a file structure, Python class structure, and a diagram of class inheritance chains that all of our cogs shall follow. The new model should be easy for us to adopt for our existing code.

To-do list

Many of our Ren cogs at the moment are written with all logics staying inside one cog class, making the files long and hard to be unit-tested. Below are our cogs sorted in order of importance (from the most important to the least importance). We should adopt the new structure accordingly, and preferably modify the less important cogs first, and the more important cogs later, to minimize potential disruptions.

• [Tags] Cog model restructure
• [Welcome] Cog model restructure
• [Highlight] Cog model restructure
• [WordFilter] Cog model restructure
• [TempChannels] Cog model restructure
• [AfterHours] Cog model restructure
• [Birthday] Cog model restructure #632
• [Heartbeat] Cog model restructure #626
• [SFU] Cog model restructure #625
• [YOURLSClient] Cog model restructure #623
• [Respects] Cog model restructure #621
• [ServerManage] Cog model restructure #619
• [QRChecker] Cog model restructure #616
• [SmartReact] Cog model restructure #615
• [Triggered] Cog model restructure #611
• [SlashSync] Cog model restructure #609

Details for the file structure, class structure and inheritance chains to follow are documented here. While this may seem strict and concrete, I believe it’s better to take this as the best approach for the general scheme of file and class structures, and flexibility is still there. If one is unsure where to put a certain class/function/method, most likely discussions need to happen. Then, anything that is worth noting related to this new model can be additionally documented in this document.