Skip to main content
Improve readability with formatting
Source Link
Cwt
  • 111
  • 4

Documentation for programmers

First off, as you said you want to provide documentation for developers using this class. There is some discussion about documenting/commenting code, that you can find eg. here:


Step towards self-documenting code

One thing that goes in the direction of self-documenting code is the following: You mentioned a set of methods that should not be overridden - resetResults, inputDefaultValues, etc. If that always should hold, you could change the methods to follow the Python convention for private access method: in prefixing them with two underscores, having then __resetResults, __inputDefaultValues, and so on.


You have applied a Design Pattern (which includes existing UML diagrams)

Some additional context to your approach: With the Form class you are in fact following one of the classic design patterns by Gamma et al: the Template Method pattern.

So, I would not create any additional UML diagram, but instead just reference the pattern.

The documentation itself, about the available methods, etc., could just by added to the Form class itself as a Python docstring.


Additional info

For completeness, in Python since version 2.6 there is in fact a sort of abstract method support with the ABC module. Though that could be from a complexity standpoint counterproductive for your use case.

To have sort of a mandatory abstract method in Python you can always just raise a NonImplementedError in the base class method.

First off, as you said you want to provide documentation for developers using this class. There is some discussion about documenting/commenting code, that you can find eg. here:


One thing that goes in the direction of self-documenting code is the following: You mentioned a set of methods that should not be overridden - resetResults, inputDefaultValues, etc. If that always should hold, you could change the methods to follow the Python convention for private access method: in prefixing them with two underscores, having then __resetResults, __inputDefaultValues, and so on.


Some additional context to your approach: With the Form class you are in fact following one of the classic design patterns by Gamma et al: the Template Method pattern.

For completeness, in Python since version 2.6 there is in fact a sort of abstract method support with the ABC module. Though that could be from a complexity standpoint counterproductive for your use case.

To have sort of a mandatory abstract method in Python you can always just raise a NonImplementedError in the base class method.

Documentation for programmers

First off, as you said you want to provide documentation for developers using this class. There is some discussion about documenting/commenting code, that you can find eg. here:


Step towards self-documenting code

One thing that goes in the direction of self-documenting code is the following: You mentioned a set of methods that should not be overridden - resetResults, inputDefaultValues, etc. If that always should hold, you could change the methods to follow the Python convention for private access method: in prefixing them with two underscores, having then __resetResults, __inputDefaultValues, and so on.


You have applied a Design Pattern (which includes existing UML diagrams)

Some additional context to your approach: With the Form class you are in fact following one of the classic design patterns by Gamma et al: the Template Method pattern.

So, I would not create any additional UML diagram, but instead just reference the pattern.

The documentation itself, about the available methods, etc., could just by added to the Form class itself as a Python docstring.


Additional info

For completeness, in Python since version 2.6 there is in fact a sort of abstract method support with the ABC module. Though that could be from a complexity standpoint counterproductive for your use case.

To have sort of a mandatory abstract method in Python you can always just raise a NonImplementedError in the base class method.

Source Link
Cwt
  • 111
  • 4

First off, as you said you want to provide documentation for developers using this class. There is some discussion about documenting/commenting code, that you can find eg. here:


One thing that goes in the direction of self-documenting code is the following: You mentioned a set of methods that should not be overridden - resetResults, inputDefaultValues, etc. If that always should hold, you could change the methods to follow the Python convention for private access method: in prefixing them with two underscores, having then __resetResults, __inputDefaultValues, and so on.


Some additional context to your approach: With the Form class you are in fact following one of the classic design patterns by Gamma et al: the Template Method pattern.

For completeness, in Python since version 2.6 there is in fact a sort of abstract method support with the ABC module. Though that could be from a complexity standpoint counterproductive for your use case.

To have sort of a mandatory abstract method in Python you can always just raise a NonImplementedError in the base class method.