From d535b8fd0a20c02a94c4b2741c9e1475a8e227ff Mon Sep 17 00:00:00 2001 From: Maria Grimaldi Date: Mon, 30 Dec 2024 14:08:28 +0100 Subject: [PATCH] docs: address PR reviews --- .../0007-filter-design-practices.rst | 22 +++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/docs/decisions/0007-filter-design-practices.rst b/docs/decisions/0007-filter-design-practices.rst index 8272382..1b597b5 100644 --- a/docs/decisions/0007-filter-design-practices.rst +++ b/docs/decisions/0007-filter-design-practices.rst @@ -23,6 +23,24 @@ Design Clarity and Understanding - A filter should have a clear and concise name that describes its purpose. - Ensure that the triggering logic of the filter is consistent and narrow. It should only trigger when the conditions are met and cover all the cases that the filter should be applied with the minimum number of modifications. +For instance, consider this filter that is supposed to modify the behavior of the certificate creation process: + +.. code-block:: python + + class CertificateCreationRequested(OpenEdxPublicFilter): + + class PreventCertificateCreation(OpenEdxFilterException): + """ + Custom class used to stop the certificate creation process. + """ + + @classmethod + def run_filter(cls, user, course_key, mode, status, grade, generation_mode): + +Where the filter name indicates that it is a filter that is triggered when the certificate creation is requested, providing a clear understanding of the filter behavior. Avoid using generic names such as ``Filter`` or ``Process`` that do not provide any context about the filter behavior. + +The ``CertificateCreationRequested`` is triggered by `_generate_certificate_task`_ which handles all the cases that the filter should be applied avoiding unnecessary modifications. + Contextual Information ~~~~~~~~~~~~~~~~~~~~~~ @@ -30,6 +48,8 @@ Contextual Information - A filter should provide enough context in its arguments to avoid runtime dependencies with the application. - The arguments of the filter should be directly related to the responsibility of the filter. +Consider the user login filter example above. The filter provides the necessary context to understand the behavior that is being modified such as the user, course key, mode, status, grade, and generation mode. The arguments are directly related to the responsibility of the filter. + Flexibility and Customization ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -41,6 +61,8 @@ Error Handling - Ensure that the exceptions when using the filter are handled properly and that the filter does not break the application. - The filter exceptions should correspond with the filter behavior. If the filter is not supposed to halt the application behavior in any case, then do not specify exceptions. If the filter is supposed to halt the application behavior in some cases, then specify the exceptions that the filter can raise with enough reason to understand why the filter is halting the application behavior. +Consider the certificate creation filter example above. The filter specifies an exception that is raised when the certificate creation process is stopped, providing a clear understanding of the filter behavior when the exception is raised. This exception should be handled properly in the application to avoid runtime errors. + Type Safety ~~~~~~~~~~~