https://eden.sahanafoundation.org/api.php?action=feedcontributions&feedformat=atom&user=Dominic 2026-10-30T02:23:30Z User contributions MediaWiki 1.44.0 https://eden.sahanafoundation.org/index.php?title=Guidelines:Quality&diff=326 2026-10-29T13:48:56Z

<p>Dominic: /* Consistent */</p> <hr /> <div>* [[Guidelines:Index|All Guidelines]]<br /> <br /> = General Quality Requirements =<br /> <br /> The general quality requirements are defined here as attributes of the solution that is to be evaluated (&quot;The solution must be ...&quot;).<br /> <br /> These attributes are grouped in four quality &quot;levels&quot; - a higher level representing a higher quality standard. <br /> <br /> Projects can refer to these levels to define minimum quality goals, to prioritize certain quality aspects vs. other requirements, or to define an iterative approach of continuous quality improvement.<br /> <br /> In order to pass a level, all criteria of this level and all previous levels must be met.<br /> <br /> {| class=&quot;wikitable&quot; style=&quot;margin:auto&quot;<br /> |+ Quality Levels<br /> |-<br /> ! Level !! Priority (MoSCoW) !! Key Attributes !! Description<br /> |-<br /> ||0 - '''Experimental'''||-||-||any solution that does not (yet) meet all criteria of level 1<br /> |-<br /> ||1 - '''Minimal'''||Must||[[#Valid| valid]], [[#Correct| correct]], [[#Safe| safe]]||minimum standard for any solution<br /> |-<br /> ||2 - '''Appropriate'''||Should||[[#Usable| usable]], [[#Maintainable| maintainable]], [[#Secure| secure]]||minimum standard for production use<br /> |-<br /> ||3 - '''Good'''||Can||[[#Consistent| consistent]], [[#Robust| robust]], [[#Configurable| configurable]]||long-term development goals<br /> |-<br /> ||4 - '''Optimal'''||Want||[[#Efficient| efficient]], [[#Scalable| scalable]], [[#Interoperable| interoperable]]||optimization and enhancement goals<br /> |}<br /> <br /> <br /> == Level 1: Minimal ==<br /> <br /> === Valid ===<br /> <br /> ''&quot;Writing the right code&quot;''<br /> <br /> * The specified solution solves the targeted problem and meets the minimum functional requirements<br /> * The required input data are available in the target scenario<br /> * The user actions required to apply and/or use the solution or its responses are ''possible'' in the target scenario<br /> * All dependencies of the feature set are resolvable, and hardware and infrastructure requirements can be met in the target scenario<br /> <br /> === Correct ===<br /> <br /> ''&quot;Writing the code right&quot;''<br /> <br /> * Processing does not fail for any valid input data or user action.<br /> * All responses are correct for the respective input data or user actions according to the specification<br /> <br /> === Safe ===<br /> <br /> * The solution does not break other functionality of the application (except for functionality it replaces or supersedes)<br /> * All processing always ends with a valid database status regardless whether it succeeds or fails<br /> * All failed processes are effectively removed from the system and their transactions properly rolled back<br /> * The solution effectively prevents uncontrolled indefinite object or process proliferation<br /> * The solution always returns to a defined system status after a failure so that the application remains accessible<br /> <br /> == Level 2: Appropriate ==<br /> <br /> === Usable ===<br /> <br /> * The solution ''can'' be used by the intended user group in the target scenario, i.e. the users can:<br /> ** discover and access the features<br /> ** understand and perform the required user actions<br /> ** understand and control the consequences of actions<br /> ** understand and provide the required type, quality and format of input data<br /> ** discover and access the results, and apply them to achieve their goals<br /> <br /> * Usability criteria apply analogously for back-end libraries and tools with developers in the role of the user<br /> <br /> === Maintainable ===<br /> <br /> * All critical dependencies are obvious at their starting point<br /> * All non-critical dependencies have meaningful fallbacks<br /> * Processing failures produce useful and accessible feedback about the reasons<br /> * The design of the solution does not obstruct diagnostics of defects<br /> * The code is structured in a way that the processing flow can easily be determined from it<br /> <br /> === Secure ===<br /> <br /> * The solution applies all relevant system configurations for authentication, authorization and accounting (AAA) appropriately and correctly.<br /> * The solution does not allow the user to perform actions or initiate processes beyond the intended functionality.<br /> <br /> == Level 3: Good ==<br /> <br /> === Consistent ===<br /> <br /> ''&quot;Maintaining Conceptual Integrity across the Application and beyond&quot;''<br /> <br /> * The solution applies the application framework appropriately and correctly<br /> * The data structures defined in the solution are consistent with the global application data model<br /> * The solution interoperates appropriately and correctly with other system components<br /> * The solution applies the application's global design and style guidelines (both for code and interfaces)<br /> * Where appropriate or required, the solution complies with specified standards (see [[#Standards| Standards]])<br /> <br /> === Robust ===<br /> <br /> * The solution delivers consistent behavior, results and performance for all valid configurations<br /> * The solution handles invalid input data, unexpected user actions and irregular system conditions appropriately and consistently for all valid configurations<br /> * The solution detects invalid configurations and prevents any inadvertent effects that could result from them<br /> <br /> === Configurable ===<br /> <br /> * The solution can be easily and safely turned on and off without inadvertent side-effects (where appropriate, not for framework solutions)<br /> * The solution applies global configuration settings correctly and consistently<br /> * Processing parameters, behavior and/or appearance of the solution can be adapted to requirements variations using configuration patterns separate from its core code<br /> <br /> == Level 4: Optimal ==<br /> <br /> === Efficient ===<br /> <br /> * The solution provides acceptable performance with the minimum available hardware/infrastructure resources in the target scenario<br /> * The solution can be applied with minimal configuration effort<br /> * The solution can be applied, developed and maintained with minimal learning effort<br /> <br /> === Scalable ===<br /> <br /> * The solution can handle/adapt to varying problem sizes (e.g. amount of data, frequency of events) without failure, inconsistent behavior or significant loss of performance<br /> * The solution can utilize hardware/infrastructure enhancements and/or concurrency to provide better performance<br /> * The solution can be applied in any number of concurrent instances (given the appropriate hardware and infrastructure) without failure, inconsistent behavior or significant loss of performance<br /> <br /> === Interoperable ===<br /> <br /> * Different instances of the solution can, where appropriate or required, interchange data and/or process information<br /> * The solution can, where appropriate or required, interchange data and/or process information with other relevant solutions in the target scenario<br /> * The solution provides external APIs (application programming interfaces)<br /> <br /> = User Experience (UX) Requirements =<br /> <br /> ''Wikipedia: ISO 9241-210[1] defines user experience as &quot;a person's perceptions and responses that result from the use or anticipated use of a product, system or service&quot;. According to the ISO definition, user experience includes all the users' emotions, beliefs, preferences, perceptions, physical and psychological responses, behaviors and accomplishments that occur before, during and after use.''<br /> <br /> User experience, as a result of human-computer-interaction, involves various aspects of a software solution - both in view of its design, its functionality as well as its quality, but also personal aspects of the individual user (e.g. skills, previous experiences, cultural background), and of the situations and environments in which the software is to be used.<br /> <br /> &quot;Good UX&quot; is though not a requirement in itself - but the generic name for any additional design, functional and quality requirements in view of human-computer-interaction that may be defined for a solution, and which must be met in order to achieve certain quality levels.<br /> <br /> Even though UX as such appears to be a largely subjective matter, there are usually a number of generalizable UX requirements for any user interface.<br /> <br /> '''Example:''' ''User interfaces which are typically used in the darkness should not blind the user, but use a reduced palette of primarily reddish colors on dark background in order to cause less or no iris contraction. If the interface is though to be used under varying lighting conditions it should be adaptable (or even auto-adapt).''<br /> <br /> In order to be '''valid and accomplishable, UX requirements must be specific and clearly defined''' (like the above example) for the quality level for which they shall apply - even when their reasoning may be more complex sometimes.<br /> <br /> Some general quality requirements also influence the user experience (e.g. correctness, usability, efficiency), but are not specific for the use-case and therefore usually not separately discussed as UX requirements. They are however relevant for UX evaluations and should thus be taken into account in such analyses.<br /> <br /> = Advanced Quality Requirements =<br /> <br /> ''Advanced'' quality criteria can be used to compare different solutions, or to define quality roadmaps for particular feature sets beyond the standard criteria.<br /> <br /> Advanced quality criteria do not apply equally for all use-cases - in certain cases they may even constitute anti-patterns.<br /> <br /> Advanced quality criteria do not enhance the general quality level of a solution: a level-3 solution is still of better quality than a level-2 solution - regardless how many advanced criteria the level-2 solution meets.<br /> <br /> == Stability ==<br /> <br /> A solution is ''stable'' when its black-box model rarely changes, and it maintains backwards-compatibility and/or easy migration paths. Stable solutions are required for all critical dependencies, so that they can be built upon without risk for frequent regression issues or need for constant migration. Stability is especially critical in shared data models (i.e. where data are shared between different modules within the application or even across applications), and in authorization frameworks - and can thus be defined as quality requirement for a solution.<br /> <br /> Stability is typically perceived as a sign of maturity, but can actually be taken into account already during the initial solution design. Pragmatic approaches (e.g. integrated migration, or enforced backwards-compatibility) can create stability early on without limiting or obstructing further development.<br /> <br /> == Generalization ==<br /> <br /> Generalizable solutions are designed and/or implemented in a way that they can be generalized. Typically, they separate their core patterns/algorithms from the use-case specifics through parametrization and/or configuration patterns. This can be defined as an advanced quality requirement for a solution.<br /> <br /> Generalization means to modify and/or extend the core patterns/algorithms of the solution in a way that they can be re-used in other solutions which involve the same or similar functional requirements, thereby reducing future development efforts. There is a wide range of quality attributes - &quot;flexible&quot;, &quot;customizable&quot;, &quot;re-usable&quot;, &quot;extensible&quot;, just to name a few - all of which involve different degrees of and approaches to generalization.<br /> <br /> = Standards =<br /> <br /> Solutions can both define or implement standards (e.g. data standards, communication protocols, taxonomies). Standard compliance can be defined as quality requirement for a solution.<br /> <br /> Standards can define additional requirements beyond the immediate requirements of the targeted problem, which must however be met in order to comply with the standard. Such additional standard requirements would usually be seen as quality requirements under [[#Consistent| &quot;Consistency&quot;]] in level 3.</div>

Dominic https://eden.sahanafoundation.org/index.php?title=Guidelines:Index&diff=325 2026-10-29T13:39:29Z

<p>Dominic: /* Contributor Guidelines */</p> <hr /> <div>== Implementer Guidelines ==<br /> <br /> * [[Guidelines:Deployment|Deployment Guidelines]]<br /> <br /> == Contributor Guidelines ==<br /> <br /> * [[Guidelines:ContributorWorkflow|Git Workflow for Code Contributions]]<br /> * [[Guidelines:CodingStyle|Coding Conventions]]<br /> * [[Guidelines:Quality|Solution Quality Evaluation Guideline]]<br /> * [[Guidelines:AI|Guideline for Responsible AI Contributions]]</div>

Dominic https://eden.sahanafoundation.org/index.php?title=Guidelines:Quality&diff=324 2026-10-29T13:37:35Z

<p>Dominic: /* General Quality Requirements */</p> <hr /> <div>* [[Guidelines:Index|All Guidelines]]<br /> <br /> = General Quality Requirements =<br /> <br /> The general quality requirements are defined here as attributes of the solution that is to be evaluated (&quot;The solution must be ...&quot;).<br /> <br /> These attributes are grouped in four quality &quot;levels&quot; - a higher level representing a higher quality standard. <br /> <br /> Projects can refer to these levels to define minimum quality goals, to prioritize certain quality aspects vs. other requirements, or to define an iterative approach of continuous quality improvement.<br /> <br /> In order to pass a level, all criteria of this level and all previous levels must be met.<br /> <br /> {| class=&quot;wikitable&quot; style=&quot;margin:auto&quot;<br /> |+ Quality Levels<br /> |-<br /> ! Level !! Priority (MoSCoW) !! Key Attributes !! Description<br /> |-<br /> ||0 - '''Experimental'''||-||-||any solution that does not (yet) meet all criteria of level 1<br /> |-<br /> ||1 - '''Minimal'''||Must||[[#Valid| valid]], [[#Correct| correct]], [[#Safe| safe]]||minimum standard for any solution<br /> |-<br /> ||2 - '''Appropriate'''||Should||[[#Usable| usable]], [[#Maintainable| maintainable]], [[#Secure| secure]]||minimum standard for production use<br /> |-<br /> ||3 - '''Good'''||Can||[[#Consistent| consistent]], [[#Robust| robust]], [[#Configurable| configurable]]||long-term development goals<br /> |-<br /> ||4 - '''Optimal'''||Want||[[#Efficient| efficient]], [[#Scalable| scalable]], [[#Interoperable| interoperable]]||optimization and enhancement goals<br /> |}<br /> <br /> <br /> == Level 1: Minimal ==<br /> <br /> === Valid ===<br /> <br /> ''&quot;Writing the right code&quot;''<br /> <br /> * The specified solution solves the targeted problem and meets the minimum functional requirements<br /> * The required input data are available in the target scenario<br /> * The user actions required to apply and/or use the solution or its responses are ''possible'' in the target scenario<br /> * All dependencies of the feature set are resolvable, and hardware and infrastructure requirements can be met in the target scenario<br /> <br /> === Correct ===<br /> <br /> ''&quot;Writing the code right&quot;''<br /> <br /> * Processing does not fail for any valid input data or user action.<br /> * All responses are correct for the respective input data or user actions according to the specification<br /> <br /> === Safe ===<br /> <br /> * The solution does not break other functionality of the application (except for functionality it replaces or supersedes)<br /> * All processing always ends with a valid database status regardless whether it succeeds or fails<br /> * All failed processes are effectively removed from the system and their transactions properly rolled back<br /> * The solution effectively prevents uncontrolled indefinite object or process proliferation<br /> * The solution always returns to a defined system status after a failure so that the application remains accessible<br /> <br /> == Level 2: Appropriate ==<br /> <br /> === Usable ===<br /> <br /> * The solution ''can'' be used by the intended user group in the target scenario, i.e. the users can:<br /> ** discover and access the features<br /> ** understand and perform the required user actions<br /> ** understand and control the consequences of actions<br /> ** understand and provide the required type, quality and format of input data<br /> ** discover and access the results, and apply them to achieve their goals<br /> <br /> * Usability criteria apply analogously for back-end libraries and tools with developers in the role of the user<br /> <br /> === Maintainable ===<br /> <br /> * All critical dependencies are obvious at their starting point<br /> * All non-critical dependencies have meaningful fallbacks<br /> * Processing failures produce useful and accessible feedback about the reasons<br /> * The design of the solution does not obstruct diagnostics of defects<br /> * The code is structured in a way that the processing flow can easily be determined from it<br /> <br /> === Secure ===<br /> <br /> * The solution applies all relevant system configurations for authentication, authorization and accounting (AAA) appropriately and correctly.<br /> * The solution does not allow the user to perform actions or initiate processes beyond the intended functionality.<br /> <br /> == Level 3: Good ==<br /> <br /> === Consistent ===<br /> <br /> ''&quot;Maintaining Conceptual Integrity across the Application and beyond&quot;''<br /> <br /> * The solution applies the application framework appropriately and correctly<br /> * The data structures defined in the solution are consistent with the global application data model<br /> * The solution interoperates appropriately and correctly with other system components<br /> * The solution applies the application's global design and style guidelines (both for code and interfaces)<br /> * Where appropriate or required, the solution complies with specified standards (see [#Standards Standards])<br /> <br /> === Robust ===<br /> <br /> * The solution delivers consistent behavior, results and performance for all valid configurations<br /> * The solution handles invalid input data, unexpected user actions and irregular system conditions appropriately and consistently for all valid configurations<br /> * The solution detects invalid configurations and prevents any inadvertent effects that could result from them<br /> <br /> === Configurable ===<br /> <br /> * The solution can be easily and safely turned on and off without inadvertent side-effects (where appropriate, not for framework solutions)<br /> * The solution applies global configuration settings correctly and consistently<br /> * Processing parameters, behavior and/or appearance of the solution can be adapted to requirements variations using configuration patterns separate from its core code<br /> <br /> == Level 4: Optimal ==<br /> <br /> === Efficient ===<br /> <br /> * The solution provides acceptable performance with the minimum available hardware/infrastructure resources in the target scenario<br /> * The solution can be applied with minimal configuration effort<br /> * The solution can be applied, developed and maintained with minimal learning effort<br /> <br /> === Scalable ===<br /> <br /> * The solution can handle/adapt to varying problem sizes (e.g. amount of data, frequency of events) without failure, inconsistent behavior or significant loss of performance<br /> * The solution can utilize hardware/infrastructure enhancements and/or concurrency to provide better performance<br /> * The solution can be applied in any number of concurrent instances (given the appropriate hardware and infrastructure) without failure, inconsistent behavior or significant loss of performance<br /> <br /> === Interoperable ===<br /> <br /> * Different instances of the solution can, where appropriate or required, interchange data and/or process information<br /> * The solution can, where appropriate or required, interchange data and/or process information with other relevant solutions in the target scenario<br /> * The solution provides external APIs (application programming interfaces)<br /> <br /> = User Experience (UX) Requirements =<br /> <br /> ''Wikipedia: ISO 9241-210[1] defines user experience as &quot;a person's perceptions and responses that result from the use or anticipated use of a product, system or service&quot;. According to the ISO definition, user experience includes all the users' emotions, beliefs, preferences, perceptions, physical and psychological responses, behaviors and accomplishments that occur before, during and after use.''<br /> <br /> User experience, as a result of human-computer-interaction, involves various aspects of a software solution - both in view of its design, its functionality as well as its quality, but also personal aspects of the individual user (e.g. skills, previous experiences, cultural background), and of the situations and environments in which the software is to be used.<br /> <br /> &quot;Good UX&quot; is though not a requirement in itself - but the generic name for any additional design, functional and quality requirements in view of human-computer-interaction that may be defined for a solution, and which must be met in order to achieve certain quality levels.<br /> <br /> Even though UX as such appears to be a largely subjective matter, there are usually a number of generalizable UX requirements for any user interface.<br /> <br /> '''Example:''' ''User interfaces which are typically used in the darkness should not blind the user, but use a reduced palette of primarily reddish colors on dark background in order to cause less or no iris contraction. If the interface is though to be used under varying lighting conditions it should be adaptable (or even auto-adapt).''<br /> <br /> In order to be '''valid and accomplishable, UX requirements must be specific and clearly defined''' (like the above example) for the quality level for which they shall apply - even when their reasoning may be more complex sometimes.<br /> <br /> Some general quality requirements also influence the user experience (e.g. correctness, usability, efficiency), but are not specific for the use-case and therefore usually not separately discussed as UX requirements. They are however relevant for UX evaluations and should thus be taken into account in such analyses.<br /> <br /> = Advanced Quality Requirements =<br /> <br /> ''Advanced'' quality criteria can be used to compare different solutions, or to define quality roadmaps for particular feature sets beyond the standard criteria.<br /> <br /> Advanced quality criteria do not apply equally for all use-cases - in certain cases they may even constitute anti-patterns.<br /> <br /> Advanced quality criteria do not enhance the general quality level of a solution: a level-3 solution is still of better quality than a level-2 solution - regardless how many advanced criteria the level-2 solution meets.<br /> <br /> == Stability ==<br /> <br /> A solution is ''stable'' when its black-box model rarely changes, and it maintains backwards-compatibility and/or easy migration paths. Stable solutions are required for all critical dependencies, so that they can be built upon without risk for frequent regression issues or need for constant migration. Stability is especially critical in shared data models (i.e. where data are shared between different modules within the application or even across applications), and in authorization frameworks - and can thus be defined as quality requirement for a solution.<br /> <br /> Stability is typically perceived as a sign of maturity, but can actually be taken into account already during the initial solution design. Pragmatic approaches (e.g. integrated migration, or enforced backwards-compatibility) can create stability early on without limiting or obstructing further development.<br /> <br /> == Generalization ==<br /> <br /> Generalizable solutions are designed and/or implemented in a way that they can be generalized. Typically, they separate their core patterns/algorithms from the use-case specifics through parametrization and/or configuration patterns. This can be defined as an advanced quality requirement for a solution.<br /> <br /> Generalization means to modify and/or extend the core patterns/algorithms of the solution in a way that they can be re-used in other solutions which involve the same or similar functional requirements, thereby reducing future development efforts. There is a wide range of quality attributes - &quot;flexible&quot;, &quot;customizable&quot;, &quot;re-usable&quot;, &quot;extensible&quot;, just to name a few - all of which involve different degrees of and approaches to generalization.<br /> <br /> = Standards =<br /> <br /> Solutions can both define or implement standards (e.g. data standards, communication protocols, taxonomies). Standard compliance can be defined as quality requirement for a solution.<br /> <br /> Standards can define additional requirements beyond the immediate requirements of the targeted problem, which must however be met in order to comply with the standard. Such additional standard requirements would usually be seen as quality requirements under [[#Consistent| &quot;Consistency&quot;]] in level 3.</div>

Dominic https://eden.sahanafoundation.org/index.php?title=Guidelines:Quality&diff=323 2026-10-29T13:37:11Z

<p>Dominic: </p> <hr /> <div>* [[Guidelines:Index|All Guidelines]]<br /> <br /> = General Quality Requirements =<br /> <br /> The general quality requirements are defined here as attributes of the solution that is to be evaluated (&quot;The solution must be ...&quot;).<br /> <br /> These attributes are grouped in four quality &quot;levels&quot; - a higher level representing a higher quality standard. <br /> <br /> Projects can refer to these levels to define minimum quality goals, to prioritize certain quality aspects vs. other requirements, or to define an iterative approach of continuous quality improvement.<br /> <br /> In order to pass a level, all criteria of this level and all previous levels must be met.<br /> <br /> {| class=&quot;wikitable&quot; style=&quot;margin:auto&quot;<br /> |+ Quality Levels<br /> |-<br /> ! Level !! Priority (MoSCoW) !! Key Attributes !! Description<br /> |-<br /> ||0 - '''Experimental'''||-||-||any solution that does not (yet) meet all criteria of level 1||<br /> |-<br /> ||1 - '''Minimal'''||Must||[[#Valid| valid]], [[#Correct| correct]], [[#Safe| safe]]||minimum standard for any solution||<br /> |-<br /> ||2 - '''Appropriate'''||Should||[[#Usable| usable]], [[#Maintainable| maintainable]], [[#Secure| secure]]||minimum standard for production use||<br /> |-<br /> ||3 - '''Good'''||Can||[[#Consistent| consistent]], [[#Robust| robust]], [[#Configurable| configurable]]||long-term development goals||<br /> |-<br /> ||4 - '''Optimal'''||Want||[[#Efficient| efficient]], [[#Scalable| scalable]], [[#Interoperable| interoperable]]||optimization and enhancement goals||<br /> |}<br /> <br /> <br /> == Level 1: Minimal ==<br /> <br /> === Valid ===<br /> <br /> ''&quot;Writing the right code&quot;''<br /> <br /> * The specified solution solves the targeted problem and meets the minimum functional requirements<br /> * The required input data are available in the target scenario<br /> * The user actions required to apply and/or use the solution or its responses are ''possible'' in the target scenario<br /> * All dependencies of the feature set are resolvable, and hardware and infrastructure requirements can be met in the target scenario<br /> <br /> === Correct ===<br /> <br /> ''&quot;Writing the code right&quot;''<br /> <br /> * Processing does not fail for any valid input data or user action.<br /> * All responses are correct for the respective input data or user actions according to the specification<br /> <br /> === Safe ===<br /> <br /> * The solution does not break other functionality of the application (except for functionality it replaces or supersedes)<br /> * All processing always ends with a valid database status regardless whether it succeeds or fails<br /> * All failed processes are effectively removed from the system and their transactions properly rolled back<br /> * The solution effectively prevents uncontrolled indefinite object or process proliferation<br /> * The solution always returns to a defined system status after a failure so that the application remains accessible<br /> <br /> == Level 2: Appropriate ==<br /> <br /> === Usable ===<br /> <br /> * The solution ''can'' be used by the intended user group in the target scenario, i.e. the users can:<br /> ** discover and access the features<br /> ** understand and perform the required user actions<br /> ** understand and control the consequences of actions<br /> ** understand and provide the required type, quality and format of input data<br /> ** discover and access the results, and apply them to achieve their goals<br /> <br /> * Usability criteria apply analogously for back-end libraries and tools with developers in the role of the user<br /> <br /> === Maintainable ===<br /> <br /> * All critical dependencies are obvious at their starting point<br /> * All non-critical dependencies have meaningful fallbacks<br /> * Processing failures produce useful and accessible feedback about the reasons<br /> * The design of the solution does not obstruct diagnostics of defects<br /> * The code is structured in a way that the processing flow can easily be determined from it<br /> <br /> === Secure ===<br /> <br /> * The solution applies all relevant system configurations for authentication, authorization and accounting (AAA) appropriately and correctly.<br /> * The solution does not allow the user to perform actions or initiate processes beyond the intended functionality.<br /> <br /> == Level 3: Good ==<br /> <br /> === Consistent ===<br /> <br /> ''&quot;Maintaining Conceptual Integrity across the Application and beyond&quot;''<br /> <br /> * The solution applies the application framework appropriately and correctly<br /> * The data structures defined in the solution are consistent with the global application data model<br /> * The solution interoperates appropriately and correctly with other system components<br /> * The solution applies the application's global design and style guidelines (both for code and interfaces)<br /> * Where appropriate or required, the solution complies with specified standards (see [#Standards Standards])<br /> <br /> === Robust ===<br /> <br /> * The solution delivers consistent behavior, results and performance for all valid configurations<br /> * The solution handles invalid input data, unexpected user actions and irregular system conditions appropriately and consistently for all valid configurations<br /> * The solution detects invalid configurations and prevents any inadvertent effects that could result from them<br /> <br /> === Configurable ===<br /> <br /> * The solution can be easily and safely turned on and off without inadvertent side-effects (where appropriate, not for framework solutions)<br /> * The solution applies global configuration settings correctly and consistently<br /> * Processing parameters, behavior and/or appearance of the solution can be adapted to requirements variations using configuration patterns separate from its core code<br /> <br /> == Level 4: Optimal ==<br /> <br /> === Efficient ===<br /> <br /> * The solution provides acceptable performance with the minimum available hardware/infrastructure resources in the target scenario<br /> * The solution can be applied with minimal configuration effort<br /> * The solution can be applied, developed and maintained with minimal learning effort<br /> <br /> === Scalable ===<br /> <br /> * The solution can handle/adapt to varying problem sizes (e.g. amount of data, frequency of events) without failure, inconsistent behavior or significant loss of performance<br /> * The solution can utilize hardware/infrastructure enhancements and/or concurrency to provide better performance<br /> * The solution can be applied in any number of concurrent instances (given the appropriate hardware and infrastructure) without failure, inconsistent behavior or significant loss of performance<br /> <br /> === Interoperable ===<br /> <br /> * Different instances of the solution can, where appropriate or required, interchange data and/or process information<br /> * The solution can, where appropriate or required, interchange data and/or process information with other relevant solutions in the target scenario<br /> * The solution provides external APIs (application programming interfaces)<br /> <br /> = User Experience (UX) Requirements =<br /> <br /> ''Wikipedia: ISO 9241-210[1] defines user experience as &quot;a person's perceptions and responses that result from the use or anticipated use of a product, system or service&quot;. According to the ISO definition, user experience includes all the users' emotions, beliefs, preferences, perceptions, physical and psychological responses, behaviors and accomplishments that occur before, during and after use.''<br /> <br /> User experience, as a result of human-computer-interaction, involves various aspects of a software solution - both in view of its design, its functionality as well as its quality, but also personal aspects of the individual user (e.g. skills, previous experiences, cultural background), and of the situations and environments in which the software is to be used.<br /> <br /> &quot;Good UX&quot; is though not a requirement in itself - but the generic name for any additional design, functional and quality requirements in view of human-computer-interaction that may be defined for a solution, and which must be met in order to achieve certain quality levels.<br /> <br /> Even though UX as such appears to be a largely subjective matter, there are usually a number of generalizable UX requirements for any user interface.<br /> <br /> '''Example:''' ''User interfaces which are typically used in the darkness should not blind the user, but use a reduced palette of primarily reddish colors on dark background in order to cause less or no iris contraction. If the interface is though to be used under varying lighting conditions it should be adaptable (or even auto-adapt).''<br /> <br /> In order to be '''valid and accomplishable, UX requirements must be specific and clearly defined''' (like the above example) for the quality level for which they shall apply - even when their reasoning may be more complex sometimes.<br /> <br /> Some general quality requirements also influence the user experience (e.g. correctness, usability, efficiency), but are not specific for the use-case and therefore usually not separately discussed as UX requirements. They are however relevant for UX evaluations and should thus be taken into account in such analyses.<br /> <br /> = Advanced Quality Requirements =<br /> <br /> ''Advanced'' quality criteria can be used to compare different solutions, or to define quality roadmaps for particular feature sets beyond the standard criteria.<br /> <br /> Advanced quality criteria do not apply equally for all use-cases - in certain cases they may even constitute anti-patterns.<br /> <br /> Advanced quality criteria do not enhance the general quality level of a solution: a level-3 solution is still of better quality than a level-2 solution - regardless how many advanced criteria the level-2 solution meets.<br /> <br /> == Stability ==<br /> <br /> A solution is ''stable'' when its black-box model rarely changes, and it maintains backwards-compatibility and/or easy migration paths. Stable solutions are required for all critical dependencies, so that they can be built upon without risk for frequent regression issues or need for constant migration. Stability is especially critical in shared data models (i.e. where data are shared between different modules within the application or even across applications), and in authorization frameworks - and can thus be defined as quality requirement for a solution.<br /> <br /> Stability is typically perceived as a sign of maturity, but can actually be taken into account already during the initial solution design. Pragmatic approaches (e.g. integrated migration, or enforced backwards-compatibility) can create stability early on without limiting or obstructing further development.<br /> <br /> == Generalization ==<br /> <br /> Generalizable solutions are designed and/or implemented in a way that they can be generalized. Typically, they separate their core patterns/algorithms from the use-case specifics through parametrization and/or configuration patterns. This can be defined as an advanced quality requirement for a solution.<br /> <br /> Generalization means to modify and/or extend the core patterns/algorithms of the solution in a way that they can be re-used in other solutions which involve the same or similar functional requirements, thereby reducing future development efforts. There is a wide range of quality attributes - &quot;flexible&quot;, &quot;customizable&quot;, &quot;re-usable&quot;, &quot;extensible&quot;, just to name a few - all of which involve different degrees of and approaches to generalization.<br /> <br /> = Standards =<br /> <br /> Solutions can both define or implement standards (e.g. data standards, communication protocols, taxonomies). Standard compliance can be defined as quality requirement for a solution.<br /> <br /> Standards can define additional requirements beyond the immediate requirements of the targeted problem, which must however be met in order to comply with the standard. Such additional standard requirements would usually be seen as quality requirements under [[#Consistent| &quot;Consistency&quot;]] in level 3.</div>

Dominic https://eden.sahanafoundation.org/index.php?title=Guidelines:Quality&diff=322 2026-10-29T13:36:55Z

<p>Dominic: </p> <hr /> <div>* [[Guidelines:Index|All Guidelines]]<br /> <br /> This guideline outlines criteria to evaluate the quality of a feature set or other solution detail, and can be used both to determine the current quality level and to set future development goals.<br /> <br /> = General Quality Requirements =<br /> <br /> The general quality requirements are defined here as attributes of the solution that is to be evaluated (&quot;The solution must be ...&quot;).<br /> <br /> These attributes are grouped in four quality &quot;levels&quot; - a higher level representing a higher quality standard. <br /> <br /> Projects can refer to these levels to define minimum quality goals, to prioritize certain quality aspects vs. other requirements, or to define an iterative approach of continuous quality improvement.<br /> <br /> In order to pass a level, all criteria of this level and all previous levels must be met.<br /> <br /> {| class=&quot;wikitable&quot; style=&quot;margin:auto&quot;<br /> |+ Quality Levels<br /> |-<br /> ! Level !! Priority (MoSCoW) !! Key Attributes !! Description<br /> |-<br /> ||0 - '''Experimental'''||-||-||any solution that does not (yet) meet all criteria of level 1||<br /> |-<br /> ||1 - '''Minimal'''||Must||[[#Valid| valid]], [[#Correct| correct]], [[#Safe| safe]]||minimum standard for any solution||<br /> |-<br /> ||2 - '''Appropriate'''||Should||[[#Usable| usable]], [[#Maintainable| maintainable]], [[#Secure| secure]]||minimum standard for production use||<br /> |-<br /> ||3 - '''Good'''||Can||[[#Consistent| consistent]], [[#Robust| robust]], [[#Configurable| configurable]]||long-term development goals||<br /> |-<br /> ||4 - '''Optimal'''||Want||[[#Efficient| efficient]], [[#Scalable| scalable]], [[#Interoperable| interoperable]]||optimization and enhancement goals||<br /> |}<br /> <br /> <br /> == Level 1: Minimal ==<br /> <br /> === Valid ===<br /> <br /> ''&quot;Writing the right code&quot;''<br /> <br /> * The specified solution solves the targeted problem and meets the minimum functional requirements<br /> * The required input data are available in the target scenario<br /> * The user actions required to apply and/or use the solution or its responses are ''possible'' in the target scenario<br /> * All dependencies of the feature set are resolvable, and hardware and infrastructure requirements can be met in the target scenario<br /> <br /> === Correct ===<br /> <br /> ''&quot;Writing the code right&quot;''<br /> <br /> * Processing does not fail for any valid input data or user action.<br /> * All responses are correct for the respective input data or user actions according to the specification<br /> <br /> === Safe ===<br /> <br /> * The solution does not break other functionality of the application (except for functionality it replaces or supersedes)<br /> * All processing always ends with a valid database status regardless whether it succeeds or fails<br /> * All failed processes are effectively removed from the system and their transactions properly rolled back<br /> * The solution effectively prevents uncontrolled indefinite object or process proliferation<br /> * The solution always returns to a defined system status after a failure so that the application remains accessible<br /> <br /> == Level 2: Appropriate ==<br /> <br /> === Usable ===<br /> <br /> * The solution ''can'' be used by the intended user group in the target scenario, i.e. the users can:<br /> ** discover and access the features<br /> ** understand and perform the required user actions<br /> ** understand and control the consequences of actions<br /> ** understand and provide the required type, quality and format of input data<br /> ** discover and access the results, and apply them to achieve their goals<br /> <br /> * Usability criteria apply analogously for back-end libraries and tools with developers in the role of the user<br /> <br /> === Maintainable ===<br /> <br /> * All critical dependencies are obvious at their starting point<br /> * All non-critical dependencies have meaningful fallbacks<br /> * Processing failures produce useful and accessible feedback about the reasons<br /> * The design of the solution does not obstruct diagnostics of defects<br /> * The code is structured in a way that the processing flow can easily be determined from it<br /> <br /> === Secure ===<br /> <br /> * The solution applies all relevant system configurations for authentication, authorization and accounting (AAA) appropriately and correctly.<br /> * The solution does not allow the user to perform actions or initiate processes beyond the intended functionality.<br /> <br /> == Level 3: Good ==<br /> <br /> === Consistent ===<br /> <br /> ''&quot;Maintaining Conceptual Integrity across the Application and beyond&quot;''<br /> <br /> * The solution applies the application framework appropriately and correctly<br /> * The data structures defined in the solution are consistent with the global application data model<br /> * The solution interoperates appropriately and correctly with other system components<br /> * The solution applies the application's global design and style guidelines (both for code and interfaces)<br /> * Where appropriate or required, the solution complies with specified standards (see [#Standards Standards])<br /> <br /> === Robust ===<br /> <br /> * The solution delivers consistent behavior, results and performance for all valid configurations<br /> * The solution handles invalid input data, unexpected user actions and irregular system conditions appropriately and consistently for all valid configurations<br /> * The solution detects invalid configurations and prevents any inadvertent effects that could result from them<br /> <br /> === Configurable ===<br /> <br /> * The solution can be easily and safely turned on and off without inadvertent side-effects (where appropriate, not for framework solutions)<br /> * The solution applies global configuration settings correctly and consistently<br /> * Processing parameters, behavior and/or appearance of the solution can be adapted to requirements variations using configuration patterns separate from its core code<br /> <br /> == Level 4: Optimal ==<br /> <br /> === Efficient ===<br /> <br /> * The solution provides acceptable performance with the minimum available hardware/infrastructure resources in the target scenario<br /> * The solution can be applied with minimal configuration effort<br /> * The solution can be applied, developed and maintained with minimal learning effort<br /> <br /> === Scalable ===<br /> <br /> * The solution can handle/adapt to varying problem sizes (e.g. amount of data, frequency of events) without failure, inconsistent behavior or significant loss of performance<br /> * The solution can utilize hardware/infrastructure enhancements and/or concurrency to provide better performance<br /> * The solution can be applied in any number of concurrent instances (given the appropriate hardware and infrastructure) without failure, inconsistent behavior or significant loss of performance<br /> <br /> === Interoperable ===<br /> <br /> * Different instances of the solution can, where appropriate or required, interchange data and/or process information<br /> * The solution can, where appropriate or required, interchange data and/or process information with other relevant solutions in the target scenario<br /> * The solution provides external APIs (application programming interfaces)<br /> <br /> = User Experience (UX) Requirements =<br /> <br /> ''Wikipedia: ISO 9241-210[1] defines user experience as &quot;a person's perceptions and responses that result from the use or anticipated use of a product, system or service&quot;. According to the ISO definition, user experience includes all the users' emotions, beliefs, preferences, perceptions, physical and psychological responses, behaviors and accomplishments that occur before, during and after use.''<br /> <br /> User experience, as a result of human-computer-interaction, involves various aspects of a software solution - both in view of its design, its functionality as well as its quality, but also personal aspects of the individual user (e.g. skills, previous experiences, cultural background), and of the situations and environments in which the software is to be used.<br /> <br /> &quot;Good UX&quot; is though not a requirement in itself - but the generic name for any additional design, functional and quality requirements in view of human-computer-interaction that may be defined for a solution, and which must be met in order to achieve certain quality levels.<br /> <br /> Even though UX as such appears to be a largely subjective matter, there are usually a number of generalizable UX requirements for any user interface.<br /> <br /> '''Example:''' ''User interfaces which are typically used in the darkness should not blind the user, but use a reduced palette of primarily reddish colors on dark background in order to cause less or no iris contraction. If the interface is though to be used under varying lighting conditions it should be adaptable (or even auto-adapt).''<br /> <br /> In order to be '''valid and accomplishable, UX requirements must be specific and clearly defined''' (like the above example) for the quality level for which they shall apply - even when their reasoning may be more complex sometimes.<br /> <br /> Some general quality requirements also influence the user experience (e.g. correctness, usability, efficiency), but are not specific for the use-case and therefore usually not separately discussed as UX requirements. They are however relevant for UX evaluations and should thus be taken into account in such analyses.<br /> <br /> = Advanced Quality Requirements =<br /> <br /> ''Advanced'' quality criteria can be used to compare different solutions, or to define quality roadmaps for particular feature sets beyond the standard criteria.<br /> <br /> Advanced quality criteria do not apply equally for all use-cases - in certain cases they may even constitute anti-patterns.<br /> <br /> Advanced quality criteria do not enhance the general quality level of a solution: a level-3 solution is still of better quality than a level-2 solution - regardless how many advanced criteria the level-2 solution meets.<br /> <br /> == Stability ==<br /> <br /> A solution is ''stable'' when its black-box model rarely changes, and it maintains backwards-compatibility and/or easy migration paths. Stable solutions are required for all critical dependencies, so that they can be built upon without risk for frequent regression issues or need for constant migration. Stability is especially critical in shared data models (i.e. where data are shared between different modules within the application or even across applications), and in authorization frameworks - and can thus be defined as quality requirement for a solution.<br /> <br /> Stability is typically perceived as a sign of maturity, but can actually be taken into account already during the initial solution design. Pragmatic approaches (e.g. integrated migration, or enforced backwards-compatibility) can create stability early on without limiting or obstructing further development.<br /> <br /> == Generalization ==<br /> <br /> Generalizable solutions are designed and/or implemented in a way that they can be generalized. Typically, they separate their core patterns/algorithms from the use-case specifics through parametrization and/or configuration patterns. This can be defined as an advanced quality requirement for a solution.<br /> <br /> Generalization means to modify and/or extend the core patterns/algorithms of the solution in a way that they can be re-used in other solutions which involve the same or similar functional requirements, thereby reducing future development efforts. There is a wide range of quality attributes - &quot;flexible&quot;, &quot;customizable&quot;, &quot;re-usable&quot;, &quot;extensible&quot;, just to name a few - all of which involve different degrees of and approaches to generalization.<br /> <br /> = Standards =<br /> <br /> Solutions can both define or implement standards (e.g. data standards, communication protocols, taxonomies). Standard compliance can be defined as quality requirement for a solution.<br /> <br /> Standards can define additional requirements beyond the immediate requirements of the targeted problem, which must however be met in order to comply with the standard. Such additional standard requirements would usually be seen as quality requirements under [[#Consistent| &quot;Consistency&quot;]] in level 3.</div>

Dominic https://eden.sahanafoundation.org/index.php?title=Guidelines:Quality&diff=321 2026-10-29T13:30:18Z

<p>Dominic: </p> <hr /> <div>* [[Guidelines:Index|All Guidelines]]<br /> <br /> = Solution Quality Evaluation Guideline =<br /> <br /> == General Quality Requirements ==<br /> <br /> The general quality requirements are defined here as attributes of the solution that is to be evaluated (&quot;The solution must be ...&quot;).<br /> <br /> These attributes are grouped in four quality &quot;levels&quot; - a higher level representing a higher quality standard. <br /> <br /> Projects can refer to these levels to define minimum quality goals, to prioritize certain quality aspects vs. other requirements, or to define an iterative approach of continuous quality improvement.<br /> <br /> In order to pass a level, all criteria of this level and all previous levels must be met.<br /> <br /> {| class=&quot;wikitable&quot; style=&quot;margin:auto&quot;<br /> |+ Quality Levels<br /> |-<br /> ! Level !! Priority (MoSCoW) !! Key Attributes !! Description<br /> |-<br /> ||0 - '''Experimental'''||-||-||any solution that does not (yet) meet all criteria of level 1||<br /> |-<br /> ||1 - '''Minimal'''||Must||[[#Valid| valid]], [[#Correct| correct]], [[#Safe| safe]]||minimum standard for any solution||<br /> |-<br /> ||2 - '''Appropriate'''||Should||[[#Usable| usable]], [[#Maintainable| maintainable]], [[#Secure| secure]]||minimum standard for production use||<br /> |-<br /> ||3 - '''Good'''||Can||[[#Consistent| consistent]], [[#Robust| robust]], [[#Configurable| configurable]]||long-term development goals||<br /> |-<br /> ||4 - '''Optimal'''||Want||[[#Efficient| efficient]], [[#Scalable| scalable]], [[#Interoperable| interoperable]]||optimization and enhancement goals||<br /> |}<br /> <br /> <br /> === Level 1: Minimal ===<br /> <br /> ==== Valid ====<br /> <br /> ''&quot;Writing the right code&quot;''<br /> <br /> * The specified solution solves the targeted problem and meets the minimum functional requirements<br /> * The required input data are available in the target scenario<br /> * The user actions required to apply and/or use the solution or its responses are ''possible'' in the target scenario<br /> * All dependencies of the feature set are resolvable, and hardware and infrastructure requirements can be met in the target scenario<br /> <br /> ==== Correct ====<br /> <br /> ''&quot;Writing the code right&quot;''<br /> <br /> * Processing does not fail for any valid input data or user action.<br /> * All responses are correct for the respective input data or user actions according to the specification<br /> <br /> ==== Safe ====<br /> <br /> * The solution does not break other functionality of the application (except for functionality it replaces or supersedes)<br /> * All processing always ends with a valid database status regardless whether it succeeds or fails<br /> * All failed processes are effectively removed from the system and their transactions properly rolled back<br /> * The solution effectively prevents uncontrolled indefinite object or process proliferation<br /> * The solution always returns to a defined system status after a failure so that the application remains accessible<br /> <br /> === Level 2: Appropriate ===<br /> <br /> ==== Usable ====<br /> <br /> * The solution ''can'' be used by the intended user group in the target scenario, i.e. the users can:<br /> ** discover and access the features<br /> ** understand and perform the required user actions<br /> ** understand and control the consequences of actions<br /> ** understand and provide the required type, quality and format of input data<br /> ** discover and access the results, and apply them to achieve their goals<br /> <br /> * Usability criteria apply analogously for back-end libraries and tools with developers in the role of the user<br /> <br /> ==== Maintainable ====<br /> <br /> * All critical dependencies are obvious at their starting point<br /> * All non-critical dependencies have meaningful fallbacks<br /> * Processing failures produce useful and accessible feedback about the reasons<br /> * The design of the solution does not obstruct diagnostics of defects<br /> * The code is structured in a way that the processing flow can easily be determined from it<br /> <br /> ==== Secure ====<br /> <br /> * The solution applies all relevant system configurations for authentication, authorization and accounting (AAA) appropriately and correctly.<br /> * The solution does not allow the user to perform actions or initiate processes beyond the intended functionality.<br /> <br /> === Level 3: Good ===<br /> <br /> ==== Consistent ====<br /> <br /> ''&quot;Maintaining Conceptual Integrity across the Application and beyond&quot;''<br /> <br /> * The solution applies the application framework appropriately and correctly<br /> * The data structures defined in the solution are consistent with the global application data model<br /> * The solution interoperates appropriately and correctly with other system components<br /> * The solution applies the application's global design and style guidelines (both for code and interfaces)<br /> * Where appropriate or required, the solution complies with specified standards (see [#Standards Standards])<br /> <br /> ==== Robust ====<br /> <br /> * The solution delivers consistent behavior, results and performance for all valid configurations<br /> * The solution handles invalid input data, unexpected user actions and irregular system conditions appropriately and consistently for all valid configurations<br /> * The solution detects invalid configurations and prevents any inadvertent effects that could result from them<br /> <br /> ==== Configurable ====<br /> <br /> * The solution can be easily and safely turned on and off without inadvertent side-effects (where appropriate, not for framework solutions)<br /> * The solution applies global configuration settings correctly and consistently<br /> * Processing parameters, behavior and/or appearance of the solution can be adapted to requirements variations using configuration patterns separate from its core code<br /> <br /> === Level 4: Optimal ===<br /> <br /> ==== Efficient ====<br /> <br /> * The solution provides acceptable performance with the minimum available hardware/infrastructure resources in the target scenario<br /> * The solution can be applied with minimal configuration effort<br /> * The solution can be applied, developed and maintained with minimal learning effort<br /> <br /> ==== Scalable ====<br /> <br /> * The solution can handle/adapt to varying problem sizes (e.g. amount of data, frequency of events) without failure, inconsistent behavior or significant loss of performance<br /> * The solution can utilize hardware/infrastructure enhancements and/or concurrency to provide better performance<br /> * The solution can be applied in any number of concurrent instances (given the appropriate hardware and infrastructure) without failure, inconsistent behavior or significant loss of performance<br /> <br /> ==== Interoperable ====<br /> <br /> * Different instances of the solution can, where appropriate or required, interchange data and/or process information<br /> * The solution can, where appropriate or required, interchange data and/or process information with other relevant solutions in the target scenario<br /> * The solution provides external APIs (application programming interfaces)<br /> <br /> == User Experience (UX) Requirements ==<br /> <br /> ''Wikipedia: ISO 9241-210[1] defines user experience as &quot;a person's perceptions and responses that result from the use or anticipated use of a product, system or service&quot;. According to the ISO definition, user experience includes all the users' emotions, beliefs, preferences, perceptions, physical and psychological responses, behaviors and accomplishments that occur before, during and after use.''<br /> <br /> User experience, as a result of human-computer-interaction, involves various aspects of a software solution - both in view of its design, its functionality as well as its quality, but also personal aspects of the individual user (e.g. skills, previous experiences, cultural background), and of the situations and environments in which the software is to be used.<br /> <br /> &quot;Good UX&quot; is though not a requirement in itself - but the generic name for any additional design, functional and quality requirements in view of human-computer-interaction that may be defined for a solution, and which must be met in order to achieve certain quality levels.<br /> <br /> Even though UX as such appears to be a largely subjective matter, there are usually a number of generalizable UX requirements for any user interface.<br /> <br /> '''Example:''' ''User interfaces which are typically used in the darkness should not blind the user, but use a reduced palette of primarily reddish colors on dark background in order to cause less or no iris contraction. If the interface is though to be used under varying lighting conditions it should be adaptable (or even auto-adapt).''<br /> <br /> In order to be '''valid and accomplishable, UX requirements must be specific and clearly defined''' (like the above example) for the quality level for which they shall apply - even when their reasoning may be more complex sometimes.<br /> <br /> Some general quality requirements also influence the user experience (e.g. correctness, usability, efficiency), but are not specific for the use-case and therefore usually not separately discussed as UX requirements. They are however relevant for UX evaluations and should thus be taken into account in such analyses.<br /> <br /> == Advanced Quality Requirements ==<br /> <br /> ''Advanced'' quality criteria can be used to compare different solutions, or to define quality roadmaps for particular feature sets beyond the standard criteria.<br /> <br /> Advanced quality criteria do not apply equally for all use-cases - in certain cases they may even constitute anti-patterns.<br /> <br /> Advanced quality criteria do not enhance the general quality level of a solution: a level-3 solution is still of better quality than a level-2 solution - regardless how many advanced criteria the level-2 solution meets.<br /> <br /> === Stability ===<br /> <br /> A solution is ''stable'' when its black-box model rarely changes, and it maintains backwards-compatibility and/or easy migration paths. Stable solutions are required for all critical dependencies, so that they can be built upon without risk for frequent regression issues or need for constant migration. Stability is especially critical in shared data models (i.e. where data are shared between different modules within the application or even across applications), and in authorization frameworks - and can thus be defined as quality requirement for a solution.<br /> <br /> Stability is typically perceived as a sign of maturity, but can actually be taken into account already during the initial solution design. Pragmatic approaches (e.g. integrated migration, or enforced backwards-compatibility) can create stability early on without limiting or obstructing further development.<br /> <br /> === Generalization ===<br /> <br /> Generalizable solutions are designed and/or implemented in a way that they can be generalized. Typically, they separate their core patterns/algorithms from the use-case specifics through parametrization and/or configuration patterns. This can be defined as an advanced quality requirement for a solution.<br /> <br /> Generalization means to modify and/or extend the core patterns/algorithms of the solution in a way that they can be re-used in other solutions which involve the same or similar functional requirements, thereby reducing future development efforts. There is a wide range of quality attributes - &quot;flexible&quot;, &quot;customizable&quot;, &quot;re-usable&quot;, &quot;extensible&quot;, just to name a few - all of which involve different degrees of and approaches to generalization.<br /> <br /> == Standards ==<br /> <br /> Solutions can both define or implement standards (e.g. data standards, communication protocols, taxonomies). Standard compliance can be defined as quality requirement for a solution.<br /> <br /> Standards can define additional requirements beyond the immediate requirements of the targeted problem, which must however be met in order to comply with the standard. Such additional standard requirements would usually be seen as quality requirements under [[#Consistent| &quot;Consistency&quot;]] in level 3.</div>

Dominic https://eden.sahanafoundation.org/index.php?title=Guidelines:Quality&diff=320 2026-10-29T13:28:42Z

<p>Dominic: /* Solution Quality Evaluation Guideline */</p> <hr /> <div>* [[Guidelines:Index|All Guidelines]]<br /> <br /> = Solution Quality Evaluation Guideline =<br /> <br /> == General Quality Requirements ==<br /> <br /> The general quality requirements are defined here as attributes of the solution that is to be evaluated (&quot;The solution must be ...&quot;).<br /> <br /> These attributes are grouped in four quality &quot;levels&quot; - a higher level representing a higher quality standard. <br /> <br /> Projects can refer to these levels to define minimum quality goals, to prioritize certain quality aspects vs. other requirements, or to define an iterative approach of continuous quality improvement.<br /> <br /> In order to pass a level, all criteria of this level and all previous levels must be met.<br /> <br /> {| class=&quot;wikitable&quot; style=&quot;margin:auto&quot;<br /> |+ Quality Levels<br /> |-<br /> ! Level !! Priority (MoSCoW) !! Key Attributes !! Description<br /> |-<br /> ||0 - '''Experimental'''||-||-||any solution that does not (yet) meet all criteria of level 1||<br /> |-<br /> ||1 - '''Minimal'''||Must||[[#Valid| valid]], [[#Correct| correct]], [[#Safe| safe]]||minimum standard for any solution||<br /> |-<br /> ||2 - '''Appropriate'''||Should||[[#Usable| usable]], [[#Maintainable| maintainable]], [[#Secure| secure]]||minimum standard for production use||<br /> |-<br /> ||3 - '''Good'''||Can||[[#Consistent| consistent]], [[#Robust| robust]], [[#Configurable| configurable]]||long-term development goals||<br /> |-<br /> ||4 - '''Optimal'''||Want||[[#Efficient| efficient]], [[#Scalable| scalable]], [[#Interoperable| interoperable]]||optimization and enhancement goals||<br /> |}<br /> === Level 1: Minimal ===<br /> <br /> ==== Valid ====<br /> <br /> ''&quot;Writing the right code&quot;''<br /> <br /> * The specified solution solves the targeted problem and meets the minimum functional requirements<br /> * The required input data are available in the target scenario<br /> * The user actions required to apply and/or use the solution or its responses are ''possible'' in the target scenario<br /> * All dependencies of the feature set are resolvable, and hardware and infrastructure requirements can be met in the target scenario<br /> <br /> ==== Correct ====<br /> <br /> ''&quot;Writing the code right&quot;''<br /> <br /> * Processing does not fail for any valid input data or user action.<br /> * All responses are correct for the respective input data or user actions according to the specification<br /> <br /> ==== Safe ====<br /> <br /> * The solution does not break other functionality of the application (except for functionality it replaces or supersedes)<br /> * All processing always ends with a valid database status regardless whether it succeeds or fails<br /> * All failed processes are effectively removed from the system and their transactions properly rolled back<br /> * The solution effectively prevents uncontrolled indefinite object or process proliferation<br /> * The solution always returns to a defined system status after a failure so that the application remains accessible<br /> <br /> === Level 2: Appropriate ===<br /> <br /> ==== Usable ====<br /> <br /> * The solution ''can'' be used by the intended user group in the target scenario, i.e. the users can:<br /> ** discover and access the features<br /> ** understand and perform the required user actions<br /> ** understand and control the consequences of actions<br /> ** understand and provide the required type, quality and format of input data<br /> ** discover and access the results, and apply them to achieve their goals<br /> <br /> * Usability criteria apply analogously for back-end libraries and tools with developers in the role of the user<br /> <br /> ==== Maintainable ====<br /> <br /> * All critical dependencies are obvious at their starting point<br /> * All non-critical dependencies have meaningful fallbacks<br /> * Processing failures produce useful and accessible feedback about the reasons<br /> * The design of the solution does not obstruct diagnostics of defects<br /> * The code is structured in a way that the processing flow can easily be determined from it<br /> <br /> ==== Secure ====<br /> <br /> * The solution applies all relevant system configurations for authentication, authorization and accounting (AAA) appropriately and correctly.<br /> * The solution does not allow the user to perform actions or initiate processes beyond the intended functionality.<br /> <br /> === Level 3: Good ===<br /> <br /> ==== Consistent ====<br /> <br /> ''&quot;Maintaining Conceptual Integrity across the Application and beyond&quot;''<br /> <br /> * The solution applies the application framework appropriately and correctly<br /> * The data structures defined in the solution are consistent with the global application data model<br /> * The solution interoperates appropriately and correctly with other system components<br /> * The solution applies the application's global design and style guidelines (both for code and interfaces)<br /> * Where appropriate or required, the solution complies with specified standards (see [#Standards Standards])<br /> <br /> ==== Robust ====<br /> <br /> * The solution delivers consistent behavior, results and performance for all valid configurations<br /> * The solution handles invalid input data, unexpected user actions and irregular system conditions appropriately and consistently for all valid configurations<br /> * The solution detects invalid configurations and prevents any inadvertent effects that could result from them<br /> <br /> ==== Configurable ====<br /> <br /> * The solution can be easily and safely turned on and off without inadvertent side-effects (where appropriate, not for framework solutions)<br /> * The solution applies global configuration settings correctly and consistently<br /> * Processing parameters, behavior and/or appearance of the solution can be adapted to requirements variations using configuration patterns separate from its core code<br /> <br /> === Level 4: Optimal ===<br /> <br /> ==== Efficient ====<br /> <br /> * The solution provides acceptable performance with the minimum available hardware/infrastructure resources in the target scenario<br /> * The solution can be applied with minimal configuration effort<br /> * The solution can be applied, developed and maintained with minimal learning effort<br /> <br /> ==== Scalable ====<br /> <br /> * The solution can handle/adapt to varying problem sizes (e.g. amount of data, frequency of events) without failure, inconsistent behavior or significant loss of performance<br /> * The solution can utilize hardware/infrastructure enhancements and/or concurrency to provide better performance<br /> * The solution can be applied in any number of concurrent instances (given the appropriate hardware and infrastructure) without failure, inconsistent behavior or significant loss of performance<br /> <br /> ==== Interoperable ====<br /> <br /> * Different instances of the solution can, where appropriate or required, interchange data and/or process information<br /> * The solution can, where appropriate or required, interchange data and/or process information with other relevant solutions in the target scenario<br /> * The solution provides external APIs (application programming interfaces)<br /> <br /> == User Experience (UX) Requirements ==<br /> <br /> ''Wikipedia: ISO 9241-210[1] defines user experience as &quot;a person's perceptions and responses that result from the use or anticipated use of a product, system or service&quot;. According to the ISO definition, user experience includes all the users' emotions, beliefs, preferences, perceptions, physical and psychological responses, behaviors and accomplishments that occur before, during and after use.''<br /> <br /> User experience, as a result of human-computer-interaction, involves various aspects of a software solution - both in view of its design, its functionality as well as its quality, but also personal aspects of the individual user (e.g. skills, previous experiences, cultural background), and of the situations and environments in which the software is to be used.<br /> <br /> &quot;Good UX&quot; is though not a requirement in itself - but the generic name for any additional design, functional and quality requirements in view of human-computer-interaction that may be defined for a solution, and which must be met in order to achieve certain quality levels.<br /> <br /> Even though UX as such appears to be a largely subjective matter, there are usually a number of generalizable UX requirements for any user interface.<br /> <br /> '''Example:''' ''User interfaces which are typically used in the darkness should not blind the user, but use a reduced palette of primarily reddish colors on dark background in order to cause less or no iris contraction. If the interface is though to be used under varying lighting conditions it should be adaptable (or even auto-adapt).''<br /> <br /> In order to be '''valid and accomplishable, UX requirements must be specific and clearly defined''' (like the above example) for the quality level for which they shall apply - even when their reasoning may be more complex sometimes.<br /> <br /> Some general quality requirements also influence the user experience (e.g. correctness, usability, efficiency), but are not specific for the use-case and therefore usually not separately discussed as UX requirements. They are however relevant for UX evaluations and should thus be taken into account in such analyses.<br /> <br /> == Advanced Quality Requirements ==<br /> <br /> ''Advanced'' quality criteria can be used to compare different solutions, or to define quality roadmaps for particular feature sets beyond the standard criteria.<br /> <br /> Advanced quality criteria do not apply equally for all use-cases - in certain cases they may even constitute anti-patterns.<br /> <br /> Advanced quality criteria do not enhance the general quality level of a solution: a level-3 solution is still of better quality than a level-2 solution - regardless how many advanced criteria the level-2 solution meets.<br /> <br /> === Stability ===<br /> <br /> A solution is ''stable'' when its black-box model rarely changes, and it maintains backwards-compatibility and/or easy migration paths. Stable solutions are required for all critical dependencies, so that they can be built upon without risk for frequent regression issues or need for constant migration. Stability is especially critical in shared data models (i.e. where data are shared between different modules within the application or even across applications), and in authorization frameworks - and can thus be defined as quality requirement for a solution.<br /> <br /> Stability is typically perceived as a sign of maturity, but can actually be taken into account already during the initial solution design. Pragmatic approaches (e.g. integrated migration, or enforced backwards-compatibility) can create stability early on without limiting or obstructing further development.<br /> <br /> === Generalization ===<br /> <br /> Generalizable solutions are designed and/or implemented in a way that they can be generalized. Typically, they separate their core patterns/algorithms from the use-case specifics through parametrization and/or configuration patterns. This can be defined as an advanced quality requirement for a solution.<br /> <br /> Generalization means to modify and/or extend the core patterns/algorithms of the solution in a way that they can be re-used in other solutions which involve the same or similar functional requirements, thereby reducing future development efforts. There is a wide range of quality attributes - &quot;flexible&quot;, &quot;customizable&quot;, &quot;re-usable&quot;, &quot;extensible&quot;, just to name a few - all of which involve different degrees of and approaches to generalization.<br /> <br /> == Standards ==<br /> <br /> Solutions can both define or implement standards (e.g. data standards, communication protocols, taxonomies). Standard compliance can be defined as quality requirement for a solution.<br /> <br /> Standards can define additional requirements beyond the immediate requirements of the targeted problem, which must however be met in order to comply with the standard. Such additional standard requirements would usually be seen as quality requirements under [[#Consistent| &quot;Consistency&quot;]] in level 3.</div>

Dominic https://eden.sahanafoundation.org/index.php?title=Guidelines:Quality&diff=319 2026-10-29T13:27:49Z

<p>Dominic: Created page with &quot;= Solution Quality Evaluation Guideline = == General Quality Requirements == The general quality requirements are defined here as attributes of the solution that is to be evaluated (&quot;The solution must be ...&quot;). These attributes are grouped in four quality &quot;levels&quot; - a higher level representing a higher quality standard. Projects can refer to these levels to define minimum quality goals, to prioritize certain quality aspects vs. other requirements, or to define an it...&quot;</p> <hr /> <div>= Solution Quality Evaluation Guideline =<br /> <br /> == General Quality Requirements ==<br /> <br /> The general quality requirements are defined here as attributes of the solution that is to be evaluated (&quot;The solution must be ...&quot;).<br /> <br /> These attributes are grouped in four quality &quot;levels&quot; - a higher level representing a higher quality standard. <br /> <br /> Projects can refer to these levels to define minimum quality goals, to prioritize certain quality aspects vs. other requirements, or to define an iterative approach of continuous quality improvement.<br /> <br /> In order to pass a level, all criteria of this level and all previous levels must be met.<br /> <br /> {| class=&quot;wikitable&quot; style=&quot;margin:auto&quot;<br /> |+ Quality Levels<br /> |-<br /> ! Level !! Priority (MoSCoW) !! Key Attributes !! Description<br /> |-<br /> ||0 - '''Experimental'''||-||-||any solution that does not (yet) meet all criteria of level 1||<br /> |-<br /> ||1 - '''Minimal'''||Must||[[#Valid| valid]], [[#Correct| correct]], [[#Safe| safe]]||minimum standard for any solution||<br /> |-<br /> ||2 - '''Appropriate'''||Should||[[#Usable| usable]], [[#Maintainable| maintainable]], [[#Secure| secure]]||minimum standard for production use||<br /> |-<br /> ||3 - '''Good'''||Can||[[#Consistent| consistent]], [[#Robust| robust]], [[#Configurable| configurable]]||long-term development goals||<br /> |-<br /> ||4 - '''Optimal'''||Want||[[#Efficient| efficient]], [[#Scalable| scalable]], [[#Interoperable| interoperable]]||optimization and enhancement goals||<br /> |}<br /> === Level 1: Minimal ===<br /> <br /> ==== Valid ====<br /> <br /> ''&quot;Writing the right code&quot;''<br /> <br /> * The specified solution solves the targeted problem and meets the minimum functional requirements<br /> * The required input data are available in the target scenario<br /> * The user actions required to apply and/or use the solution or its responses are ''possible'' in the target scenario<br /> * All dependencies of the feature set are resolvable, and hardware and infrastructure requirements can be met in the target scenario<br /> <br /> ==== Correct ====<br /> <br /> ''&quot;Writing the code right&quot;''<br /> <br /> * Processing does not fail for any valid input data or user action.<br /> * All responses are correct for the respective input data or user actions according to the specification<br /> <br /> ==== Safe ====<br /> <br /> * The solution does not break other functionality of the application (except for functionality it replaces or supersedes)<br /> * All processing always ends with a valid database status regardless whether it succeeds or fails<br /> * All failed processes are effectively removed from the system and their transactions properly rolled back<br /> * The solution effectively prevents uncontrolled indefinite object or process proliferation<br /> * The solution always returns to a defined system status after a failure so that the application remains accessible<br /> <br /> === Level 2: Appropriate ===<br /> <br /> ==== Usable ====<br /> <br /> * The solution ''can'' be used by the intended user group in the target scenario, i.e. the users can:<br /> ** discover and access the features<br /> ** understand and perform the required user actions<br /> ** understand and control the consequences of actions<br /> ** understand and provide the required type, quality and format of input data<br /> ** discover and access the results, and apply them to achieve their goals<br /> <br /> * Usability criteria apply analogously for back-end libraries and tools with developers in the role of the user<br /> <br /> ==== Maintainable ====<br /> <br /> * All critical dependencies are obvious at their starting point<br /> * All non-critical dependencies have meaningful fallbacks<br /> * Processing failures produce useful and accessible feedback about the reasons<br /> * The design of the solution does not obstruct diagnostics of defects<br /> * The code is structured in a way that the processing flow can easily be determined from it<br /> <br /> ==== Secure ====<br /> <br /> * The solution applies all relevant system configurations for authentication, authorization and accounting (AAA) appropriately and correctly.<br /> * The solution does not allow the user to perform actions or initiate processes beyond the intended functionality.<br /> <br /> === Level 3: Good ===<br /> <br /> ==== Consistent ====<br /> <br /> ''&quot;Maintaining Conceptual Integrity across the Application and beyond&quot;''<br /> <br /> * The solution applies the application framework appropriately and correctly<br /> * The data structures defined in the solution are consistent with the global application data model<br /> * The solution interoperates appropriately and correctly with other system components<br /> * The solution applies the application's global design and style guidelines (both for code and interfaces)<br /> * Where appropriate or required, the solution complies with specified standards (see [#Standards Standards])<br /> <br /> ==== Robust ====<br /> <br /> * The solution delivers consistent behavior, results and performance for all valid configurations<br /> * The solution handles invalid input data, unexpected user actions and irregular system conditions appropriately and consistently for all valid configurations<br /> * The solution detects invalid configurations and prevents any inadvertent effects that could result from them<br /> <br /> ==== Configurable ====<br /> <br /> * The solution can be easily and safely turned on and off without inadvertent side-effects (where appropriate, not for framework solutions)<br /> * The solution applies global configuration settings correctly and consistently<br /> * Processing parameters, behavior and/or appearance of the solution can be adapted to requirements variations using configuration patterns separate from its core code<br /> <br /> === Level 4: Optimal ===<br /> <br /> ==== Efficient ====<br /> <br /> * The solution provides acceptable performance with the minimum available hardware/infrastructure resources in the target scenario<br /> * The solution can be applied with minimal configuration effort<br /> * The solution can be applied, developed and maintained with minimal learning effort<br /> <br /> ==== Scalable ====<br /> <br /> * The solution can handle/adapt to varying problem sizes (e.g. amount of data, frequency of events) without failure, inconsistent behavior or significant loss of performance<br /> * The solution can utilize hardware/infrastructure enhancements and/or concurrency to provide better performance<br /> * The solution can be applied in any number of concurrent instances (given the appropriate hardware and infrastructure) without failure, inconsistent behavior or significant loss of performance<br /> <br /> ==== Interoperable ====<br /> <br /> * Different instances of the solution can, where appropriate or required, interchange data and/or process information<br /> * The solution can, where appropriate or required, interchange data and/or process information with other relevant solutions in the target scenario<br /> * The solution provides external APIs (application programming interfaces)<br /> <br /> == User Experience (UX) Requirements ==<br /> <br /> ''Wikipedia: ISO 9241-210[1] defines user experience as &quot;a person's perceptions and responses that result from the use or anticipated use of a product, system or service&quot;. According to the ISO definition, user experience includes all the users' emotions, beliefs, preferences, perceptions, physical and psychological responses, behaviors and accomplishments that occur before, during and after use.''<br /> <br /> User experience, as a result of human-computer-interaction, involves various aspects of a software solution - both in view of its design, its functionality as well as its quality, but also personal aspects of the individual user (e.g. skills, previous experiences, cultural background), and of the situations and environments in which the software is to be used.<br /> <br /> &quot;Good UX&quot; is though not a requirement in itself - but the generic name for any additional design, functional and quality requirements in view of human-computer-interaction that may be defined for a solution, and which must be met in order to achieve certain quality levels.<br /> <br /> Even though UX as such appears to be a largely subjective matter, there are usually a number of generalizable UX requirements for any user interface.<br /> <br /> '''Example:''' ''User interfaces which are typically used in the darkness should not blind the user, but use a reduced palette of primarily reddish colors on dark background in order to cause less or no iris contraction. If the interface is though to be used under varying lighting conditions it should be adaptable (or even auto-adapt).''<br /> <br /> In order to be '''valid and accomplishable, UX requirements must be specific and clearly defined''' (like the above example) for the quality level for which they shall apply - even when their reasoning may be more complex sometimes.<br /> <br /> Some general quality requirements also influence the user experience (e.g. correctness, usability, efficiency), but are not specific for the use-case and therefore usually not separately discussed as UX requirements. They are however relevant for UX evaluations and should thus be taken into account in such analyses.<br /> <br /> == Advanced Quality Requirements ==<br /> <br /> ''Advanced'' quality criteria can be used to compare different solutions, or to define quality roadmaps for particular feature sets beyond the standard criteria.<br /> <br /> Advanced quality criteria do not apply equally for all use-cases - in certain cases they may even constitute anti-patterns.<br /> <br /> Advanced quality criteria do not enhance the general quality level of a solution: a level-3 solution is still of better quality than a level-2 solution - regardless how many advanced criteria the level-2 solution meets.<br /> <br /> === Stability ===<br /> <br /> A solution is ''stable'' when its black-box model rarely changes, and it maintains backwards-compatibility and/or easy migration paths. Stable solutions are required for all critical dependencies, so that they can be built upon without risk for frequent regression issues or need for constant migration. Stability is especially critical in shared data models (i.e. where data are shared between different modules within the application or even across applications), and in authorization frameworks - and can thus be defined as quality requirement for a solution.<br /> <br /> Stability is typically perceived as a sign of maturity, but can actually be taken into account already during the initial solution design. Pragmatic approaches (e.g. integrated migration, or enforced backwards-compatibility) can create stability early on without limiting or obstructing further development.<br /> <br /> === Generalization ===<br /> <br /> Generalizable solutions are designed and/or implemented in a way that they can be generalized. Typically, they separate their core patterns/algorithms from the use-case specifics through parametrization and/or configuration patterns. This can be defined as an advanced quality requirement for a solution.<br /> <br /> Generalization means to modify and/or extend the core patterns/algorithms of the solution in a way that they can be re-used in other solutions which involve the same or similar functional requirements, thereby reducing future development efforts. There is a wide range of quality attributes - &quot;flexible&quot;, &quot;customizable&quot;, &quot;re-usable&quot;, &quot;extensible&quot;, just to name a few - all of which involve different degrees of and approaches to generalization.<br /> <br /> == Standards ==<br /> <br /> Solutions can both define or implement standards (e.g. data standards, communication protocols, taxonomies). Standard compliance can be defined as quality requirement for a solution.<br /> <br /> Standards can define additional requirements beyond the immediate requirements of the targeted problem, which must however be met in order to comply with the standard. Such additional standard requirements would usually be seen as quality requirements under [[#Consistent| &quot;Consistency&quot;]] in level 3.</div>

Dominic https://eden.sahanafoundation.org/index.php?title=Guidelines:CodingStyle&diff=318 2026-10-29T12:58:43Z

<p>Dominic: /* Internationalisation */</p> <hr /> <div>* [[Guidelines:Index|All Guidelines]]<br /> <br /> = General =<br /> <br /> The following conventions should be followed in all code.<br /> <br /> This facilitates a team of developers working on the same code base. If each developer were to use their own style, there would be jarring changes in the code as someone read through it. This slows comprehension and can also cause spurious differences in changesets as developers alter style in frivolous ways on the code they touch.<br /> <br /> Our style guide aims to make the code base appear as if it was written by one precise punctilious programmer, rather than a a cacophony of competing coders. As with many aspects of coding and writing, there can be differences of opinion about the best style. These issues distract from the goal of writing code that works. Most project contributors have a slightly different personal coding style, but we all use the Sahana Eden style when contributing to the Sahana Eden project.<br /> <br /> = Python =<br /> <br /> == Line-length and Indentation ==<br /> <br /> Use '''four spaces''' for indentation. <br /> <br /> Try to limit the length of code lines to '''80 characters''', where possible (PEP8). This is not a strict requirement, however:<br /> * a string literal making the line longer is acceptable as long as it is the last code element in that line<br /> * a line that is only slightly longer (up to 96 characters) is acceptable if it aids readability/comprehensibility<br /> <br /> == Quotes ==<br /> <br /> * for string literals in '''Python''' use double-quotes &lt;code&gt;&quot; &quot;&lt;/code&gt;, unless the string contains double-quotes<br /> * for triple-quoted strings (such as ''Docstrings'' or ''Inline-XML'') use &lt;code&gt;&quot;&quot;&quot; &quot;&quot;&quot;&lt;/code&gt; with double-quotes, except:<br /> * for ''Inline-JavaScript'' or ''JSON'' inside '''Python''' code use &lt;code&gt;&lt;nowiki&gt;''' '''&lt;/nowiki&gt;&lt;/code&gt; with single-quotes<br /> <br /> Note though that this:<br /> <br /> &lt;syntaxhighlight lang=&quot;python&quot;&gt;<br /> inline_javascript = '''sometext=&quot;%s&quot;;''' % sometext<br /> &lt;/syntaxhighlight&gt;<br /> <br /> is a '''potential bug and security risk''' - the script breaks when &lt;code&gt;sometext&lt;/code&gt; contains a &lt;code&gt;&quot;&lt;/code&gt;. A safer way to do that is:<br /> <br /> &lt;syntaxhighlight lang=&quot;python&quot;&gt;<br /> inline_javascript = '''sometext=%s;''' % json.dumps(sometext)<br /> &lt;/syntaxhighlight&gt;<br /> <br /> == Names ==<br /> <br /> Names should be obvious and explicit, but not overly verbose (i.e. as long as they need to be to not make people think). They shouldn't require someone to look in another file or solve a puzzle to figure out what they mean, but shouldn't take too long to write. Avoid inventing new acronyms. e.g. <br /> <br /> bad: &lt;code&gt; prm_lkp&lt;/code&gt;, &lt;code&gt;method_that_allows_us_to_create_a_gis_layer&lt;/code&gt;<br /> <br /> good: &lt;code&gt;personnel_search&lt;/code&gt;, &lt;code&gt;create_gis_layer&lt;/code&gt;<br /> <br /> * Class names start with an uppercase letter.<br /> * CamelCase is for class names only.<br /> * Constant names are all-uppercase and with underscores as word separator.<br /> * everything else (including table names and field names) should be all-lowercase with underscores as word separator.<br /> * Names should not be Python keywords or standard library names<br /> * Variable names should not start with _undersore (a trailing underscore_ is acceptable in local scope, though)<br /> * Indexes in names should be avoided (e.g. file1, file2), except where they designate new versions of classes/functions (e.g. AddPersonWidget2)<br /> <br /> * Names for Eden-specific subclasses of web2py classes and all classes which replace existing web2py classes should have the suffix &quot;S3&quot; (e.g. &lt;code&gt;AuthS3&lt;/code&gt;)<br /> * Names for Eden-specific methods (not overrides) in subclasses of web2py classes should start with the prefix &quot;s3_&quot; (e.g. &lt;code&gt;s3_logged_in()&lt;/code&gt;)<br /> * Eden-specific classes ''can'' have an &quot;S3&quot; prefix to their name in order to avoid name collisions, but ideally they ''should not'' (i.e. &lt;code&gt;BasicCRUD&lt;/code&gt; rather than &lt;code&gt;S3BasicCRUD&lt;/code&gt;)<br /> * Method names in Eden-specific classes do not need to (and thus should not) be prefixed<br /> * avoid &quot;s3&quot; or &quot;S3&quot; prefixes in all other cases<br /> <br /> * &lt;code&gt;DataModel&lt;/code&gt; subclasses in &lt;code&gt;s3db&lt;/code&gt; should start with the all-uppercase module prefix, e.g. &lt;code&gt;DVRCaseModel&lt;/code&gt;<br /> * &lt;code&gt;CRUDMethod&lt;/code&gt; subclasses in &lt;code&gt;s3db&lt;/code&gt; must start with the all-lowercase module prefix plus underscore, e.g. &lt;code&gt;pr_Contacts&lt;/code&gt;<br /> <br /> == Docstrings ==<br /> <br /> All classes and functions must have docstrings that explain what the class or function is intended for and how it is to be used. <br /> <br /> Exceptions can be made where the docstring would merely repeat documentation that already exists in another place, e.g. controllers, or standard interface methods inherited from (and thus documented in) a parent class.<br /> <br /> The function description in the docstring should be a statement in the third person about what the function does — not an imperative instruction telling it what to do.<br /> <br /> We follow loosely the ''Google Style Guide'' for docstrings in Python, albeit with additional indentation:<br /> <br /> &lt;syntaxhighlight lang=&quot;python&quot;&gt;<br /> def card_details(r, idcard):<br /> &quot;&quot;&quot;<br /> Displays the details of the new registration card, and offers<br /> a button to download the PDF.<br /> <br /> Args:<br /> (CRUDRequest) r: the request context<br /> (IDCard) idcard: the new registration card<br /> <br /> Returns:<br /> DIV: the card contents<br /> <br /> Raises:<br /> ValueError: if the idcard is invalid<br /> <br /> Note:<br /> Card secrets will not be rendered.<br /> &quot;&quot;&quot;<br /> &lt;/syntaxhighlight&gt;<br /> <br /> Except where they are obvious, '''data types''' of parameters and return value '''should be included''' in the docstring.<br /> <br /> To that end, '''PEP484-style type hints''' can also be acceptable in simple cases - but are '''discouraged''' for more complex parameter lists as they can easily impair comprehensibility, and not every syntax highlighter will aid the visual parsing of function annotations.<br /> <br /> &lt;syntaxhighlight lang=&quot;python&quot;&gt;<br /> def card_details(r: CRUDRequest, idcard: IDCard) -&gt; DIV:<br /> &quot;&quot;&quot;<br /> Displays the details of the new registration card, and offers<br /> a button to download the PDF<br /> <br /> Args:<br /> r: the request context<br /> idcard: the new registration card<br /> <br /> Returns:<br /> the card contents<br /> <br /> Raises:<br /> ValueError: if the idcard is invalid or expired<br /> <br /> Note:<br /> Card secrets will not be rendered.<br /> &quot;&quot;&quot;<br /> &lt;/syntaxhighlight&gt;<br /> <br /> == Comments ==<br /> <br /> Add comments so others can understand your code when they try to find bugs or improve/extend it. Comments in code should explain intent (or clarify techniques), not repeat the code (do not explain what is self-explaining).<br /> <br /> Poor:<br /> &lt;syntaxhighlight lang=&quot;python&quot;&gt;<br /> # Set free to True<br /> free = True<br /> &lt;/syntaxhighlight&gt;<br /> <br /> Good:<br /> &lt;syntaxhighlight lang=&quot;python&quot;&gt;<br /> # Indicate that the position is now free<br /> free = True<br /> &lt;/syntaxhighlight&gt;<br /> <br /> Commented code should have a comment explaining why it is commented.<br /> <br /> Unclear:<br /> &lt;syntaxhighlight lang=&quot;python&quot;&gt;<br /> #result = somefunction(somearg)<br /> result = 0<br /> &lt;/syntaxhighlight&gt;<br /> <br /> Better:<br /> &lt;syntaxhighlight lang=&quot;python&quot;&gt;<br /> # Not working yet, TODO: fix somefunction<br /> #result = somefunction(somearg)<br /> result = 0<br /> &lt;/syntaxhighlight&gt;<br /> <br /> == Internationalisation ==<br /> <br /> * All user-visible strings and labels ''must'' be internationalised: &lt;code&gt;T(&quot;My string&quot;)&lt;/code&gt;<br /> <br /> == Exception Handling ==<br /> <br /> Catching exceptions too broadly can easily hide programming errors, obscure problem causes, and introduce serious risks for data integrity and security. Be as specific as possible as to which (type of) exception is to be caught, and always have a good reason for catching it.<br /> <br /> Do not catch an exception (&quot;Let it crash&quot;) unless:<br /> * there is an immediate remedy or a meaningful alternative action, or<br /> * the exception can be transformed into a meaningful error message that the users can act upon, or<br /> * the exception needs to be logged (in which case it should be re-raised after logging)<br /> <br /> All critical exceptions on the server-side should be logged.<br /> <br /> Database exceptions should never be caught as they may block the current transaction and thus lead to another exception at a later point, obscuring the original cause of the problem.<br /> <br /> == Print Function ==<br /> <br /> For compatibility with WSGI as well as newer web2py (&gt;=2.15), using the &lt;code&gt;print()&lt;/code&gt; function in web application sources is '''strongly discouraged'''.<br /> <br /> For everything that is to be executed in the restricted environment (i.e. all server code):<br /> * for messages that are relevant during system setup (e.g. 1st run, module import failures etc.), use &lt;code&gt;&lt;nowiki&gt;sys.stderr.write()&lt;/nowiki&gt;&lt;/code&gt;<br /> * for run-time debug/error messages: use &lt;code&gt;&lt;nowiki&gt;current.log.*&lt;/nowiki&gt;&lt;/code&gt;, as it can be controlled centrally, and routed to a log file when web2py isn't console-run<br /> * for temporary debug output in code under development, use either &lt;code&gt;&lt;nowiki&gt;sys.stderr.write()&lt;/nowiki&gt;&lt;/code&gt; or &lt;code&gt;&lt;nowiki&gt;print(..., file=sys.stderr)&lt;/nowiki&gt;&lt;/code&gt;<br /> <br /> <br /> For CLI scripts:<br /> * use &lt;code&gt;&lt;nowiki&gt;sys.stderr.write()&lt;/nowiki&gt;&lt;/code&gt; for status/error messages, or &lt;code&gt;&lt;nowiki&gt;sys.stdout.write()&lt;/nowiki&gt;&lt;/code&gt; for results<br /> * alternatively, use the &lt;code&gt;&lt;nowiki&gt;print()&lt;/nowiki&gt;&lt;/code&gt;-function<br /> <br /> <br /> Using &lt;code&gt;&lt;nowiki&gt;sys.std*.write()&lt;/nowiki&gt;&lt;/code&gt; (remember that write expects string/buffer, so you must convert any parameters explicitly):<br /> <br /> &lt;syntaxhighlight lang=&quot;python&quot;&gt;<br /> import sys<br /> <br /> # For status/error/debug messages:<br /> sys.stderr.write(&quot;Here is a status message\n&quot;)<br /> <br /> # For results:<br /> sys.stdout.write(&quot;%s\n&quot; % result)<br /> &lt;/syntaxhighlight&gt;<br /> <br /> Using the logger:<br /> &lt;syntaxhighlight lang=&quot;python&quot;&gt;<br /> from gluon import current<br /> <br /> # Use this for any permanent message output in server code:<br /> current.log.error(&quot;Here is an error message&quot;)<br /> <br /> current.log.debug(&quot;And this is a debug message&quot;)<br /> &lt;/syntaxhighlight&gt;<br /> <br /> Using the print-function:<br /> &lt;syntaxhighlight lang=&quot;python&quot;&gt;<br /> import sys<br /> <br /> # Using the print-function in CLI scripts:<br /> print(&quot;The print-function&quot;, &quot;accepts&quot;, &quot;multiple arguments&quot;)<br /> <br /> # Remember that server code must write to stderr, not stdout:<br /> print(&quot;Direct output to stderr&quot;, file=sys.stderr)<br /> &lt;/syntaxhighlight&gt;<br /> <br /> = JavaScript =<br /> <br /> == Quotes ==<br /> <br /> * for string literals in '''JavaScript''' use single-quotes &lt;code&gt;' '&lt;/code&gt;, unless the string contains single-quotes<br /> <br /> == Names ==<br /> ''tbw''<br /> <br /> == Docstrings ==<br /> <br /> In JavaScript, we use Java Docstrings. Type specifications for parameters and return values are mandatory.<br /> <br /> &lt;syntaxhighlight lang=&quot;JavaScript&quot;&gt;<br /> /**<br /> * Retrieves events within a certain time interval.<br /> *<br /> * @param {moment|Date|string} start - the start of the interval<br /> * @param {moment|Date|string} end - the end of the interval<br /> *<br /> * @returns {Array} - the events within the interval,<br /> * or null if the interval is not completely cached<br /> */<br /> EventCache.prototype.retrieve = function(start, end) {<br /> ...<br /> };<br /> &lt;/syntaxhighlight&gt;<br /> <br /> = HTML / XML =<br /> <br /> == Quotes ==<br /> <br /> * for attributes in '''HTML''' (such as ''view templates'') use single-quotes &lt;code&gt;attr='value'&lt;/code&gt;<br /> * for attributes in other '''XML''' (e.g. ''XSLT'') use double-quotes &lt;code&gt;&quot; &quot;&lt;/code&gt; (inner quotes must be escaped anyway)</div>

Dominic https://eden.sahanafoundation.org/index.php?title=Main_Page&diff=317 2026-10-29T12:54:16Z

<p>Dominic: /* Project Conventions */</p> <hr /> <div>'''Sahana Eden''' is an ''Application Development Kit'' designed to build database-driven web applications tailored for emergency and humanitarian management. It provides a robust foundation for application developers and IT service providers to meet the information management needs of aid organizations and governmental agencies during emergencies, disaster preparedness, and humanitarian operations.<br /> <br /> Eden is '''free and open-source software''' (FOSS) that can be freely used, modified, extended, and integrated by anyone without restrictions.<br /> <br /> As an open project, Eden fosters collaboration and the exchange of knowledge, experiences, and best practices among humanitarian organizations. The project is guided by input from experienced aid organizations worldwide and emphasizes the use of open technology and standards. Nearly all of Eden’s code is developed in close cooperation with humanitarians in the field, ensuring it is directly aligned with real-world needs.<br /> <br /> == Implementing Eden ==<br /> <br /> Sahana Eden is a multi-purpose ''web application'' written for the [https://web2py.com web2py] framework. <br /> <br /> The appearance and business logic of this application can be adjusted to the needs of a particular deployment by altering settings in the &lt;code&gt;models/000_config.py&lt;/code&gt; configuration file on the server. Such adjustments can be minimal, or (more commonly) be extensive customization involving menus, forms, user roles, workflows, data models and even processing logic - so that Eden can be repurposed and adapted for many different use-cases and scenarios.<br /> <br /> Rather than putting all these customizations into one server-side configuration file, they would normally be implemented as Python packages which are then imported as '''configuration templates'''. This way, complex custom configurations can be developed, tested and maintained away from the server - and can easily be shared and re-used in other deployments.<br /> <br /> An '''Eden application''' is understood as such a re-usable configuration template (or a combination of templates), and '''Application Development''' is focused on these templates. <br /> <br /> A small selection of configuration templates is included in the Eden code base. However, downstream projects will often develop their own templates, and may publish and/or market them independently - a business model which we encourage and support.<br /> <br /> == Deploying Eden ==<br /> <br /> === Installation and Setup ===<br /> * [[Guidelines:Deployment|Deployment Guidelines]]<br /> <br /> == How to Contribute ==<br /> <br /> === What to Do ===<br /> <br /> ==== Code ====<br /> * [https://github.com/sahana/eden/issues Issues] are a good starting point for short-term contribution<br /> * [[Blueprint:Index|Blueprints]] describe more complex feature sets and requirements, best suited for longer-term contribution<br /> * Many core modules are looking for a maintainer, who takes long-term overall responsibility for their continuous development, support and documentation. Tell us on our [https://groups.google.com/g/eden-asp mailing list] what you would be interested in leading, and we will guide you to the role.<br /> <br /> ==== Documentation ====<br /> * Our [https://eden-asp.readthedocs.io/en/latest Handbook for Application Developers] needs continuous maintenance and improvement. You can work on the handbook in the [https://github.com/sahana/eden/tree/dev/docs/source code base].<br /> * If you want to contribute to this wiki, you can start by discussing your idea on our [https://groups.google.com/g/eden-asp mailing list] - we will then create a wiki account for you as needed.<br /> <br /> === Information Resources ===<br /> <br /> * [[Code Repository]]<br /> * [[Guidelines:ContributorWorkflow|Git Workflow for Code Contributions]]<br /> <br /> === Project Conventions ===<br /> <br /> * [[Guidelines:CodingStyle|Coding Conventions]]<br /> * [[Guidelines:AI|Policy for Responsible AI Contributions]]</div>

Dominic https://eden.sahanafoundation.org/index.php?title=Guidelines:Index&diff=316 2026-10-29T12:53:37Z

<p>Dominic: /* Contributor Guidelines */</p> <hr /> <div>== Implementer Guidelines ==<br /> <br /> * [[Guidelines:Deployment|Deployment Guidelines]]<br /> <br /> == Contributor Guidelines ==<br /> <br /> * [[Guidelines:ContributorWorkflow|Git Workflow for Code Contributions]]<br /> * [[Guidelines:CodingStyle|Coding Conventions]]<br /> * [[Guidelines:AI|Guideline for Responsible AI Contributions]]</div>

Dominic https://eden.sahanafoundation.org/index.php?title=Guidelines:CodingStyle&diff=315 2026-10-29T12:52:16Z

<p>Dominic: /* Python */</p> <hr /> <div>* [[Guidelines:Index|All Guidelines]]<br /> <br /> = General =<br /> <br /> The following conventions should be followed in all code.<br /> <br /> This facilitates a team of developers working on the same code base. If each developer were to use their own style, there would be jarring changes in the code as someone read through it. This slows comprehension and can also cause spurious differences in changesets as developers alter style in frivolous ways on the code they touch.<br /> <br /> Our style guide aims to make the code base appear as if it was written by one precise punctilious programmer, rather than a a cacophony of competing coders. As with many aspects of coding and writing, there can be differences of opinion about the best style. These issues distract from the goal of writing code that works. Most project contributors have a slightly different personal coding style, but we all use the Sahana Eden style when contributing to the Sahana Eden project.<br /> <br /> = Python =<br /> <br /> == Line-length and Indentation ==<br /> <br /> Use '''four spaces''' for indentation. <br /> <br /> Try to limit the length of code lines to '''80 characters''', where possible (PEP8). This is not a strict requirement, however:<br /> * a string literal making the line longer is acceptable as long as it is the last code element in that line<br /> * a line that is only slightly longer (up to 96 characters) is acceptable if it aids readability/comprehensibility<br /> <br /> == Quotes ==<br /> <br /> * for string literals in '''Python''' use double-quotes &lt;code&gt;&quot; &quot;&lt;/code&gt;, unless the string contains double-quotes<br /> * for triple-quoted strings (such as ''Docstrings'' or ''Inline-XML'') use &lt;code&gt;&quot;&quot;&quot; &quot;&quot;&quot;&lt;/code&gt; with double-quotes, except:<br /> * for ''Inline-JavaScript'' or ''JSON'' inside '''Python''' code use &lt;code&gt;&lt;nowiki&gt;''' '''&lt;/nowiki&gt;&lt;/code&gt; with single-quotes<br /> <br /> Note though that this:<br /> <br /> &lt;syntaxhighlight lang=&quot;python&quot;&gt;<br /> inline_javascript = '''sometext=&quot;%s&quot;;''' % sometext<br /> &lt;/syntaxhighlight&gt;<br /> <br /> is a '''potential bug and security risk''' - the script breaks when &lt;code&gt;sometext&lt;/code&gt; contains a &lt;code&gt;&quot;&lt;/code&gt;. A safer way to do that is:<br /> <br /> &lt;syntaxhighlight lang=&quot;python&quot;&gt;<br /> inline_javascript = '''sometext=%s;''' % json.dumps(sometext)<br /> &lt;/syntaxhighlight&gt;<br /> <br /> == Names ==<br /> <br /> Names should be obvious and explicit, but not overly verbose (i.e. as long as they need to be to not make people think). They shouldn't require someone to look in another file or solve a puzzle to figure out what they mean, but shouldn't take too long to write. Avoid inventing new acronyms. e.g. <br /> <br /> bad: &lt;code&gt; prm_lkp&lt;/code&gt;, &lt;code&gt;method_that_allows_us_to_create_a_gis_layer&lt;/code&gt;<br /> <br /> good: &lt;code&gt;personnel_search&lt;/code&gt;, &lt;code&gt;create_gis_layer&lt;/code&gt;<br /> <br /> * Class names start with an uppercase letter.<br /> * CamelCase is for class names only.<br /> * Constant names are all-uppercase and with underscores as word separator.<br /> * everything else (including table names and field names) should be all-lowercase with underscores as word separator.<br /> * Names should not be Python keywords or standard library names<br /> * Variable names should not start with _undersore (a trailing underscore_ is acceptable in local scope, though)<br /> * Indexes in names should be avoided (e.g. file1, file2), except where they designate new versions of classes/functions (e.g. AddPersonWidget2)<br /> <br /> * Names for Eden-specific subclasses of web2py classes and all classes which replace existing web2py classes should have the suffix &quot;S3&quot; (e.g. &lt;code&gt;AuthS3&lt;/code&gt;)<br /> * Names for Eden-specific methods (not overrides) in subclasses of web2py classes should start with the prefix &quot;s3_&quot; (e.g. &lt;code&gt;s3_logged_in()&lt;/code&gt;)<br /> * Eden-specific classes ''can'' have an &quot;S3&quot; prefix to their name in order to avoid name collisions, but ideally they ''should not'' (i.e. &lt;code&gt;BasicCRUD&lt;/code&gt; rather than &lt;code&gt;S3BasicCRUD&lt;/code&gt;)<br /> * Method names in Eden-specific classes do not need to (and thus should not) be prefixed<br /> * avoid &quot;s3&quot; or &quot;S3&quot; prefixes in all other cases<br /> <br /> * &lt;code&gt;DataModel&lt;/code&gt; subclasses in &lt;code&gt;s3db&lt;/code&gt; should start with the all-uppercase module prefix, e.g. &lt;code&gt;DVRCaseModel&lt;/code&gt;<br /> * &lt;code&gt;CRUDMethod&lt;/code&gt; subclasses in &lt;code&gt;s3db&lt;/code&gt; must start with the all-lowercase module prefix plus underscore, e.g. &lt;code&gt;pr_Contacts&lt;/code&gt;<br /> <br /> == Docstrings ==<br /> <br /> All classes and functions must have docstrings that explain what the class or function is intended for and how it is to be used. <br /> <br /> Exceptions can be made where the docstring would merely repeat documentation that already exists in another place, e.g. controllers, or standard interface methods inherited from (and thus documented in) a parent class.<br /> <br /> The function description in the docstring should be a statement in the third person about what the function does — not an imperative instruction telling it what to do.<br /> <br /> We follow loosely the ''Google Style Guide'' for docstrings in Python, albeit with additional indentation:<br /> <br /> &lt;syntaxhighlight lang=&quot;python&quot;&gt;<br /> def card_details(r, idcard):<br /> &quot;&quot;&quot;<br /> Displays the details of the new registration card, and offers<br /> a button to download the PDF.<br /> <br /> Args:<br /> (CRUDRequest) r: the request context<br /> (IDCard) idcard: the new registration card<br /> <br /> Returns:<br /> DIV: the card contents<br /> <br /> Raises:<br /> ValueError: if the idcard is invalid<br /> <br /> Note:<br /> Card secrets will not be rendered.<br /> &quot;&quot;&quot;<br /> &lt;/syntaxhighlight&gt;<br /> <br /> Except where they are obvious, '''data types''' of parameters and return value '''should be included''' in the docstring.<br /> <br /> To that end, '''PEP484-style type hints''' can also be acceptable in simple cases - but are '''discouraged''' for more complex parameter lists as they can easily impair comprehensibility, and not every syntax highlighter will aid the visual parsing of function annotations.<br /> <br /> &lt;syntaxhighlight lang=&quot;python&quot;&gt;<br /> def card_details(r: CRUDRequest, idcard: IDCard) -&gt; DIV:<br /> &quot;&quot;&quot;<br /> Displays the details of the new registration card, and offers<br /> a button to download the PDF<br /> <br /> Args:<br /> r: the request context<br /> idcard: the new registration card<br /> <br /> Returns:<br /> the card contents<br /> <br /> Raises:<br /> ValueError: if the idcard is invalid or expired<br /> <br /> Note:<br /> Card secrets will not be rendered.<br /> &quot;&quot;&quot;<br /> &lt;/syntaxhighlight&gt;<br /> <br /> == Internationalisation ==<br /> <br /> * All user-visible strings and labels ''must'' be internationalised: &lt;code&gt;T(&quot;My string&quot;)&lt;/code&gt;<br /> <br /> == Exception Handling ==<br /> <br /> Catching exceptions too broadly can easily hide programming errors, obscure problem causes, and introduce serious risks for data integrity and security. Be as specific as possible as to which (type of) exception is to be caught, and always have a good reason for catching it.<br /> <br /> Do not catch an exception (&quot;Let it crash&quot;) unless:<br /> * there is an immediate remedy or a meaningful alternative action, or<br /> * the exception can be transformed into a meaningful error message that the users can act upon, or<br /> * the exception needs to be logged (in which case it should be re-raised after logging)<br /> <br /> All critical exceptions on the server-side should be logged.<br /> <br /> Database exceptions should never be caught as they may block the current transaction and thus lead to another exception at a later point, obscuring the original cause of the problem.<br /> <br /> == Print Function ==<br /> <br /> For compatibility with WSGI as well as newer web2py (&gt;=2.15), using the &lt;code&gt;print()&lt;/code&gt; function in web application sources is '''strongly discouraged'''.<br /> <br /> For everything that is to be executed in the restricted environment (i.e. all server code):<br /> * for messages that are relevant during system setup (e.g. 1st run, module import failures etc.), use &lt;code&gt;&lt;nowiki&gt;sys.stderr.write()&lt;/nowiki&gt;&lt;/code&gt;<br /> * for run-time debug/error messages: use &lt;code&gt;&lt;nowiki&gt;current.log.*&lt;/nowiki&gt;&lt;/code&gt;, as it can be controlled centrally, and routed to a log file when web2py isn't console-run<br /> * for temporary debug output in code under development, use either &lt;code&gt;&lt;nowiki&gt;sys.stderr.write()&lt;/nowiki&gt;&lt;/code&gt; or &lt;code&gt;&lt;nowiki&gt;print(..., file=sys.stderr)&lt;/nowiki&gt;&lt;/code&gt;<br /> <br /> <br /> For CLI scripts:<br /> * use &lt;code&gt;&lt;nowiki&gt;sys.stderr.write()&lt;/nowiki&gt;&lt;/code&gt; for status/error messages, or &lt;code&gt;&lt;nowiki&gt;sys.stdout.write()&lt;/nowiki&gt;&lt;/code&gt; for results<br /> * alternatively, use the &lt;code&gt;&lt;nowiki&gt;print()&lt;/nowiki&gt;&lt;/code&gt;-function<br /> <br /> <br /> Using &lt;code&gt;&lt;nowiki&gt;sys.std*.write()&lt;/nowiki&gt;&lt;/code&gt; (remember that write expects string/buffer, so you must convert any parameters explicitly):<br /> <br /> &lt;syntaxhighlight lang=&quot;python&quot;&gt;<br /> import sys<br /> <br /> # For status/error/debug messages:<br /> sys.stderr.write(&quot;Here is a status message\n&quot;)<br /> <br /> # For results:<br /> sys.stdout.write(&quot;%s\n&quot; % result)<br /> &lt;/syntaxhighlight&gt;<br /> <br /> Using the logger:<br /> &lt;syntaxhighlight lang=&quot;python&quot;&gt;<br /> from gluon import current<br /> <br /> # Use this for any permanent message output in server code:<br /> current.log.error(&quot;Here is an error message&quot;)<br /> <br /> current.log.debug(&quot;And this is a debug message&quot;)<br /> &lt;/syntaxhighlight&gt;<br /> <br /> Using the print-function:<br /> &lt;syntaxhighlight lang=&quot;python&quot;&gt;<br /> import sys<br /> <br /> # Using the print-function in CLI scripts:<br /> print(&quot;The print-function&quot;, &quot;accepts&quot;, &quot;multiple arguments&quot;)<br /> <br /> # Remember that server code must write to stderr, not stdout:<br /> print(&quot;Direct output to stderr&quot;, file=sys.stderr)<br /> &lt;/syntaxhighlight&gt;<br /> <br /> = JavaScript =<br /> <br /> == Quotes ==<br /> <br /> * for string literals in '''JavaScript''' use single-quotes &lt;code&gt;' '&lt;/code&gt;, unless the string contains single-quotes<br /> <br /> == Names ==<br /> ''tbw''<br /> <br /> == Docstrings ==<br /> <br /> In JavaScript, we use Java Docstrings. Type specifications for parameters and return values are mandatory.<br /> <br /> &lt;syntaxhighlight lang=&quot;JavaScript&quot;&gt;<br /> /**<br /> * Retrieves events within a certain time interval.<br /> *<br /> * @param {moment|Date|string} start - the start of the interval<br /> * @param {moment|Date|string} end - the end of the interval<br /> *<br /> * @returns {Array} - the events within the interval,<br /> * or null if the interval is not completely cached<br /> */<br /> EventCache.prototype.retrieve = function(start, end) {<br /> ...<br /> };<br /> &lt;/syntaxhighlight&gt;<br /> <br /> = HTML / XML =<br /> <br /> == Quotes ==<br /> <br /> * for attributes in '''HTML''' (such as ''view templates'') use single-quotes &lt;code&gt;attr='value'&lt;/code&gt;<br /> * for attributes in other '''XML''' (e.g. ''XSLT'') use double-quotes &lt;code&gt;&quot; &quot;&lt;/code&gt; (inner quotes must be escaped anyway)</div>

Dominic https://eden.sahanafoundation.org/index.php?title=Guidelines:CodingStyle&diff=314 2026-10-29T12:26:37Z

<p>Dominic: /* Python */</p> <hr /> <div>* [[Guidelines:Index|All Guidelines]]<br /> <br /> = General =<br /> <br /> The following conventions should be followed in all code.<br /> <br /> This facilitates a team of developers working on the same code base. If each developer were to use their own style, there would be jarring changes in the code as someone read through it. This slows comprehension and can also cause spurious differences in changesets as developers alter style in frivolous ways on the code they touch.<br /> <br /> Our style guide aims to make the code base appear as if it was written by one precise punctilious programmer, rather than a a cacophony of competing coders. As with many aspects of coding and writing, there can be differences of opinion about the best style. These issues distract from the goal of writing code that works. Most project contributors have a slightly different personal coding style, but we all use the Sahana Eden style when contributing to the Sahana Eden project.<br /> <br /> = Python =<br /> <br /> == Quotes ==<br /> <br /> * for string literals in '''Python''' use double-quotes &lt;code&gt;&quot; &quot;&lt;/code&gt;, unless the string contains double-quotes<br /> * for triple-quoted strings (such as ''Docstrings'' or ''Inline-XML'') use &lt;code&gt;&quot;&quot;&quot; &quot;&quot;&quot;&lt;/code&gt; with double-quotes, except:<br /> * for ''Inline-JavaScript'' or ''JSON'' inside '''Python''' code use &lt;code&gt;&lt;nowiki&gt;''' '''&lt;/nowiki&gt;&lt;/code&gt; with single-quotes<br /> <br /> Note though that this:<br /> <br /> &lt;syntaxhighlight lang=&quot;python&quot;&gt;<br /> inline_javascript = '''sometext=&quot;%s&quot;;''' % sometext<br /> &lt;/syntaxhighlight&gt;<br /> <br /> is a '''potential bug and security risk''' - the script breaks when &lt;code&gt;sometext&lt;/code&gt; contains a &lt;code&gt;&quot;&lt;/code&gt;. A safer way to do that is:<br /> <br /> &lt;syntaxhighlight lang=&quot;python&quot;&gt;<br /> inline_javascript = '''sometext=%s;''' % json.dumps(sometext)<br /> &lt;/syntaxhighlight&gt;<br /> <br /> == Names ==<br /> <br /> Names should be obvious and explicit, but not overly verbose (i.e. as long as they need to be to not make people think). They shouldn't require someone to look in another file or solve a puzzle to figure out what they mean, but shouldn't take too long to write. Avoid inventing new acronyms. e.g. <br /> <br /> bad: &lt;code&gt; prm_lkp&lt;/code&gt;, &lt;code&gt;method_that_allows_us_to_create_a_gis_layer&lt;/code&gt;<br /> <br /> good: &lt;code&gt;personnel_search&lt;/code&gt;, &lt;code&gt;create_gis_layer&lt;/code&gt;<br /> <br /> * Class names start with an uppercase letter.<br /> * CamelCase is for class names only.<br /> * Constant names are all-uppercase and with underscores as word separator.<br /> * everything else (including table names and field names) should be all-lowercase with underscores as word separator.<br /> * Names should not be Python keywords or standard library names<br /> * Variable names should not start with _undersore (a trailing underscore_ is acceptable in local scope, though)<br /> * Indexes in names should be avoided (e.g. file1, file2), except where they designate new versions of classes/functions (e.g. AddPersonWidget2)<br /> <br /> * Names for Eden-specific subclasses of web2py classes and all classes which replace existing web2py classes should have the suffix &quot;S3&quot; (e.g. &lt;code&gt;AuthS3&lt;/code&gt;)<br /> * Names for Eden-specific methods (not overrides) in subclasses of web2py classes should start with the prefix &quot;s3_&quot; (e.g. &lt;code&gt;s3_logged_in()&lt;/code&gt;)<br /> * Eden-specific classes ''can'' have an &quot;S3&quot; prefix to their name in order to avoid name collisions, but ideally they ''should not'' (i.e. &lt;code&gt;BasicCRUD&lt;/code&gt; rather than &lt;code&gt;S3BasicCRUD&lt;/code&gt;)<br /> * Method names in Eden-specific classes do not need to (and thus should not) be prefixed<br /> * avoid &quot;s3&quot; or &quot;S3&quot; prefixes in all other cases<br /> <br /> * &lt;code&gt;DataModel&lt;/code&gt; subclasses in &lt;code&gt;s3db&lt;/code&gt; should start with the all-uppercase module prefix, e.g. &lt;code&gt;DVRCaseModel&lt;/code&gt;<br /> * &lt;code&gt;CRUDMethod&lt;/code&gt; subclasses in &lt;code&gt;s3db&lt;/code&gt; must start with the all-lowercase module prefix plus underscore, e.g. &lt;code&gt;pr_Contacts&lt;/code&gt;<br /> <br /> == Docstrings ==<br /> <br /> All classes and functions must have docstrings that explain what the class or function is intended for and how it is to be used. <br /> <br /> Exceptions can be made where the docstring would merely repeat documentation that already exists in another place, e.g. controllers, or standard interface methods inherited from (and thus documented in) a parent class.<br /> <br /> The function description in the docstring should be a statement in the third person about what the function does — not an imperative instruction telling it what to do.<br /> <br /> We follow loosely the ''Google Style Guide'' for docstrings in Python, albeit with additional indentation:<br /> <br /> &lt;syntaxhighlight lang=&quot;python&quot;&gt;<br /> def card_details(r, idcard):<br /> &quot;&quot;&quot;<br /> Displays the details of the new registration card, and offers<br /> a button to download the PDF.<br /> <br /> Args:<br /> (CRUDRequest) r: the request context<br /> (IDCard) idcard: the new registration card<br /> <br /> Returns:<br /> DIV: the card contents<br /> <br /> Raises:<br /> ValueError: if the idcard is invalid<br /> <br /> Note:<br /> Card secrets will not be rendered.<br /> &quot;&quot;&quot;<br /> &lt;/syntaxhighlight&gt;<br /> <br /> Except where they are obvious, '''data types''' of parameters and return value '''should be included''' in the docstring.<br /> <br /> To that end, '''PEP484-style type hints''' can also be acceptable in simple cases - but are '''discouraged''' for more complex parameter lists as they can easily impair comprehensibility, and not every syntax highlighter will aid the visual parsing of function annotations.<br /> <br /> &lt;syntaxhighlight lang=&quot;python&quot;&gt;<br /> def card_details(r: CRUDRequest, idcard: IDCard) -&gt; DIV:<br /> &quot;&quot;&quot;<br /> Displays the details of the new registration card, and offers<br /> a button to download the PDF<br /> <br /> Args:<br /> r: the request context<br /> idcard: the new registration card<br /> <br /> Returns:<br /> the card contents<br /> <br /> Raises:<br /> ValueError: if the idcard is invalid or expired<br /> <br /> Note:<br /> Card secrets will not be rendered.<br /> &quot;&quot;&quot;<br /> &lt;/syntaxhighlight&gt;<br /> <br /> == Internationalisation ==<br /> <br /> * All user-visible strings and labels ''must'' be internationalised: &lt;code&gt;T(&quot;My string&quot;)&lt;/code&gt;<br /> <br /> == Exception Handling ==<br /> <br /> Catching exceptions too broadly can easily hide programming errors, obscure problem causes, and introduce serious risks for data integrity and security. Be as specific as possible as to which (type of) exception is to be caught, and always have a good reason for catching it.<br /> <br /> Do not catch an exception (&quot;Let it crash&quot;) unless:<br /> * there is an immediate remedy or a meaningful alternative action, or<br /> * the exception can be transformed into a meaningful error message that the users can act upon, or<br /> * the exception needs to be logged (in which case it should be re-raised after logging)<br /> <br /> All critical exceptions on the server-side should be logged.<br /> <br /> Database exceptions should never be caught as they may block the current transaction and thus lead to another exception at a later point, obscuring the original cause of the problem.<br /> <br /> == Print Function ==<br /> <br /> For compatibility with WSGI as well as newer web2py (&gt;=2.15), using the &lt;code&gt;print()&lt;/code&gt; function in web application sources is '''strongly discouraged'''.<br /> <br /> For everything that is to be executed in the restricted environment (i.e. all server code):<br /> * for messages that are relevant during system setup (e.g. 1st run, module import failures etc.), use &lt;code&gt;&lt;nowiki&gt;sys.stderr.write()&lt;/nowiki&gt;&lt;/code&gt;<br /> * for run-time debug/error messages: use &lt;code&gt;&lt;nowiki&gt;current.log.*&lt;/nowiki&gt;&lt;/code&gt;, as it can be controlled centrally, and routed to a log file when web2py isn't console-run<br /> * for temporary debug output in code under development, use either &lt;code&gt;&lt;nowiki&gt;sys.stderr.write()&lt;/nowiki&gt;&lt;/code&gt; or &lt;code&gt;&lt;nowiki&gt;print(..., file=sys.stderr)&lt;/nowiki&gt;&lt;/code&gt;<br /> <br /> <br /> For CLI scripts:<br /> * use &lt;code&gt;&lt;nowiki&gt;sys.stderr.write()&lt;/nowiki&gt;&lt;/code&gt; for status/error messages, or &lt;code&gt;&lt;nowiki&gt;sys.stdout.write()&lt;/nowiki&gt;&lt;/code&gt; for results<br /> * alternatively, use the &lt;code&gt;&lt;nowiki&gt;print()&lt;/nowiki&gt;&lt;/code&gt;-function<br /> <br /> <br /> Using &lt;code&gt;&lt;nowiki&gt;sys.std*.write()&lt;/nowiki&gt;&lt;/code&gt; (remember that write expects string/buffer, so you must convert any parameters explicitly):<br /> <br /> &lt;syntaxhighlight lang=&quot;python&quot;&gt;<br /> import sys<br /> <br /> # For status/error/debug messages:<br /> sys.stderr.write(&quot;Here is a status message\n&quot;)<br /> <br /> # For results:<br /> sys.stdout.write(&quot;%s\n&quot; % result)<br /> &lt;/syntaxhighlight&gt;<br /> <br /> Using the logger:<br /> &lt;syntaxhighlight lang=&quot;python&quot;&gt;<br /> from gluon import current<br /> <br /> # Use this for any permanent message output in server code:<br /> current.log.error(&quot;Here is an error message&quot;)<br /> <br /> current.log.debug(&quot;And this is a debug message&quot;)<br /> &lt;/syntaxhighlight&gt;<br /> <br /> Using the print-function:<br /> &lt;syntaxhighlight lang=&quot;python&quot;&gt;<br /> import sys<br /> <br /> # Using the print-function in CLI scripts:<br /> print(&quot;The print-function&quot;, &quot;accepts&quot;, &quot;multiple arguments&quot;)<br /> <br /> # Remember that server code must write to stderr, not stdout:<br /> print(&quot;Direct output to stderr&quot;, file=sys.stderr)<br /> &lt;/syntaxhighlight&gt;<br /> <br /> = JavaScript =<br /> <br /> == Quotes ==<br /> <br /> * for string literals in '''JavaScript''' use single-quotes &lt;code&gt;' '&lt;/code&gt;, unless the string contains single-quotes<br /> <br /> == Names ==<br /> ''tbw''<br /> <br /> == Docstrings ==<br /> <br /> In JavaScript, we use Java Docstrings. Type specifications for parameters and return values are mandatory.<br /> <br /> &lt;syntaxhighlight lang=&quot;JavaScript&quot;&gt;<br /> /**<br /> * Retrieves events within a certain time interval.<br /> *<br /> * @param {moment|Date|string} start - the start of the interval<br /> * @param {moment|Date|string} end - the end of the interval<br /> *<br /> * @returns {Array} - the events within the interval,<br /> * or null if the interval is not completely cached<br /> */<br /> EventCache.prototype.retrieve = function(start, end) {<br /> ...<br /> };<br /> &lt;/syntaxhighlight&gt;<br /> <br /> = HTML / XML =<br /> <br /> == Quotes ==<br /> <br /> * for attributes in '''HTML''' (such as ''view templates'') use single-quotes &lt;code&gt;attr='value'&lt;/code&gt;<br /> * for attributes in other '''XML''' (e.g. ''XSLT'') use double-quotes &lt;code&gt;&quot; &quot;&lt;/code&gt; (inner quotes must be escaped anyway)</div>

Dominic https://eden.sahanafoundation.org/index.php?title=Guidelines:CodingStyle&diff=313 2026-10-29T12:14:12Z

<p>Dominic: /* JavaScript */</p> <hr /> <div>* [[Guidelines:Index|All Guidelines]]<br /> <br /> = General =<br /> <br /> The following conventions should be followed in all code.<br /> <br /> This facilitates a team of developers working on the same code base. If each developer were to use their own style, there would be jarring changes in the code as someone read through it. This slows comprehension and can also cause spurious differences in changesets as developers alter style in frivolous ways on the code they touch.<br /> <br /> Our style guide aims to make the code base appear as if it was written by one precise punctilious programmer, rather than a a cacophony of competing coders. As with many aspects of coding and writing, there can be differences of opinion about the best style. These issues distract from the goal of writing code that works. Most project contributors have a slightly different personal coding style, but we all use the Sahana Eden style when contributing to the Sahana Eden project.<br /> <br /> = Python =<br /> <br /> == Quotes ==<br /> <br /> * for string literals in '''Python''' use double-quotes &lt;code&gt;&quot; &quot;&lt;/code&gt;, unless the string contains double-quotes<br /> * for triple-quoted strings (such as ''Docstrings'' or ''Inline-XML'') use &lt;code&gt;&quot;&quot;&quot; &quot;&quot;&quot;&lt;/code&gt; with double-quotes, except:<br /> * for ''Inline-JavaScript'' or ''JSON'' inside '''Python''' code use &lt;code&gt;&lt;nowiki&gt;''' '''&lt;/nowiki&gt;&lt;/code&gt; with single-quotes<br /> <br /> Note though that this:<br /> <br /> &lt;syntaxhighlight lang=&quot;python&quot;&gt;<br /> inline_javascript = '''sometext=&quot;%s&quot;;''' % sometext<br /> &lt;/syntaxhighlight&gt;<br /> <br /> is a '''potential bug and security risk''' - the script breaks when &lt;code&gt;sometext&lt;/code&gt; contains a &lt;code&gt;&quot;&lt;/code&gt;. A safer way to do that is:<br /> <br /> &lt;syntaxhighlight lang=&quot;python&quot;&gt;<br /> inline_javascript = '''sometext=%s;''' % json.dumps(sometext)<br /> &lt;/syntaxhighlight&gt;<br /> <br /> == Names ==<br /> <br /> Names should be obvious and explicit, but not overly verbose (i.e. as long as they need to be to not make people think). They shouldn't require someone to look in another file or solve a puzzle to figure out what they mean, but shouldn't take too long to write. Avoid inventing new acronyms. e.g. <br /> <br /> bad: &lt;code&gt; prm_lkp&lt;/code&gt;, &lt;code&gt;method_that_allows_us_to_create_a_gis_layer&lt;/code&gt;<br /> <br /> good: &lt;code&gt;personnel_search&lt;/code&gt;, &lt;code&gt;create_gis_layer&lt;/code&gt;<br /> <br /> * Class names start with an uppercase letter.<br /> * CamelCase is for class names only.<br /> * Constant names are all-uppercase and with underscores as word separator.<br /> * everything else (including table names and field names) should be all-lowercase with underscores as word separator.<br /> * Names should not be Python keywords or standard library names<br /> * Variable names should not start with _undersore (a trailing underscore_ is acceptable in local scope, though)<br /> * Indexes in names should be avoided (e.g. file1, file2), except where they designate new versions of classes/functions (e.g. AddPersonWidget2)<br /> <br /> * Names for Eden-specific subclasses of web2py classes and all classes which replace existing web2py classes should have the suffix &quot;S3&quot; (e.g. &lt;code&gt;AuthS3&lt;/code&gt;)<br /> * Names for Eden-specific methods (not overrides) in subclasses of web2py classes should start with the prefix &quot;s3_&quot; (e.g. &lt;code&gt;s3_logged_in()&lt;/code&gt;)<br /> * Eden-specific classes ''can'' have an &quot;S3&quot; prefix to their name in order to avoid name collisions, but ideally they ''should not'' (i.e. &lt;code&gt;BasicCRUD&lt;/code&gt; rather than &lt;code&gt;S3BasicCRUD&lt;/code&gt;)<br /> * Method names in Eden-specific classes do not need to (and thus should not) be prefixed<br /> * avoid &quot;s3&quot; or &quot;S3&quot; prefixes in all other cases<br /> <br /> * &lt;code&gt;DataModel&lt;/code&gt; subclasses in &lt;code&gt;s3db&lt;/code&gt; should start with the all-uppercase module prefix, e.g. &lt;code&gt;DVRCaseModel&lt;/code&gt;<br /> * &lt;code&gt;CRUDMethod&lt;/code&gt; subclasses in &lt;code&gt;s3db&lt;/code&gt; must start with the all-lowercase module prefix plus underscore, e.g. &lt;code&gt;pr_Contacts&lt;/code&gt;<br /> <br /> == Docstrings ==<br /> <br /> All classes and functions must have docstrings that explain what the class or function is intended for and how it is to be used. <br /> <br /> Exceptions can be made where the docstring would merely repeat documentation that already exists in another place, e.g. controllers, or standard interface methods inherited from (and thus documented in) a parent class.<br /> <br /> The function description in the docstring should be a statement in the third person about what the function does — not an imperative instruction telling it what to do.<br /> <br /> We follow loosely the ''Google Style Guide'' for docstrings in Python, albeit with additional indentation:<br /> <br /> &lt;syntaxhighlight lang=&quot;python&quot;&gt;<br /> def card_details(r, idcard):<br /> &quot;&quot;&quot;<br /> Displays the details of the new registration card, and offers<br /> a button to download the PDF.<br /> <br /> Args:<br /> (CRUDRequest) r: the request context<br /> (IDCard) idcard: the new registration card<br /> <br /> Returns:<br /> DIV: the card contents<br /> <br /> Raises:<br /> ValueError: if the idcard is invalid<br /> <br /> Note:<br /> Card secrets will not be rendered.<br /> &quot;&quot;&quot;<br /> &lt;/syntaxhighlight&gt;<br /> <br /> Except where they are obvious, '''data types''' of parameters and return value '''should be included''' in the docstring.<br /> <br /> To that end, '''PEP484-style type hints''' can also be acceptable in simple cases - but are '''discouraged''' for more complex parameter lists as they can easily impair comprehensibility, and not every syntax highlighter will aid the visual parsing of function annotations.<br /> <br /> &lt;syntaxhighlight lang=&quot;python&quot;&gt;<br /> def card_details(r: CRUDRequest, idcard: IDCard) -&gt; DIV:<br /> &quot;&quot;&quot;<br /> Displays the details of the new registration card, and offers<br /> a button to download the PDF<br /> <br /> Args:<br /> r: the request context<br /> idcard: the new registration card<br /> <br /> Returns:<br /> the card contents<br /> <br /> Raises:<br /> ValueError: if the idcard is invalid or expired<br /> <br /> Note:<br /> Card secrets will not be rendered.<br /> &quot;&quot;&quot;<br /> &lt;/syntaxhighlight&gt;<br /> <br /> == Internationalisation ==<br /> <br /> * All user-visible strings and labels ''must'' be internationalised: &lt;code&gt;T(&quot;My string&quot;)&lt;/code&gt;<br /> <br /> == Exception Handling ==<br /> <br /> Catching exceptions too broadly can easily hide programming errors, obscure problem causes, and introduce serious risks for data integrity and security. Be as specific as possible as to which (type of) exception is to be caught, and always have a good reason for catching it.<br /> <br /> Do not catch an exception (&quot;Let it crash&quot;) unless:<br /> * there is an immediate remedy or a meaningful alternative action, or<br /> * the exception can be transformed into a meaningful error message that the users can act upon, or<br /> * the exception needs to be logged (in which case it should be re-raised after logging)<br /> <br /> All critical exceptions on the server-side should be logged.<br /> <br /> Database exceptions should never be caught as they may block the current transaction and thus lead to another exception at a later point, obscuring the original cause of the problem.<br /> <br /> = JavaScript =<br /> <br /> == Quotes ==<br /> <br /> * for string literals in '''JavaScript''' use single-quotes &lt;code&gt;' '&lt;/code&gt;, unless the string contains single-quotes<br /> <br /> == Names ==<br /> ''tbw''<br /> <br /> == Docstrings ==<br /> <br /> In JavaScript, we use Java Docstrings. Type specifications for parameters and return values are mandatory.<br /> <br /> &lt;syntaxhighlight lang=&quot;JavaScript&quot;&gt;<br /> /**<br /> * Retrieves events within a certain time interval.<br /> *<br /> * @param {moment|Date|string} start - the start of the interval<br /> * @param {moment|Date|string} end - the end of the interval<br /> *<br /> * @returns {Array} - the events within the interval,<br /> * or null if the interval is not completely cached<br /> */<br /> EventCache.prototype.retrieve = function(start, end) {<br /> ...<br /> };<br /> &lt;/syntaxhighlight&gt;<br /> <br /> = HTML / XML =<br /> <br /> == Quotes ==<br /> <br /> * for attributes in '''HTML''' (such as ''view templates'') use single-quotes &lt;code&gt;attr='value'&lt;/code&gt;<br /> * for attributes in other '''XML''' (e.g. ''XSLT'') use double-quotes &lt;code&gt;&quot; &quot;&lt;/code&gt; (inner quotes must be escaped anyway)</div>

Dominic https://eden.sahanafoundation.org/index.php?title=Guidelines:CodingStyle&diff=312 2026-10-29T12:13:45Z

<p>Dominic: </p> <hr /> <div>* [[Guidelines:Index|All Guidelines]]<br /> <br /> = General =<br /> <br /> The following conventions should be followed in all code.<br /> <br /> This facilitates a team of developers working on the same code base. If each developer were to use their own style, there would be jarring changes in the code as someone read through it. This slows comprehension and can also cause spurious differences in changesets as developers alter style in frivolous ways on the code they touch.<br /> <br /> Our style guide aims to make the code base appear as if it was written by one precise punctilious programmer, rather than a a cacophony of competing coders. As with many aspects of coding and writing, there can be differences of opinion about the best style. These issues distract from the goal of writing code that works. Most project contributors have a slightly different personal coding style, but we all use the Sahana Eden style when contributing to the Sahana Eden project.<br /> <br /> = Python =<br /> <br /> == Quotes ==<br /> <br /> * for string literals in '''Python''' use double-quotes &lt;code&gt;&quot; &quot;&lt;/code&gt;, unless the string contains double-quotes<br /> * for triple-quoted strings (such as ''Docstrings'' or ''Inline-XML'') use &lt;code&gt;&quot;&quot;&quot; &quot;&quot;&quot;&lt;/code&gt; with double-quotes, except:<br /> * for ''Inline-JavaScript'' or ''JSON'' inside '''Python''' code use &lt;code&gt;&lt;nowiki&gt;''' '''&lt;/nowiki&gt;&lt;/code&gt; with single-quotes<br /> <br /> Note though that this:<br /> <br /> &lt;syntaxhighlight lang=&quot;python&quot;&gt;<br /> inline_javascript = '''sometext=&quot;%s&quot;;''' % sometext<br /> &lt;/syntaxhighlight&gt;<br /> <br /> is a '''potential bug and security risk''' - the script breaks when &lt;code&gt;sometext&lt;/code&gt; contains a &lt;code&gt;&quot;&lt;/code&gt;. A safer way to do that is:<br /> <br /> &lt;syntaxhighlight lang=&quot;python&quot;&gt;<br /> inline_javascript = '''sometext=%s;''' % json.dumps(sometext)<br /> &lt;/syntaxhighlight&gt;<br /> <br /> == Names ==<br /> <br /> Names should be obvious and explicit, but not overly verbose (i.e. as long as they need to be to not make people think). They shouldn't require someone to look in another file or solve a puzzle to figure out what they mean, but shouldn't take too long to write. Avoid inventing new acronyms. e.g. <br /> <br /> bad: &lt;code&gt; prm_lkp&lt;/code&gt;, &lt;code&gt;method_that_allows_us_to_create_a_gis_layer&lt;/code&gt;<br /> <br /> good: &lt;code&gt;personnel_search&lt;/code&gt;, &lt;code&gt;create_gis_layer&lt;/code&gt;<br /> <br /> * Class names start with an uppercase letter.<br /> * CamelCase is for class names only.<br /> * Constant names are all-uppercase and with underscores as word separator.<br /> * everything else (including table names and field names) should be all-lowercase with underscores as word separator.<br /> * Names should not be Python keywords or standard library names<br /> * Variable names should not start with _undersore (a trailing underscore_ is acceptable in local scope, though)<br /> * Indexes in names should be avoided (e.g. file1, file2), except where they designate new versions of classes/functions (e.g. AddPersonWidget2)<br /> <br /> * Names for Eden-specific subclasses of web2py classes and all classes which replace existing web2py classes should have the suffix &quot;S3&quot; (e.g. &lt;code&gt;AuthS3&lt;/code&gt;)<br /> * Names for Eden-specific methods (not overrides) in subclasses of web2py classes should start with the prefix &quot;s3_&quot; (e.g. &lt;code&gt;s3_logged_in()&lt;/code&gt;)<br /> * Eden-specific classes ''can'' have an &quot;S3&quot; prefix to their name in order to avoid name collisions, but ideally they ''should not'' (i.e. &lt;code&gt;BasicCRUD&lt;/code&gt; rather than &lt;code&gt;S3BasicCRUD&lt;/code&gt;)<br /> * Method names in Eden-specific classes do not need to (and thus should not) be prefixed<br /> * avoid &quot;s3&quot; or &quot;S3&quot; prefixes in all other cases<br /> <br /> * &lt;code&gt;DataModel&lt;/code&gt; subclasses in &lt;code&gt;s3db&lt;/code&gt; should start with the all-uppercase module prefix, e.g. &lt;code&gt;DVRCaseModel&lt;/code&gt;<br /> * &lt;code&gt;CRUDMethod&lt;/code&gt; subclasses in &lt;code&gt;s3db&lt;/code&gt; must start with the all-lowercase module prefix plus underscore, e.g. &lt;code&gt;pr_Contacts&lt;/code&gt;<br /> <br /> == Docstrings ==<br /> <br /> All classes and functions must have docstrings that explain what the class or function is intended for and how it is to be used. <br /> <br /> Exceptions can be made where the docstring would merely repeat documentation that already exists in another place, e.g. controllers, or standard interface methods inherited from (and thus documented in) a parent class.<br /> <br /> The function description in the docstring should be a statement in the third person about what the function does — not an imperative instruction telling it what to do.<br /> <br /> We follow loosely the ''Google Style Guide'' for docstrings in Python, albeit with additional indentation:<br /> <br /> &lt;syntaxhighlight lang=&quot;python&quot;&gt;<br /> def card_details(r, idcard):<br /> &quot;&quot;&quot;<br /> Displays the details of the new registration card, and offers<br /> a button to download the PDF.<br /> <br /> Args:<br /> (CRUDRequest) r: the request context<br /> (IDCard) idcard: the new registration card<br /> <br /> Returns:<br /> DIV: the card contents<br /> <br /> Raises:<br /> ValueError: if the idcard is invalid<br /> <br /> Note:<br /> Card secrets will not be rendered.<br /> &quot;&quot;&quot;<br /> &lt;/syntaxhighlight&gt;<br /> <br /> Except where they are obvious, '''data types''' of parameters and return value '''should be included''' in the docstring.<br /> <br /> To that end, '''PEP484-style type hints''' can also be acceptable in simple cases - but are '''discouraged''' for more complex parameter lists as they can easily impair comprehensibility, and not every syntax highlighter will aid the visual parsing of function annotations.<br /> <br /> &lt;syntaxhighlight lang=&quot;python&quot;&gt;<br /> def card_details(r: CRUDRequest, idcard: IDCard) -&gt; DIV:<br /> &quot;&quot;&quot;<br /> Displays the details of the new registration card, and offers<br /> a button to download the PDF<br /> <br /> Args:<br /> r: the request context<br /> idcard: the new registration card<br /> <br /> Returns:<br /> the card contents<br /> <br /> Raises:<br /> ValueError: if the idcard is invalid or expired<br /> <br /> Note:<br /> Card secrets will not be rendered.<br /> &quot;&quot;&quot;<br /> &lt;/syntaxhighlight&gt;<br /> <br /> == Internationalisation ==<br /> <br /> * All user-visible strings and labels ''must'' be internationalised: &lt;code&gt;T(&quot;My string&quot;)&lt;/code&gt;<br /> <br /> == Exception Handling ==<br /> <br /> Catching exceptions too broadly can easily hide programming errors, obscure problem causes, and introduce serious risks for data integrity and security. Be as specific as possible as to which (type of) exception is to be caught, and always have a good reason for catching it.<br /> <br /> Do not catch an exception (&quot;Let it crash&quot;) unless:<br /> * there is an immediate remedy or a meaningful alternative action, or<br /> * the exception can be transformed into a meaningful error message that the users can act upon, or<br /> * the exception needs to be logged (in which case it should be re-raised after logging)<br /> <br /> All critical exceptions on the server-side should be logged.<br /> <br /> Database exceptions should never be caught as they may block the current transaction and thus lead to another exception at a later point, obscuring the original cause of the problem.<br /> <br /> = JavaScript =<br /> <br /> == Quotes ==<br /> <br /> * for string literals in '''JavaScript''' use single-quotes &lt;code&gt;' '&lt;/code&gt;, unless the string contains single-quotes<br /> <br /> == Names ==<br /> ''tbw''<br /> <br /> === JavaScript ===<br /> <br /> In JavaScript, we use Java Docstrings. Type specifications for parameters and return values are mandatory.<br /> <br /> &lt;syntaxhighlight lang=&quot;JavaScript&quot;&gt;<br /> /**<br /> * Retrieves events within a certain time interval.<br /> *<br /> * @param {moment|Date|string} start - the start of the interval<br /> * @param {moment|Date|string} end - the end of the interval<br /> *<br /> * @returns {Array} - the events within the interval,<br /> * or null if the interval is not completely cached<br /> */<br /> EventCache.prototype.retrieve = function(start, end) {<br /> ...<br /> };<br /> &lt;/syntaxhighlight&gt;<br /> <br /> = HTML / XML =<br /> <br /> == Quotes ==<br /> <br /> * for attributes in '''HTML''' (such as ''view templates'') use single-quotes &lt;code&gt;attr='value'&lt;/code&gt;<br /> * for attributes in other '''XML''' (e.g. ''XSLT'') use double-quotes &lt;code&gt;&quot; &quot;&lt;/code&gt; (inner quotes must be escaped anyway)</div>

Dominic https://eden.sahanafoundation.org/index.php?title=Guidelines:CodingStyle&diff=311 2026-10-28T23:08:20Z

<p>Dominic: /* Quotes */</p> <hr /> <div>* [[Guidelines:Index|All Guidelines]]<br /> <br /> = Coding Style Guide =<br /> <br /> These conventions should be followed in all code.<br /> <br /> This facilitates a team of developers working on the same code base. If each developer were to use their own style, there would be jarring changes in the code as someone read through it. This slows comprehension and can also cause spurious differences in changesets as developers alter style in frivolous ways on the code they touch.<br /> <br /> Our style guide aims to make the code base appear as if it was written by one precise punctilious programmer, rather than a a cacophony of competing coders. As with many aspects of coding and writing, there can be differences of opinion about the best style. These issues distract from the goal of writing code that works. Most project contributors have a slightly different personal coding style, but we all use the Sahana Eden style when contributing to the Sahana Eden project.<br /> <br /> == Quotes ==<br /> <br /> * for string literals in '''Python''' use double-quotes &lt;code&gt;&quot; &quot;&lt;/code&gt;, unless the string contains double-quotes<br /> * for triple-quoted strings (such as ''Docstrings'' or ''Inline-XML'') use &lt;code&gt;&quot;&quot;&quot; &quot;&quot;&quot;&lt;/code&gt; with double-quotes, except:<br /> * for ''Inline-JavaScript'' or ''JSON'' inside '''Python''' code use &lt;code&gt;&lt;nowiki&gt;''' '''&lt;/nowiki&gt;&lt;/code&gt; with single-quotes<br /> <br /> <br /> Note though that this:<br /> <br /> &lt;syntaxhighlight lang=&quot;python&quot;&gt;<br /> inline_javascript = '''sometext=&quot;%s&quot;;''' % sometext<br /> &lt;/syntaxhighlight&gt;<br /> <br /> is a '''potential bug and security risk''' - the script breaks when &lt;code&gt;sometext&lt;/code&gt; contains a &lt;code&gt;&quot;&lt;/code&gt;. A safer way to do that is:<br /> <br /> &lt;syntaxhighlight lang=&quot;python&quot;&gt;<br /> inline_javascript = '''sometext=%s;''' % json.dumps(sometext)<br /> &lt;/syntaxhighlight&gt;<br /> <br /> <br /> * for string literals in '''JavaScript''' use single-quotes &lt;code&gt;' '&lt;/code&gt;, unless the string contains single-quotes<br /> <br /> <br /> * for attributes in '''HTML''' (such as ''view templates'') use single-quotes &lt;code&gt;attr='value'&lt;/code&gt;<br /> * for attributes in other '''XML''' (e.g. ''XSLT'') use double-quotes &lt;code&gt;&quot; &quot;&lt;/code&gt; (inner quotes must be escaped anyway)<br /> <br /> == Names ==<br /> <br /> === General ===<br /> <br /> * Names should be obvious and explicit, but not overly verbose (i.e. as long as they need to be to not make people think). They shouldn't require someone to look in another file or solve a puzzle to figure out what they mean, but shouldn't take too long to write. Avoid inventing new acronyms. e.g. <br /> bad: &lt;code&gt; prm_lkp&lt;/code&gt;, &lt;code&gt;method_that_allows_us_to_create_a_gis_layer&lt;/code&gt;<br /> good: &lt;code&gt;personnel_search&lt;/code&gt;, &lt;code&gt;create_gis_layer&lt;/code&gt;<br /> <br /> === Python ===<br /> <br /> * Class names start with an uppercase letter.<br /> * CamelCase is for class names only.<br /> * Constant names are all-uppercase and with underscores as word separator.<br /> * everything else (including table names and field names) should be all-lowercase with underscores as word separator.<br /> * Names should not be Python keywords or standard library names<br /> * Variable names should not start with _undersore (a trailing underscore_ is acceptable in local scope, though)<br /> * Indexes in names should be avoided (e.g. file1, file2), except where they designate new versions of classes/functions (e.g. AddPersonWidget2)<br /> <br /> <br /> * Names for Eden-specific subclasses of web2py classes and all classes which replace existing web2py classes should have the suffix &quot;S3&quot; (e.g. &lt;code&gt;AuthS3&lt;/code&gt;)<br /> * Names for Eden-specific methods (not overrides) in subclasses of web2py classes should start with the prefix &quot;s3_&quot; (e.g. &lt;code&gt;s3_logged_in()&lt;/code&gt;)<br /> * Eden-specific classes ''can'' have an &quot;S3&quot; prefix to their name in order to avoid name collisions, but ideally they ''should not'' (i.e. &lt;code&gt;BasicCRUD&lt;/code&gt; rather than &lt;code&gt;S3BasicCRUD&lt;/code&gt;)<br /> * Method names in Eden-specific classes do not need to (and thus should not) be prefixed<br /> * avoid &quot;s3&quot; or &quot;S3&quot; prefixes in all other cases<br /> <br /> <br /> * &lt;code&gt;DataModel&lt;/code&gt; subclasses in &lt;code&gt;s3db&lt;/code&gt; should start with the all-uppercase module prefix, e.g. &lt;code&gt;DVRCaseModel&lt;/code&gt;<br /> * &lt;code&gt;CRUDMethod&lt;/code&gt; subclasses in &lt;code&gt;s3db&lt;/code&gt; must start with the all-lowercase module prefix plus underscore, e.g. &lt;code&gt;pr_Contacts&lt;/code&gt;<br /> <br /> == Docstrings ==<br /> <br /> All classes and functions must have docstrings that explain what the class or function is intended for and how it is to be used. <br /> <br /> Exceptions can be made where the docstring would merely repeat documentation that already exists in another place, e.g. controllers, or standard interface methods inherited from (and thus documented in) a parent class.<br /> <br /> The function description in the docstring should be a statement in the third person about what the function does — not an imperative instruction telling it what to do.<br /> <br /> === Python ===<br /> <br /> We follow loosely the ''Google Style Guide'' for docstrings in Python, albeit with additional indentation:<br /> <br /> &lt;syntaxhighlight lang=&quot;python&quot;&gt;<br /> def card_details(r, idcard):<br /> &quot;&quot;&quot;<br /> Displays the details of the new registration card, and offers<br /> a button to download the PDF.<br /> <br /> Args:<br /> (CRUDRequest) r: the request context<br /> (IDCard) idcard: the new registration card<br /> <br /> Returns:<br /> DIV: the card contents<br /> <br /> Raises:<br /> ValueError: if the idcard is invalid<br /> <br /> Note:<br /> Card secrets will not be rendered.<br /> &quot;&quot;&quot;<br /> &lt;/syntaxhighlight&gt;<br /> <br /> Except where they are obvious, '''data types''' of parameters and return value '''should be included''' in the docstring.<br /> <br /> To that end, '''PEP484-style type hints''' can also be acceptable in simple cases - but are '''discouraged''' for more complex parameter lists as they can easily impair comprehensibility, and not every syntax highlighter will aid the visual parsing of function annotations.<br /> <br /> &lt;syntaxhighlight lang=&quot;python&quot;&gt;<br /> def card_details(r: CRUDRequest, idcard: IDCard) -&gt; DIV:<br /> &quot;&quot;&quot;<br /> Displays the details of the new registration card, and offers<br /> a button to download the PDF<br /> <br /> Args:<br /> r: the request context<br /> idcard: the new registration card<br /> <br /> Returns:<br /> the card contents<br /> <br /> Raises:<br /> ValueError: if the idcard is invalid or expired<br /> <br /> Note:<br /> Card secrets will not be rendered.<br /> &quot;&quot;&quot;<br /> &lt;/syntaxhighlight&gt;<br /> <br /> === JavaScript ===<br /> <br /> In JavaScript, we use Java Docstrings.<br /> <br /> &lt;syntaxhighlight lang=&quot;JavaScript&quot;&gt;<br /> /**<br /> * Retrieves events within a certain time interval.<br /> *<br /> * @param {moment|Date|string} start - the start of the interval<br /> * @param {moment|Date|string} end - the end of the interval<br /> *<br /> * @returns {Array} - the events within the interval,<br /> * or null if the interval is not completely cached<br /> */<br /> EventCache.prototype.retrieve = function(start, end) {<br /> ...<br /> };<br /> &lt;/syntaxhighlight&gt;<br /> <br /> Type specifications for parameters and return values are mandatory here.<br /> <br /> == Internationalisation ==<br /> <br /> * All user-visible strings and labels ''must'' be internationalised: &lt;code&gt;T(&quot;My string&quot;)&lt;/code&gt;<br /> <br /> == Exception Handling ==<br /> <br /> Catching exceptions too broadly can easily hide programming errors, obscure problem causes, and introduce serious risks for data integrity and security. Be as specific as possible as to which (type of) exception is to be caught, and always have a good reason for catching it.<br /> <br /> Do not catch an exception (&quot;Let it crash&quot;) unless:<br /> * there is an immediate remedy or a meaningful alternative action, or<br /> * the exception can be transformed into a meaningful error message that the users can act upon, or<br /> * the exception needs to be logged (in which case it should be re-raised after logging)<br /> <br /> All critical exceptions on the server-side should be logged.<br /> <br /> Database exceptions should never be caught as they may block the current transaction and thus lead to another exception at a later point, obscuring the original cause of the problem.</div>

Dominic https://eden.sahanafoundation.org/index.php?title=Guidelines:CodingStyle&diff=310 2026-10-28T23:02:36Z

<p>Dominic: </p> <hr /> <div>* [[Guidelines:Index|All Guidelines]]<br /> <br /> = Coding Style Guide =<br /> <br /> These conventions should be followed in all code.<br /> <br /> This facilitates a team of developers working on the same code base. If each developer were to use their own style, there would be jarring changes in the code as someone read through it. This slows comprehension and can also cause spurious differences in changesets as developers alter style in frivolous ways on the code they touch.<br /> <br /> Our style guide aims to make the code base appear as if it was written by one precise punctilious programmer, rather than a a cacophony of competing coders. As with many aspects of coding and writing, there can be differences of opinion about the best style. These issues distract from the goal of writing code that works. Most project contributors have a slightly different personal coding style, but we all use the Sahana Eden style when contributing to the Sahana Eden project.<br /> <br /> == Quotes ==<br /> <br /> * for string literals in '''Python''' use double-quotes &lt;code&gt;&quot; &quot;&lt;/code&gt;, unless the string contains double-quotes<br /> * for triple-quoted strings (such as ''Docstrings'' or ''Inline-XML'') use &lt;code&gt;&quot;&quot;&quot; &quot;&quot;&quot;&lt;/code&gt; with double-quotes, except:<br /> * for ''Inline-JavaScript'' or ''JSON'' inside '''Python''' code use &lt;code&gt;&lt;nowiki&gt;''' '''&lt;/nowiki&gt;&lt;/code&gt; with single-quotes<br /> <br /> <br /> Note though that this:<br /> <br /> &lt;code&gt;&lt;nowiki&gt;<br /> inline_javascript = '''sometext=&quot;%s&quot;;''' % sometext<br /> &lt;/nowiki&gt;&lt;/code&gt;<br /> <br /> is a '''potential bug''' - the script breaks when &lt;code&gt;sometext&lt;/code&gt; contains a &lt;code&gt;&quot;&lt;/code&gt;. A safer way to do that is:<br /> <br /> &lt;code&gt;&lt;nowiki&gt;<br /> inline_javascript = '''sometext=%s;''' % json.dumps(sometext)<br /> &lt;/nowiki&gt;&lt;/code&gt;<br /> <br /> <br /> * for string literals in '''JavaScript''' use single-quotes &lt;code&gt;' '&lt;/code&gt;, unless the string contains single-quotes<br /> <br /> <br /> * for attributes in '''HTML''' (such as ''view templates'') use single-quotes &lt;code&gt;attr='value'&lt;/code&gt;<br /> * for attributes in other '''XML''' (e.g. ''XSLT'') use double-quotes &lt;code&gt;&quot; &quot;&lt;/code&gt; (inner quotes must be escaped anyway)<br /> <br /> == Names ==<br /> <br /> === General ===<br /> <br /> * Names should be obvious and explicit, but not overly verbose (i.e. as long as they need to be to not make people think). They shouldn't require someone to look in another file or solve a puzzle to figure out what they mean, but shouldn't take too long to write. Avoid inventing new acronyms. e.g. <br /> bad: &lt;code&gt; prm_lkp&lt;/code&gt;, &lt;code&gt;method_that_allows_us_to_create_a_gis_layer&lt;/code&gt;<br /> good: &lt;code&gt;personnel_search&lt;/code&gt;, &lt;code&gt;create_gis_layer&lt;/code&gt;<br /> <br /> === Python ===<br /> <br /> * Class names start with an uppercase letter.<br /> * CamelCase is for class names only.<br /> * Constant names are all-uppercase and with underscores as word separator.<br /> * everything else (including table names and field names) should be all-lowercase with underscores as word separator.<br /> * Names should not be Python keywords or standard library names<br /> * Variable names should not start with _undersore (a trailing underscore_ is acceptable in local scope, though)<br /> * Indexes in names should be avoided (e.g. file1, file2), except where they designate new versions of classes/functions (e.g. AddPersonWidget2)<br /> <br /> <br /> * Names for Eden-specific subclasses of web2py classes and all classes which replace existing web2py classes should have the suffix &quot;S3&quot; (e.g. &lt;code&gt;AuthS3&lt;/code&gt;)<br /> * Names for Eden-specific methods (not overrides) in subclasses of web2py classes should start with the prefix &quot;s3_&quot; (e.g. &lt;code&gt;s3_logged_in()&lt;/code&gt;)<br /> * Eden-specific classes ''can'' have an &quot;S3&quot; prefix to their name in order to avoid name collisions, but ideally they ''should not'' (i.e. &lt;code&gt;BasicCRUD&lt;/code&gt; rather than &lt;code&gt;S3BasicCRUD&lt;/code&gt;)<br /> * Method names in Eden-specific classes do not need to (and thus should not) be prefixed<br /> * avoid &quot;s3&quot; or &quot;S3&quot; prefixes in all other cases<br /> <br /> <br /> * &lt;code&gt;DataModel&lt;/code&gt; subclasses in &lt;code&gt;s3db&lt;/code&gt; should start with the all-uppercase module prefix, e.g. &lt;code&gt;DVRCaseModel&lt;/code&gt;<br /> * &lt;code&gt;CRUDMethod&lt;/code&gt; subclasses in &lt;code&gt;s3db&lt;/code&gt; must start with the all-lowercase module prefix plus underscore, e.g. &lt;code&gt;pr_Contacts&lt;/code&gt;<br /> <br /> == Docstrings ==<br /> <br /> All classes and functions must have docstrings that explain what the class or function is intended for and how it is to be used. <br /> <br /> Exceptions can be made where the docstring would merely repeat documentation that already exists in another place, e.g. controllers, or standard interface methods inherited from (and thus documented in) a parent class.<br /> <br /> The function description in the docstring should be a statement in the third person about what the function does — not an imperative instruction telling it what to do.<br /> <br /> === Python ===<br /> <br /> We follow loosely the ''Google Style Guide'' for docstrings in Python, albeit with additional indentation:<br /> <br /> &lt;syntaxhighlight lang=&quot;python&quot;&gt;<br /> def card_details(r, idcard):<br /> &quot;&quot;&quot;<br /> Displays the details of the new registration card, and offers<br /> a button to download the PDF.<br /> <br /> Args:<br /> (CRUDRequest) r: the request context<br /> (IDCard) idcard: the new registration card<br /> <br /> Returns:<br /> DIV: the card contents<br /> <br /> Raises:<br /> ValueError: if the idcard is invalid<br /> <br /> Note:<br /> Card secrets will not be rendered.<br /> &quot;&quot;&quot;<br /> &lt;/syntaxhighlight&gt;<br /> <br /> Except where they are obvious, '''data types''' of parameters and return value '''should be included''' in the docstring.<br /> <br /> To that end, '''PEP484-style type hints''' can also be acceptable in simple cases - but are '''discouraged''' for more complex parameter lists as they can easily impair comprehensibility, and not every syntax highlighter will aid the visual parsing of function annotations.<br /> <br /> &lt;syntaxhighlight lang=&quot;python&quot;&gt;<br /> def card_details(r: CRUDRequest, idcard: IDCard) -&gt; DIV:<br /> &quot;&quot;&quot;<br /> Displays the details of the new registration card, and offers<br /> a button to download the PDF<br /> <br /> Args:<br /> r: the request context<br /> idcard: the new registration card<br /> <br /> Returns:<br /> the card contents<br /> <br /> Raises:<br /> ValueError: if the idcard is invalid or expired<br /> <br /> Note:<br /> Card secrets will not be rendered.<br /> &quot;&quot;&quot;<br /> &lt;/syntaxhighlight&gt;<br /> <br /> === JavaScript ===<br /> <br /> In JavaScript, we use Java Docstrings.<br /> <br /> &lt;syntaxhighlight lang=&quot;JavaScript&quot;&gt;<br /> /**<br /> * Retrieves events within a certain time interval.<br /> *<br /> * @param {moment|Date|string} start - the start of the interval<br /> * @param {moment|Date|string} end - the end of the interval<br /> *<br /> * @returns {Array} - the events within the interval,<br /> * or null if the interval is not completely cached<br /> */<br /> EventCache.prototype.retrieve = function(start, end) {<br /> ...<br /> };<br /> &lt;/syntaxhighlight&gt;<br /> <br /> Type specifications for parameters and return values are mandatory here.<br /> <br /> == Internationalisation ==<br /> <br /> * All user-visible strings and labels ''must'' be internationalised: &lt;code&gt;T(&quot;My string&quot;)&lt;/code&gt;<br /> <br /> == Exception Handling ==<br /> <br /> Catching exceptions too broadly can easily hide programming errors, obscure problem causes, and introduce serious risks for data integrity and security. Be as specific as possible as to which (type of) exception is to be caught, and always have a good reason for catching it.<br /> <br /> Do not catch an exception (&quot;Let it crash&quot;) unless:<br /> * there is an immediate remedy or a meaningful alternative action, or<br /> * the exception can be transformed into a meaningful error message that the users can act upon, or<br /> * the exception needs to be logged (in which case it should be re-raised after logging)<br /> <br /> All critical exceptions on the server-side should be logged.<br /> <br /> Database exceptions should never be caught as they may block the current transaction and thus lead to another exception at a later point, obscuring the original cause of the problem.</div>

Dominic https://eden.sahanafoundation.org/index.php?title=Guidelines:CodingStyle&diff=309 2026-10-28T22:56:16Z

<p>Dominic: /* Exceptions */</p> <hr /> <div>* [[Guidelines:Index|All Guidelines]]<br /> <br /> = Coding Style Guide =<br /> <br /> These conventions should be followed in all code.<br /> <br /> This facilitates a team of developers working on the same code base. If each developer were to use their own style, there would be jarring changes in the code as someone read through it. This slows comprehension and can also cause spurious differences in changesets as developers alter style in frivolous ways on the code they touch.<br /> <br /> Our style guide aims to make the code base appear as if it was written by one precise punctilious programmer, rather than a a cacophony of competing coders. As with many aspects of coding and writing, there can be differences of opinion about the best style. These issues distract from the goal of writing code that works. Most project contributors have a slightly different personal coding style, but we all use the Sahana Eden style when contributing to the Sahana Eden project.<br /> <br /> == Quotes ==<br /> <br /> * for string literals in '''Python''' use double-quotes &lt;code&gt;&quot; &quot;&lt;/code&gt;, unless the string contains double-quotes<br /> * for triple-quoted strings (such as ''Docstrings'' or ''Inline-XML'') use &lt;code&gt;&quot;&quot;&quot; &quot;&quot;&quot;&lt;/code&gt; with double-quotes, except:<br /> * for ''Inline-JavaScript'' or ''JSON'' inside '''Python''' code use &lt;code&gt;&lt;nowiki&gt;''' '''&lt;/nowiki&gt;&lt;/code&gt; with single-quotes<br /> <br /> <br /> Note though that this:<br /> <br /> &lt;code&gt;&lt;nowiki&gt;<br /> inline_javascript = '''sometext=&quot;%s&quot;;''' % sometext<br /> &lt;/nowiki&gt;&lt;/code&gt;<br /> <br /> is a '''potential bug''' - the script breaks when &lt;code&gt;sometext&lt;/code&gt; contains a &lt;code&gt;&quot;&lt;/code&gt;. A safer way to do that is:<br /> <br /> &lt;code&gt;&lt;nowiki&gt;<br /> inline_javascript = '''sometext=%s;''' % json.dumps(sometext)<br /> &lt;/nowiki&gt;&lt;/code&gt;<br /> <br /> <br /> * for string literals in '''JavaScript''' use single-quotes &lt;code&gt;' '&lt;/code&gt;, unless the string contains single-quotes<br /> <br /> <br /> * for attributes in '''HTML''' (such as ''view templates'') use single-quotes &lt;code&gt;attr='value'&lt;/code&gt;<br /> * for attributes in other '''XML''' (e.g. ''XSLT'') use double-quotes &lt;code&gt;&quot; &quot;&lt;/code&gt; (inner quotes must be escaped anyway)<br /> <br /> == Names ==<br /> <br /> === General ===<br /> <br /> * Names should be obvious and explicit, but not overly verbose (i.e. as long as they need to be to not make people think). They shouldn't require someone to look in another file or solve a puzzle to figure out what they mean, but shouldn't take too long to write. Avoid inventing new acronyms. e.g. <br /> bad: &lt;code&gt; prm_lkp&lt;/code&gt;, &lt;code&gt;method_that_allows_us_to_create_a_gis_layer&lt;/code&gt;<br /> good: &lt;code&gt;personnel_search&lt;/code&gt;, &lt;code&gt;create_gis_layer&lt;/code&gt;<br /> <br /> === Python ===<br /> <br /> * Class names start with an uppercase letter.<br /> * CamelCase is for class names only.<br /> * Constant names are all-uppercase and with underscores as word separator.<br /> * everything else (including table names and field names) should be all-lowercase with underscores as word separator.<br /> * Names should not be Python keywords or standard library names<br /> * Variable names should not start with _undersore (a trailing underscore_ is acceptable in local scope, though)<br /> * Indexes in names should be avoided (e.g. file1, file2), except where they designate new versions of classes/functions (e.g. AddPersonWidget2)<br /> <br /> <br /> * Names for Eden-specific subclasses of web2py classes and all classes which replace existing web2py classes should have the suffix &quot;S3&quot; (e.g. &lt;code&gt;AuthS3&lt;/code&gt;)<br /> * Names for Eden-specific methods (not overrides) in subclasses of web2py classes should start with the prefix &quot;s3_&quot; (e.g. &lt;code&gt;s3_logged_in()&lt;/code&gt;)<br /> * Eden-specific classes ''can'' have an &quot;S3&quot; prefix to their name in order to avoid name collisions, but ideally they ''should not'' (i.e. &lt;code&gt;BasicCRUD&lt;/code&gt; rather than &lt;code&gt;S3BasicCRUD&lt;/code&gt;)<br /> * Method names in Eden-specific classes do not need to (and thus should not) be prefixed<br /> * avoid &quot;s3&quot; or &quot;S3&quot; prefixes in all other cases<br /> <br /> <br /> * &lt;code&gt;DataModel&lt;/code&gt; subclasses in &lt;code&gt;s3db&lt;/code&gt; should start with the all-uppercase module prefix, e.g. &lt;code&gt;DVRCaseModel&lt;/code&gt;<br /> * &lt;code&gt;CRUDMethod&lt;/code&gt; subclasses in &lt;code&gt;s3db&lt;/code&gt; must start with the all-lowercase module prefix plus underscore, e.g. &lt;code&gt;pr_Contacts&lt;/code&gt;<br /> <br /> == Docstrings ==<br /> <br /> All classes and functions must have docstrings that explain what the class or function is intended for and how it is to be used. <br /> <br /> Exceptions can be made where the docstring would merely repeat documentation that already exists in another place, e.g. controllers, or standard interface methods inherited from (and thus documented in) a parent class.<br /> <br /> The function description in the docstring should be a statement in the third person about what the function does — not an imperative instruction telling it what to do.<br /> <br /> === Python ===<br /> <br /> We follow loosely the ''Google Style Guide'' for docstrings in Python, albeit with additional indentation:<br /> <br /> &lt;syntaxhighlight lang=&quot;python&quot;&gt;<br /> def card_details(r, idcard):<br /> &quot;&quot;&quot;<br /> Displays the details of the new registration card, and offers<br /> a button to download the PDF.<br /> <br /> Args:<br /> (CRUDRequest) r: the request context<br /> (IDCard) idcard: the new registration card<br /> <br /> Returns:<br /> DIV: the card contents<br /> <br /> Raises:<br /> ValueError: if the idcard is invalid<br /> <br /> Note:<br /> Card secrets will not be rendered.<br /> &quot;&quot;&quot;<br /> &lt;/syntaxhighlight&gt;<br /> <br /> Except where they are obvious, '''data types''' of parameters and return value '''should be included''' in the docstring.<br /> <br /> To that end, '''PEP484-style type hints''' can also be acceptable in simple cases - but are '''discouraged''' for more complex parameter lists as they can easily impair comprehensibility, and not every syntax highlighter will aid the visual parsing of function annotations.<br /> <br /> &lt;syntaxhighlight lang=&quot;python&quot;&gt;<br /> def card_details(r: CRUDRequest, idcard: IDCard) -&gt; DIV:<br /> &quot;&quot;&quot;<br /> Displays the details of the new registration card, and offers<br /> a button to download the PDF<br /> <br /> Args:<br /> r: the request context<br /> idcard: the new registration card<br /> <br /> Returns:<br /> the card contents<br /> <br /> Raises:<br /> ValueError: if the idcard is invalid or expired<br /> <br /> Note:<br /> Card secrets will not be rendered.<br /> &quot;&quot;&quot;<br /> &lt;/syntaxhighlight&gt;<br /> <br /> === JavaScript ===<br /> <br /> In JavaScript, we use Java Docstrings.<br /> <br /> &lt;syntaxhighlight lang=&quot;JavaScript&quot;&gt;<br /> /**<br /> * Retrieves events within a certain time interval.<br /> *<br /> * @param {moment|Date|string} start - the start of the interval<br /> * @param {moment|Date|string} end - the end of the interval<br /> *<br /> * @returns {Array} - the events within the interval,<br /> * or null if the interval is not completely cached<br /> */<br /> EventCache.prototype.retrieve = function(start, end) {<br /> ...<br /> };<br /> &lt;/syntaxhighlight&gt;<br /> <br /> Type specifications for parameters and return values are mandatory here.<br /> <br /> === Internationalisation ===<br /> <br /> * All user-visible strings and labels ''must'' be internationalised: &lt;code&gt;T(&quot;My string&quot;)&lt;/code&gt;<br /> <br /> === Exception Handling ===<br /> <br /> Catching exceptions too broadly can easily hide programming errors, obscure problem causes, and introduce serious risks for data integrity and security. Be as specific as possible as to which (type of) exception is to be caught, and always have a good reason for catching it.<br /> <br /> Do not catch an exception (&quot;Let it crash&quot;) unless:<br /> * there is an immediate remedy or a meaningful alternative action, or<br /> * the exception can be transformed into a meaningful error message that the users can act upon, or<br /> * the exception needs to be logged (in which case it should be re-raised after logging)<br /> <br /> All critical exceptions on the server-side should be logged.<br /> <br /> Database exceptions should never be caught as they may block the current transaction and thus lead to another exception at a later point, obscuring the original cause of the problem.</div>

Dominic https://eden.sahanafoundation.org/index.php?title=Guidelines:CodingStyle&diff=308 2026-10-28T22:12:47Z

<p>Dominic: </p> <hr /> <div>* [[Guidelines:Index|All Guidelines]]<br /> <br /> = Coding Style Guide =<br /> <br /> These conventions should be followed in all code.<br /> <br /> This facilitates a team of developers working on the same code base. If each developer were to use their own style, there would be jarring changes in the code as someone read through it. This slows comprehension and can also cause spurious differences in changesets as developers alter style in frivolous ways on the code they touch.<br /> <br /> Our style guide aims to make the code base appear as if it was written by one precise punctilious programmer, rather than a a cacophony of competing coders. As with many aspects of coding and writing, there can be differences of opinion about the best style. These issues distract from the goal of writing code that works. Most project contributors have a slightly different personal coding style, but we all use the Sahana Eden style when contributing to the Sahana Eden project.<br /> <br /> == Quotes ==<br /> <br /> * for string literals in '''Python''' use double-quotes &lt;code&gt;&quot; &quot;&lt;/code&gt;, unless the string contains double-quotes<br /> * for triple-quoted strings (such as ''Docstrings'' or ''Inline-XML'') use &lt;code&gt;&quot;&quot;&quot; &quot;&quot;&quot;&lt;/code&gt; with double-quotes, except:<br /> * for ''Inline-JavaScript'' or ''JSON'' inside '''Python''' code use &lt;code&gt;&lt;nowiki&gt;''' '''&lt;/nowiki&gt;&lt;/code&gt; with single-quotes<br /> <br /> <br /> Note though that this:<br /> <br /> &lt;code&gt;&lt;nowiki&gt;<br /> inline_javascript = '''sometext=&quot;%s&quot;;''' % sometext<br /> &lt;/nowiki&gt;&lt;/code&gt;<br /> <br /> is a '''potential bug''' - the script breaks when &lt;code&gt;sometext&lt;/code&gt; contains a &lt;code&gt;&quot;&lt;/code&gt;. A safer way to do that is:<br /> <br /> &lt;code&gt;&lt;nowiki&gt;<br /> inline_javascript = '''sometext=%s;''' % json.dumps(sometext)<br /> &lt;/nowiki&gt;&lt;/code&gt;<br /> <br /> <br /> * for string literals in '''JavaScript''' use single-quotes &lt;code&gt;' '&lt;/code&gt;, unless the string contains single-quotes<br /> <br /> <br /> * for attributes in '''HTML''' (such as ''view templates'') use single-quotes &lt;code&gt;attr='value'&lt;/code&gt;<br /> * for attributes in other '''XML''' (e.g. ''XSLT'') use double-quotes &lt;code&gt;&quot; &quot;&lt;/code&gt; (inner quotes must be escaped anyway)<br /> <br /> == Names ==<br /> <br /> === General ===<br /> <br /> * Names should be obvious and explicit, but not overly verbose (i.e. as long as they need to be to not make people think). They shouldn't require someone to look in another file or solve a puzzle to figure out what they mean, but shouldn't take too long to write. Avoid inventing new acronyms. e.g. <br /> bad: &lt;code&gt; prm_lkp&lt;/code&gt;, &lt;code&gt;method_that_allows_us_to_create_a_gis_layer&lt;/code&gt;<br /> good: &lt;code&gt;personnel_search&lt;/code&gt;, &lt;code&gt;create_gis_layer&lt;/code&gt;<br /> <br /> === Python ===<br /> <br /> * Class names start with an uppercase letter.<br /> * CamelCase is for class names only.<br /> * Constant names are all-uppercase and with underscores as word separator.<br /> * everything else (including table names and field names) should be all-lowercase with underscores as word separator.<br /> * Names should not be Python keywords or standard library names<br /> * Variable names should not start with _undersore (a trailing underscore_ is acceptable in local scope, though)<br /> * Indexes in names should be avoided (e.g. file1, file2), except where they designate new versions of classes/functions (e.g. AddPersonWidget2)<br /> <br /> <br /> * Names for Eden-specific subclasses of web2py classes and all classes which replace existing web2py classes should have the suffix &quot;S3&quot; (e.g. &lt;code&gt;AuthS3&lt;/code&gt;)<br /> * Names for Eden-specific methods (not overrides) in subclasses of web2py classes should start with the prefix &quot;s3_&quot; (e.g. &lt;code&gt;s3_logged_in()&lt;/code&gt;)<br /> * Eden-specific classes ''can'' have an &quot;S3&quot; prefix to their name in order to avoid name collisions, but ideally they ''should not'' (i.e. &lt;code&gt;BasicCRUD&lt;/code&gt; rather than &lt;code&gt;S3BasicCRUD&lt;/code&gt;)<br /> * Method names in Eden-specific classes do not need to (and thus should not) be prefixed<br /> * avoid &quot;s3&quot; or &quot;S3&quot; prefixes in all other cases<br /> <br /> <br /> * &lt;code&gt;DataModel&lt;/code&gt; subclasses in &lt;code&gt;s3db&lt;/code&gt; should start with the all-uppercase module prefix, e.g. &lt;code&gt;DVRCaseModel&lt;/code&gt;<br /> * &lt;code&gt;CRUDMethod&lt;/code&gt; subclasses in &lt;code&gt;s3db&lt;/code&gt; must start with the all-lowercase module prefix plus underscore, e.g. &lt;code&gt;pr_Contacts&lt;/code&gt;<br /> <br /> == Docstrings ==<br /> <br /> All classes and functions must have docstrings that explain what the class or function is intended for and how it is to be used. <br /> <br /> Exceptions can be made where the docstring would merely repeat documentation that already exists in another place, e.g. controllers, or standard interface methods inherited from (and thus documented in) a parent class.<br /> <br /> The function description in the docstring should be a statement in the third person about what the function does — not an imperative instruction telling it what to do.<br /> <br /> === Python ===<br /> <br /> We follow loosely the ''Google Style Guide'' for docstrings in Python, albeit with additional indentation:<br /> <br /> &lt;syntaxhighlight lang=&quot;python&quot;&gt;<br /> def card_details(r, idcard):<br /> &quot;&quot;&quot;<br /> Displays the details of the new registration card, and offers<br /> a button to download the PDF.<br /> <br /> Args:<br /> (CRUDRequest) r: the request context<br /> (IDCard) idcard: the new registration card<br /> <br /> Returns:<br /> DIV: the card contents<br /> <br /> Raises:<br /> ValueError: if the idcard is invalid<br /> <br /> Note:<br /> Card secrets will not be rendered.<br /> &quot;&quot;&quot;<br /> &lt;/syntaxhighlight&gt;<br /> <br /> Except where they are obvious, '''data types''' of parameters and return value '''should be included''' in the docstring.<br /> <br /> To that end, '''PEP484-style type hints''' can also be acceptable in simple cases - but are '''discouraged''' for more complex parameter lists as they can easily impair comprehensibility, and not every syntax highlighter will aid the visual parsing of function annotations.<br /> <br /> &lt;syntaxhighlight lang=&quot;python&quot;&gt;<br /> def card_details(r: CRUDRequest, idcard: IDCard) -&gt; DIV:<br /> &quot;&quot;&quot;<br /> Displays the details of the new registration card, and offers<br /> a button to download the PDF<br /> <br /> Args:<br /> r: the request context<br /> idcard: the new registration card<br /> <br /> Returns:<br /> the card contents<br /> <br /> Raises:<br /> ValueError: if the idcard is invalid or expired<br /> <br /> Note:<br /> Card secrets will not be rendered.<br /> &quot;&quot;&quot;<br /> &lt;/syntaxhighlight&gt;<br /> <br /> === JavaScript ===<br /> <br /> In JavaScript, we use Java Docstrings.<br /> <br /> &lt;syntaxhighlight lang=&quot;JavaScript&quot;&gt;<br /> /**<br /> * Retrieves events within a certain time interval.<br /> *<br /> * @param {moment|Date|string} start - the start of the interval<br /> * @param {moment|Date|string} end - the end of the interval<br /> *<br /> * @returns {Array} - the events within the interval,<br /> * or null if the interval is not completely cached<br /> */<br /> EventCache.prototype.retrieve = function(start, end) {<br /> ...<br /> };<br /> &lt;/syntaxhighlight&gt;<br /> <br /> Type specifications for parameters and return values are mandatory here.<br /> <br /> === Internationalisation ===<br /> <br /> * All user-visible strings and labels ''must'' be internationalised: &lt;code&gt;T(&quot;My string&quot;)&lt;/code&gt;<br /> <br /> === Exceptions ===</div>

Dominic https://eden.sahanafoundation.org/index.php?title=Guidelines:CodingStyle&diff=307 2026-10-28T22:11:23Z

<p>Dominic: /* Python */</p> <hr /> <div>* [[Guidelines:Index|All Guidelines]]<br /> <br /> == Coding Style Guide ==<br /> <br /> These conventions should be followed in all code.<br /> <br /> This facilitates a team of developers working on the same code base. If each developer were to use their own style, there would be jarring changes in the code as someone read through it. This slows comprehension and can also cause spurious differences in changesets as developers alter style in frivolous ways on the code they touch.<br /> <br /> Our style guide aims to make the code base appear as if it was written by one precise punctilious programmer, rather than a a cacophony of competing coders. As with many aspects of coding and writing, there can be differences of opinion about the best style. These issues distract from the goal of writing code that works. Most project contributors have a slightly different personal coding style, but we all use the Sahana Eden style when contributing to the Sahana Eden project.<br /> <br /> === Quotes ===<br /> <br /> * for string literals in '''Python''' use double-quotes &lt;code&gt;&quot; &quot;&lt;/code&gt;, unless the string contains double-quotes<br /> * for triple-quoted strings (such as ''Docstrings'' or ''Inline-XML'') use &lt;code&gt;&quot;&quot;&quot; &quot;&quot;&quot;&lt;/code&gt; with double-quotes, except:<br /> * for ''Inline-JavaScript'' or ''JSON'' inside '''Python''' code use &lt;code&gt;&lt;nowiki&gt;''' '''&lt;/nowiki&gt;&lt;/code&gt; with single-quotes<br /> <br /> <br /> Note though that this:<br /> <br /> &lt;code&gt;&lt;nowiki&gt;<br /> inline_javascript = '''sometext=&quot;%s&quot;;''' % sometext<br /> &lt;/nowiki&gt;&lt;/code&gt;<br /> <br /> is a '''potential bug''' - the script breaks when &lt;code&gt;sometext&lt;/code&gt; contains a &lt;code&gt;&quot;&lt;/code&gt;. A safer way to do that is:<br /> <br /> &lt;code&gt;&lt;nowiki&gt;<br /> inline_javascript = '''sometext=%s;''' % json.dumps(sometext)<br /> &lt;/nowiki&gt;&lt;/code&gt;<br /> <br /> <br /> * for string literals in '''JavaScript''' use single-quotes &lt;code&gt;' '&lt;/code&gt;, unless the string contains single-quotes<br /> <br /> <br /> * for attributes in '''HTML''' (such as ''view templates'') use single-quotes &lt;code&gt;attr='value'&lt;/code&gt;<br /> * for attributes in other '''XML''' (e.g. ''XSLT'') use double-quotes &lt;code&gt;&quot; &quot;&lt;/code&gt; (inner quotes must be escaped anyway)<br /> <br /> === Names ===<br /> <br /> ==== General ====<br /> <br /> * Names should be obvious and explicit, but not overly verbose (i.e. as long as they need to be to not make people think). They shouldn't require someone to look in another file or solve a puzzle to figure out what they mean, but shouldn't take too long to write. Avoid inventing new acronyms. e.g. <br /> bad: &lt;code&gt; prm_lkp&lt;/code&gt;, &lt;code&gt;method_that_allows_us_to_create_a_gis_layer&lt;/code&gt;<br /> good: &lt;code&gt;personnel_search&lt;/code&gt;, &lt;code&gt;create_gis_layer&lt;/code&gt;<br /> <br /> ==== Python ====<br /> <br /> * Class names start with an uppercase letter.<br /> * CamelCase is for class names only.<br /> * Constant names are all-uppercase and with underscores as word separator.<br /> * everything else (including table names and field names) should be all-lowercase with underscores as word separator.<br /> * Names should not be Python keywords or standard library names<br /> * Variable names should not start with _undersore (a trailing underscore_ is acceptable in local scope, though)<br /> * Indexes in names should be avoided (e.g. file1, file2), except where they designate new versions of classes/functions (e.g. AddPersonWidget2)<br /> <br /> <br /> * Names for Eden-specific subclasses of web2py classes and all classes which replace existing web2py classes should have the suffix &quot;S3&quot; (e.g. &lt;code&gt;AuthS3&lt;/code&gt;)<br /> * Names for Eden-specific methods (not overrides) in subclasses of web2py classes should start with the prefix &quot;s3_&quot; (e.g. &lt;code&gt;s3_logged_in()&lt;/code&gt;)<br /> * Eden-specific classes ''can'' have an &quot;S3&quot; prefix to their name in order to avoid name collisions, but ideally they ''should not'' (i.e. &lt;code&gt;BasicCRUD&lt;/code&gt; rather than &lt;code&gt;S3BasicCRUD&lt;/code&gt;)<br /> * Method names in Eden-specific classes do not need to (and thus should not) be prefixed<br /> * avoid &quot;s3&quot; or &quot;S3&quot; prefixes in all other cases<br /> <br /> <br /> * &lt;code&gt;DataModel&lt;/code&gt; subclasses in &lt;code&gt;s3db&lt;/code&gt; should start with the all-uppercase module prefix, e.g. &lt;code&gt;DVRCaseModel&lt;/code&gt;<br /> * &lt;code&gt;CRUDMethod&lt;/code&gt; subclasses in &lt;code&gt;s3db&lt;/code&gt; must start with the all-lowercase module prefix plus underscore, e.g. &lt;code&gt;pr_Contacts&lt;/code&gt;<br /> <br /> === Docstrings ===<br /> <br /> All classes and functions must have docstrings that explain what the class or function is intended for and how it is to be used. <br /> <br /> Exceptions can be made where the docstring would merely repeat documentation that already exists in another place, e.g. controllers, or standard interface methods inherited from (and thus documented in) a parent class.<br /> <br /> The function description in the docstring should be a statement in the third person about what the function does — not an imperative instruction telling it what to do.<br /> <br /> ==== Python ====<br /> <br /> We follow loosely the ''Google Style Guide'' for docstrings in Python, albeit with additional indentation:<br /> <br /> &lt;syntaxhighlight lang=&quot;python&quot;&gt;<br /> def card_details(r, idcard):<br /> &quot;&quot;&quot;<br /> Displays the details of the new registration card, and offers<br /> a button to download the PDF.<br /> <br /> Args:<br /> (CRUDRequest) r: the request context<br /> (IDCard) idcard: the new registration card<br /> <br /> Returns:<br /> DIV: the card contents<br /> <br /> Raises:<br /> ValueError: if the idcard is invalid<br /> <br /> Note:<br /> Card secrets will not be rendered.<br /> &quot;&quot;&quot;<br /> &lt;/syntaxhighlight&gt;<br /> <br /> Except where they are obvious, '''data types''' of parameters and return value '''should be included''' in the docstring.<br /> <br /> To that end, '''PEP484-style type hints''' can also be acceptable in simple cases - but are '''discouraged''' for more complex parameter lists as they can easily impair comprehensibility, and not every syntax highlighter will aid the visual parsing of function annotations.<br /> <br /> &lt;syntaxhighlight lang=&quot;python&quot;&gt;<br /> def card_details(r: CRUDRequest, idcard: IDCard) -&gt; DIV:<br /> &quot;&quot;&quot;<br /> Displays the details of the new registration card, and offers<br /> a button to download the PDF<br /> <br /> Args:<br /> r: the request context<br /> idcard: the new registration card<br /> <br /> Returns:<br /> the card contents<br /> <br /> Raises:<br /> ValueError: if the idcard is invalid or expired<br /> <br /> Note:<br /> Card secrets will not be rendered.<br /> &quot;&quot;&quot;<br /> &lt;/syntaxhighlight&gt;<br /> <br /> ==== JavaScript ====<br /> <br /> In JavaScript, we use Java Docstrings.<br /> <br /> &lt;syntaxhighlight lang=&quot;JavaScript&quot;&gt;<br /> /**<br /> * Retrieves events within a certain time interval.<br /> *<br /> * @param {moment|Date|string} start - the start of the interval<br /> * @param {moment|Date|string} end - the end of the interval<br /> *<br /> * @returns {Array} - the events within the interval,<br /> * or null if the interval is not completely cached<br /> */<br /> EventCache.prototype.retrieve = function(start, end) {<br /> ...<br /> };<br /> &lt;/syntaxhighlight&gt;<br /> <br /> Type specifications for parameters and return values are mandatory here.<br /> <br /> === Internationalisation ===<br /> <br /> * All user-visible strings and labels ''must'' be internationalised: &lt;code&gt;T(&quot;My string&quot;)&lt;/code&gt;<br /> <br /> === Exceptions ===</div>

Dominic https://eden.sahanafoundation.org/index.php?title=Guidelines:CodingStyle&diff=306 2026-10-28T22:10:25Z

<p>Dominic: /* Python */</p> <hr /> <div>* [[Guidelines:Index|All Guidelines]]<br /> <br /> == Coding Style Guide ==<br /> <br /> These conventions should be followed in all code.<br /> <br /> This facilitates a team of developers working on the same code base. If each developer were to use their own style, there would be jarring changes in the code as someone read through it. This slows comprehension and can also cause spurious differences in changesets as developers alter style in frivolous ways on the code they touch.<br /> <br /> Our style guide aims to make the code base appear as if it was written by one precise punctilious programmer, rather than a a cacophony of competing coders. As with many aspects of coding and writing, there can be differences of opinion about the best style. These issues distract from the goal of writing code that works. Most project contributors have a slightly different personal coding style, but we all use the Sahana Eden style when contributing to the Sahana Eden project.<br /> <br /> === Quotes ===<br /> <br /> * for string literals in '''Python''' use double-quotes &lt;code&gt;&quot; &quot;&lt;/code&gt;, unless the string contains double-quotes<br /> * for triple-quoted strings (such as ''Docstrings'' or ''Inline-XML'') use &lt;code&gt;&quot;&quot;&quot; &quot;&quot;&quot;&lt;/code&gt; with double-quotes, except:<br /> * for ''Inline-JavaScript'' or ''JSON'' inside '''Python''' code use &lt;code&gt;&lt;nowiki&gt;''' '''&lt;/nowiki&gt;&lt;/code&gt; with single-quotes<br /> <br /> <br /> Note though that this:<br /> <br /> &lt;code&gt;&lt;nowiki&gt;<br /> inline_javascript = '''sometext=&quot;%s&quot;;''' % sometext<br /> &lt;/nowiki&gt;&lt;/code&gt;<br /> <br /> is a '''potential bug''' - the script breaks when &lt;code&gt;sometext&lt;/code&gt; contains a &lt;code&gt;&quot;&lt;/code&gt;. A safer way to do that is:<br /> <br /> &lt;code&gt;&lt;nowiki&gt;<br /> inline_javascript = '''sometext=%s;''' % json.dumps(sometext)<br /> &lt;/nowiki&gt;&lt;/code&gt;<br /> <br /> <br /> * for string literals in '''JavaScript''' use single-quotes &lt;code&gt;' '&lt;/code&gt;, unless the string contains single-quotes<br /> <br /> <br /> * for attributes in '''HTML''' (such as ''view templates'') use single-quotes &lt;code&gt;attr='value'&lt;/code&gt;<br /> * for attributes in other '''XML''' (e.g. ''XSLT'') use double-quotes &lt;code&gt;&quot; &quot;&lt;/code&gt; (inner quotes must be escaped anyway)<br /> <br /> === Names ===<br /> <br /> ==== General ====<br /> <br /> * Names should be obvious and explicit, but not overly verbose (i.e. as long as they need to be to not make people think). They shouldn't require someone to look in another file or solve a puzzle to figure out what they mean, but shouldn't take too long to write. Avoid inventing new acronyms. e.g. <br /> bad: &lt;code&gt; prm_lkp&lt;/code&gt;, &lt;code&gt;method_that_allows_us_to_create_a_gis_layer&lt;/code&gt;<br /> good: &lt;code&gt;personnel_search&lt;/code&gt;, &lt;code&gt;create_gis_layer&lt;/code&gt;<br /> <br /> ==== Python ====<br /> <br /> * Class names start with an uppercase letter.<br /> * CamelCase is for class names only.<br /> * Constant names are all-uppercase and with underscores as word separator.<br /> * everything else (including table names and field names) should be all-lowercase with underscores as word separator.<br /> * Names should not be Python keywords or standard library names<br /> * Variable names should not start with _undersore (a trailing underscore_ is acceptable in local scope, though)<br /> * Indexes in names should be avoided (e.g. file1, file2), except where they designate new versions of classes/functions (e.g. AddPersonWidget2)<br /> <br /> <br /> * Names for Eden-specific subclasses of web2py classes and all classes which replace existing web2py classes should have the suffix &quot;S3&quot; (e.g. &lt;code&gt;AuthS3&lt;/code&gt;)<br /> * Names for Eden-specific methods (not overrides) in subclasses of web2py classes should start with the prefix &quot;s3_&quot; (e.g. &lt;code&gt;s3_logged_in()&lt;/code&gt;)<br /> * Eden-specific classes ''can'' have an &quot;S3&quot; prefix to their name in order to avoid name collisions, but ideally they ''should not'' (i.e. &lt;code&gt;BasicCRUD&lt;/code&gt; rather than &lt;code&gt;S3BasicCRUD&lt;/code&gt;)<br /> * Method names in Eden-specific classes do not need to (and thus should not) be prefixed<br /> * avoid &quot;s3&quot; or &quot;S3&quot; prefixes in all other cases<br /> <br /> <br /> * &lt;code&gt;DataModel&lt;/code&gt; subclasses in &lt;code&gt;s3db&lt;/code&gt; should start with the all-uppercase module prefix, e.g. &lt;code&gt;DVRCaseModel&lt;/code&gt;<br /> * &lt;code&gt;CRUDMethod&lt;/code&gt; subclasses in &lt;code&gt;s3db&lt;/code&gt; must start with the all-lowercase module prefix plus underscore, e.g. &lt;code&gt;pr_Contacts&lt;/code&gt;<br /> <br /> === Docstrings ===<br /> <br /> All classes and functions must have docstrings that explain what the class or function is intended for and how it is to be used. <br /> <br /> Exceptions can be made where the docstring would merely repeat documentation that already exists in another place, e.g. controllers, or standard interface methods inherited from (and thus documented in) a parent class.<br /> <br /> The function description in the docstring should be a statement in the third person about what the function does — not an imperative instruction telling it what to do.<br /> <br /> ==== Python ====<br /> <br /> We follow loosely the ''Google Style Guide'' for docstrings in Python, albeit with additional indentation:<br /> <br /> &lt;syntaxhighlight lang=&quot;python&quot;&gt;<br /> def card_details(r, idcard):<br /> &quot;&quot;&quot;<br /> Displays the details of the new registration card, and offers<br /> a button to download the PDF.<br /> <br /> Args:<br /> (CRUDRequest) r: the request context<br /> (IDCard) idcard: the new registration card<br /> <br /> Returns:<br /> DIV: the card contents<br /> <br /> Raises:<br /> ValueError: if the idcard is invalid<br /> <br /> Note:<br /> Card secrets will not be rendered.<br /> &quot;&quot;&quot;<br /> &lt;/syntaxhighlight&gt;<br /> <br /> Except where they are obvious, '''data types''' of parameters and return value should be included in the docstring.<br /> <br /> To that end, '''PEP484-style type hints''' can also be acceptable in simple cases - but are discouraged for more complex parameter lists as they can easily impair comprehensibility, and not every syntax highlighter will aid the visual parsing of function annotations.<br /> <br /> &lt;syntaxhighlight lang=&quot;python&quot;&gt;<br /> def card_details(r: CRUDRequest, idcard: IDCard) -&gt; DIV:<br /> &quot;&quot;&quot;<br /> Displays the details of the new registration card, and offers<br /> a button to download the PDF<br /> <br /> Args:<br /> r: the request context<br /> idcard: the new registration card<br /> <br /> Returns:<br /> the card contents<br /> <br /> Raises:<br /> ValueError: if the idcard is invalid or expired<br /> <br /> Note:<br /> Card secrets will not be rendered.<br /> &quot;&quot;&quot;<br /> &lt;/syntaxhighlight&gt;<br /> <br /> ==== JavaScript ====<br /> <br /> In JavaScript, we use Java Docstrings.<br /> <br /> &lt;syntaxhighlight lang=&quot;JavaScript&quot;&gt;<br /> /**<br /> * Retrieves events within a certain time interval.<br /> *<br /> * @param {moment|Date|string} start - the start of the interval<br /> * @param {moment|Date|string} end - the end of the interval<br /> *<br /> * @returns {Array} - the events within the interval,<br /> * or null if the interval is not completely cached<br /> */<br /> EventCache.prototype.retrieve = function(start, end) {<br /> ...<br /> };<br /> &lt;/syntaxhighlight&gt;<br /> <br /> Type specifications for parameters and return values are mandatory here.<br /> <br /> === Internationalisation ===<br /> <br /> * All user-visible strings and labels ''must'' be internationalised: &lt;code&gt;T(&quot;My string&quot;)&lt;/code&gt;<br /> <br /> === Exceptions ===</div>

Dominic https://eden.sahanafoundation.org/index.php?title=Guidelines:CodingStyle&diff=305 2026-10-28T22:02:35Z

<p>Dominic: /* Python */</p> <hr /> <div>* [[Guidelines:Index|All Guidelines]]<br /> <br /> == Coding Style Guide ==<br /> <br /> These conventions should be followed in all code.<br /> <br /> This facilitates a team of developers working on the same code base. If each developer were to use their own style, there would be jarring changes in the code as someone read through it. This slows comprehension and can also cause spurious differences in changesets as developers alter style in frivolous ways on the code they touch.<br /> <br /> Our style guide aims to make the code base appear as if it was written by one precise punctilious programmer, rather than a a cacophony of competing coders. As with many aspects of coding and writing, there can be differences of opinion about the best style. These issues distract from the goal of writing code that works. Most project contributors have a slightly different personal coding style, but we all use the Sahana Eden style when contributing to the Sahana Eden project.<br /> <br /> === Quotes ===<br /> <br /> * for string literals in '''Python''' use double-quotes &lt;code&gt;&quot; &quot;&lt;/code&gt;, unless the string contains double-quotes<br /> * for triple-quoted strings (such as ''Docstrings'' or ''Inline-XML'') use &lt;code&gt;&quot;&quot;&quot; &quot;&quot;&quot;&lt;/code&gt; with double-quotes, except:<br /> * for ''Inline-JavaScript'' or ''JSON'' inside '''Python''' code use &lt;code&gt;&lt;nowiki&gt;''' '''&lt;/nowiki&gt;&lt;/code&gt; with single-quotes<br /> <br /> <br /> Note though that this:<br /> <br /> &lt;code&gt;&lt;nowiki&gt;<br /> inline_javascript = '''sometext=&quot;%s&quot;;''' % sometext<br /> &lt;/nowiki&gt;&lt;/code&gt;<br /> <br /> is a '''potential bug''' - the script breaks when &lt;code&gt;sometext&lt;/code&gt; contains a &lt;code&gt;&quot;&lt;/code&gt;. A safer way to do that is:<br /> <br /> &lt;code&gt;&lt;nowiki&gt;<br /> inline_javascript = '''sometext=%s;''' % json.dumps(sometext)<br /> &lt;/nowiki&gt;&lt;/code&gt;<br /> <br /> <br /> * for string literals in '''JavaScript''' use single-quotes &lt;code&gt;' '&lt;/code&gt;, unless the string contains single-quotes<br /> <br /> <br /> * for attributes in '''HTML''' (such as ''view templates'') use single-quotes &lt;code&gt;attr='value'&lt;/code&gt;<br /> * for attributes in other '''XML''' (e.g. ''XSLT'') use double-quotes &lt;code&gt;&quot; &quot;&lt;/code&gt; (inner quotes must be escaped anyway)<br /> <br /> === Names ===<br /> <br /> ==== General ====<br /> <br /> * Names should be obvious and explicit, but not overly verbose (i.e. as long as they need to be to not make people think). They shouldn't require someone to look in another file or solve a puzzle to figure out what they mean, but shouldn't take too long to write. Avoid inventing new acronyms. e.g. <br /> bad: &lt;code&gt; prm_lkp&lt;/code&gt;, &lt;code&gt;method_that_allows_us_to_create_a_gis_layer&lt;/code&gt;<br /> good: &lt;code&gt;personnel_search&lt;/code&gt;, &lt;code&gt;create_gis_layer&lt;/code&gt;<br /> <br /> ==== Python ====<br /> <br /> * Class names start with an uppercase letter.<br /> * CamelCase is for class names only.<br /> * Constant names are all-uppercase and with underscores as word separator.<br /> * everything else (including table names and field names) should be all-lowercase with underscores as word separator.<br /> * Names should not be Python keywords or standard library names<br /> * Variable names should not start with _undersore (a trailing underscore_ is acceptable in local scope, though)<br /> * Indexes in names should be avoided (e.g. file1, file2), except where they designate new versions of classes/functions (e.g. AddPersonWidget2)<br /> <br /> <br /> * Names for Eden-specific subclasses of web2py classes and all classes which replace existing web2py classes should have the suffix &quot;S3&quot; (e.g. &lt;code&gt;AuthS3&lt;/code&gt;)<br /> * Names for Eden-specific methods (not overrides) in subclasses of web2py classes should start with the prefix &quot;s3_&quot; (e.g. &lt;code&gt;s3_logged_in()&lt;/code&gt;)<br /> * Eden-specific classes ''can'' have an &quot;S3&quot; prefix to their name in order to avoid name collisions, but ideally they ''should not'' (i.e. &lt;code&gt;BasicCRUD&lt;/code&gt; rather than &lt;code&gt;S3BasicCRUD&lt;/code&gt;)<br /> * Method names in Eden-specific classes do not need to (and thus should not) be prefixed<br /> * avoid &quot;s3&quot; or &quot;S3&quot; prefixes in all other cases<br /> <br /> <br /> * &lt;code&gt;DataModel&lt;/code&gt; subclasses in &lt;code&gt;s3db&lt;/code&gt; should start with the all-uppercase module prefix, e.g. &lt;code&gt;DVRCaseModel&lt;/code&gt;<br /> * &lt;code&gt;CRUDMethod&lt;/code&gt; subclasses in &lt;code&gt;s3db&lt;/code&gt; must start with the all-lowercase module prefix plus underscore, e.g. &lt;code&gt;pr_Contacts&lt;/code&gt;<br /> <br /> === Docstrings ===<br /> <br /> All classes and functions must have docstrings that explain what the class or function is intended for and how it is to be used. <br /> <br /> Exceptions can be made where the docstring would merely repeat documentation that already exists in another place, e.g. controllers, or standard interface methods inherited from (and thus documented in) a parent class.<br /> <br /> The function description in the docstring should be a statement in the third person about what the function does — not an imperative instruction telling it what to do.<br /> <br /> ==== Python ====<br /> <br /> We follow loosely the ''Google Style Guide'' for docstrings in Python, albeit with additional indentation:<br /> <br /> &lt;syntaxhighlight lang=&quot;python&quot;&gt;<br /> def card_details(r, idcard):<br /> &quot;&quot;&quot;<br /> Displays the details of the new registration card, and offers<br /> a button to download the PDF.<br /> <br /> Args:<br /> (CRUDRequest) r: the request context<br /> (IDCard) idcard: the new registration card<br /> <br /> Returns:<br /> DIV: the card contents<br /> <br /> Raises:<br /> ValueError: if the idcard is invalid<br /> <br /> Note:<br /> Card secrets will not be rendered.<br /> &quot;&quot;&quot;<br /> &lt;/syntaxhighlight&gt;<br /> <br /> Type specifications for parameters and return value are optional, but strongly recommended where the types are not obvious.<br /> <br /> In simple cases, ''PEP484-style type hints'' can also be acceptable - but are discouraged for more complex parameter lists as they can easily impair comprehensibility, and not every syntax highlighter will aid the visual parsing of function annotations.<br /> <br /> &lt;syntaxhighlight lang=&quot;python&quot;&gt;<br /> def card_details(r: CRUDRequest, idcard: IDCard) -&gt; DIV:<br /> &quot;&quot;&quot;<br /> Displays the details of the new registration card, and offers<br /> a button to download the PDF<br /> <br /> Args:<br /> r: the request context<br /> idcard: the new registration card<br /> <br /> Returns:<br /> the card contents<br /> <br /> Raises:<br /> ValueError: if the idcard is invalid or expired<br /> <br /> Note:<br /> Card secrets will not be rendered.<br /> &quot;&quot;&quot;<br /> &lt;/syntaxhighlight&gt;<br /> <br /> ==== JavaScript ====<br /> <br /> In JavaScript, we use Java Docstrings.<br /> <br /> &lt;syntaxhighlight lang=&quot;JavaScript&quot;&gt;<br /> /**<br /> * Retrieves events within a certain time interval.<br /> *<br /> * @param {moment|Date|string} start - the start of the interval<br /> * @param {moment|Date|string} end - the end of the interval<br /> *<br /> * @returns {Array} - the events within the interval,<br /> * or null if the interval is not completely cached<br /> */<br /> EventCache.prototype.retrieve = function(start, end) {<br /> ...<br /> };<br /> &lt;/syntaxhighlight&gt;<br /> <br /> Type specifications for parameters and return values are mandatory here.<br /> <br /> === Internationalisation ===<br /> <br /> * All user-visible strings and labels ''must'' be internationalised: &lt;code&gt;T(&quot;My string&quot;)&lt;/code&gt;<br /> <br /> === Exceptions ===</div>

Dominic https://eden.sahanafoundation.org/index.php?title=Guidelines:CodingStyle&diff=304 2026-10-28T22:01:32Z

<p>Dominic: /* Python */</p> <hr /> <div>* [[Guidelines:Index|All Guidelines]]<br /> <br /> == Coding Style Guide ==<br /> <br /> These conventions should be followed in all code.<br /> <br /> This facilitates a team of developers working on the same code base. If each developer were to use their own style, there would be jarring changes in the code as someone read through it. This slows comprehension and can also cause spurious differences in changesets as developers alter style in frivolous ways on the code they touch.<br /> <br /> Our style guide aims to make the code base appear as if it was written by one precise punctilious programmer, rather than a a cacophony of competing coders. As with many aspects of coding and writing, there can be differences of opinion about the best style. These issues distract from the goal of writing code that works. Most project contributors have a slightly different personal coding style, but we all use the Sahana Eden style when contributing to the Sahana Eden project.<br /> <br /> === Quotes ===<br /> <br /> * for string literals in '''Python''' use double-quotes &lt;code&gt;&quot; &quot;&lt;/code&gt;, unless the string contains double-quotes<br /> * for triple-quoted strings (such as ''Docstrings'' or ''Inline-XML'') use &lt;code&gt;&quot;&quot;&quot; &quot;&quot;&quot;&lt;/code&gt; with double-quotes, except:<br /> * for ''Inline-JavaScript'' or ''JSON'' inside '''Python''' code use &lt;code&gt;&lt;nowiki&gt;''' '''&lt;/nowiki&gt;&lt;/code&gt; with single-quotes<br /> <br /> <br /> Note though that this:<br /> <br /> &lt;code&gt;&lt;nowiki&gt;<br /> inline_javascript = '''sometext=&quot;%s&quot;;''' % sometext<br /> &lt;/nowiki&gt;&lt;/code&gt;<br /> <br /> is a '''potential bug''' - the script breaks when &lt;code&gt;sometext&lt;/code&gt; contains a &lt;code&gt;&quot;&lt;/code&gt;. A safer way to do that is:<br /> <br /> &lt;code&gt;&lt;nowiki&gt;<br /> inline_javascript = '''sometext=%s;''' % json.dumps(sometext)<br /> &lt;/nowiki&gt;&lt;/code&gt;<br /> <br /> <br /> * for string literals in '''JavaScript''' use single-quotes &lt;code&gt;' '&lt;/code&gt;, unless the string contains single-quotes<br /> <br /> <br /> * for attributes in '''HTML''' (such as ''view templates'') use single-quotes &lt;code&gt;attr='value'&lt;/code&gt;<br /> * for attributes in other '''XML''' (e.g. ''XSLT'') use double-quotes &lt;code&gt;&quot; &quot;&lt;/code&gt; (inner quotes must be escaped anyway)<br /> <br /> === Names ===<br /> <br /> ==== General ====<br /> <br /> * Names should be obvious and explicit, but not overly verbose (i.e. as long as they need to be to not make people think). They shouldn't require someone to look in another file or solve a puzzle to figure out what they mean, but shouldn't take too long to write. Avoid inventing new acronyms. e.g. <br /> bad: &lt;code&gt; prm_lkp&lt;/code&gt;, &lt;code&gt;method_that_allows_us_to_create_a_gis_layer&lt;/code&gt;<br /> good: &lt;code&gt;personnel_search&lt;/code&gt;, &lt;code&gt;create_gis_layer&lt;/code&gt;<br /> <br /> ==== Python ====<br /> <br /> * Class names start with an uppercase letter.<br /> * CamelCase is for class names only.<br /> * Constant names are all-uppercase and with underscores as word separator.<br /> * everything else (including table names and field names) should be all-lowercase with underscores as word separator.<br /> * Names should not be Python keywords or standard library names<br /> * Variable names should not start with _undersore (a trailing underscore_ is acceptable in local scope, though)<br /> * Indexes in names should be avoided (e.g. file1, file2), except where they designate new versions of classes/functions (e.g. AddPersonWidget2)<br /> <br /> <br /> * Names for Eden-specific subclasses of web2py classes and all classes which replace existing web2py classes should have the suffix &quot;S3&quot; (e.g. &lt;code&gt;AuthS3&lt;/code&gt;)<br /> * Names for Eden-specific methods (not overrides) in subclasses of web2py classes should start with the prefix &quot;s3_&quot; (e.g. &lt;code&gt;s3_logged_in()&lt;/code&gt;)<br /> * Eden-specific classes ''can'' have an &quot;S3&quot; prefix to their name in order to avoid name collisions, but ideally they ''should not'' (i.e. &lt;code&gt;BasicCRUD&lt;/code&gt; rather than &lt;code&gt;S3BasicCRUD&lt;/code&gt;)<br /> * Method names in Eden-specific classes do not need to (and thus should not) be prefixed<br /> * avoid &quot;s3&quot; or &quot;S3&quot; prefixes in all other cases<br /> <br /> <br /> * &lt;code&gt;DataModel&lt;/code&gt; subclasses in &lt;code&gt;s3db&lt;/code&gt; should start with the all-uppercase module prefix, e.g. &lt;code&gt;DVRCaseModel&lt;/code&gt;<br /> * &lt;code&gt;CRUDMethod&lt;/code&gt; subclasses in &lt;code&gt;s3db&lt;/code&gt; must start with the all-lowercase module prefix plus underscore, e.g. &lt;code&gt;pr_Contacts&lt;/code&gt;<br /> <br /> === Docstrings ===<br /> <br /> All classes and functions must have docstrings that explain what the class or function is intended for and how it is to be used. <br /> <br /> Exceptions can be made where the docstring would merely repeat documentation that already exists in another place, e.g. controllers, or standard interface methods inherited from (and thus documented in) a parent class.<br /> <br /> The function description in the docstring should be a statement in the third person about what the function does — not an imperative instruction telling it what to do.<br /> <br /> ==== Python ====<br /> <br /> We follow loosely the ''Google Style Guide'' for docstrings in Python, albeit with additional indentation:<br /> <br /> &lt;syntaxhighlight lang=&quot;python&quot;&gt;<br /> def card_details(r, idcard):<br /> &quot;&quot;&quot;<br /> Displays the details of the new registration card, and offers<br /> a button to download the PDF.<br /> <br /> Args:<br /> (CRUDRequest) r: the request context<br /> (IDCard) idcard: the new registration card<br /> <br /> Returns:<br /> DIV: the card contents<br /> <br /> Raises:<br /> ValueError: if the idcard is invalid<br /> <br /> Note:<br /> Card secrets will not be rendered.<br /> &quot;&quot;&quot;<br /> &lt;/syntaxhighlight&gt;<br /> <br /> Type specifications for parameters and return value are optional, but strongly recommended where the types are not obvious.<br /> <br /> In simple cases, ''PEP484-style type hints'' can also be acceptable - but are otherwise discouraged as they can easily impair comprehensibility, and not every syntax highlighter will aid the visual parsing of complex function annotations.<br /> <br /> &lt;syntaxhighlight lang=&quot;python&quot;&gt;<br /> def card_details(r: CRUDRequest, idcard: IDCard) -&gt; DIV:<br /> &quot;&quot;&quot;<br /> Displays the details of the new registration card, and offers<br /> a button to download the PDF<br /> <br /> Args:<br /> r: the request context<br /> idcard: the new registration card<br /> <br /> Returns:<br /> the card contents<br /> <br /> Raises:<br /> ValueError: if the idcard is invalid or expired<br /> <br /> Note:<br /> Card secrets will not be rendered.<br /> &quot;&quot;&quot;<br /> &lt;/syntaxhighlight&gt;<br /> <br /> ==== JavaScript ====<br /> <br /> In JavaScript, we use Java Docstrings.<br /> <br /> &lt;syntaxhighlight lang=&quot;JavaScript&quot;&gt;<br /> /**<br /> * Retrieves events within a certain time interval.<br /> *<br /> * @param {moment|Date|string} start - the start of the interval<br /> * @param {moment|Date|string} end - the end of the interval<br /> *<br /> * @returns {Array} - the events within the interval,<br /> * or null if the interval is not completely cached<br /> */<br /> EventCache.prototype.retrieve = function(start, end) {<br /> ...<br /> };<br /> &lt;/syntaxhighlight&gt;<br /> <br /> Type specifications for parameters and return values are mandatory here.<br /> <br /> === Internationalisation ===<br /> <br /> * All user-visible strings and labels ''must'' be internationalised: &lt;code&gt;T(&quot;My string&quot;)&lt;/code&gt;<br /> <br /> === Exceptions ===</div>

Dominic https://eden.sahanafoundation.org/index.php?title=Guidelines:CodingStyle&diff=303 2026-10-28T21:49:16Z

<p>Dominic: /* Python */</p> <hr /> <div>* [[Guidelines:Index|All Guidelines]]<br /> <br /> == Coding Style Guide ==<br /> <br /> These conventions should be followed in all code.<br /> <br /> This facilitates a team of developers working on the same code base. If each developer were to use their own style, there would be jarring changes in the code as someone read through it. This slows comprehension and can also cause spurious differences in changesets as developers alter style in frivolous ways on the code they touch.<br /> <br /> Our style guide aims to make the code base appear as if it was written by one precise punctilious programmer, rather than a a cacophony of competing coders. As with many aspects of coding and writing, there can be differences of opinion about the best style. These issues distract from the goal of writing code that works. Most project contributors have a slightly different personal coding style, but we all use the Sahana Eden style when contributing to the Sahana Eden project.<br /> <br /> === Quotes ===<br /> <br /> * for string literals in '''Python''' use double-quotes &lt;code&gt;&quot; &quot;&lt;/code&gt;, unless the string contains double-quotes<br /> * for triple-quoted strings (such as ''Docstrings'' or ''Inline-XML'') use &lt;code&gt;&quot;&quot;&quot; &quot;&quot;&quot;&lt;/code&gt; with double-quotes, except:<br /> * for ''Inline-JavaScript'' or ''JSON'' inside '''Python''' code use &lt;code&gt;&lt;nowiki&gt;''' '''&lt;/nowiki&gt;&lt;/code&gt; with single-quotes<br /> <br /> <br /> Note though that this:<br /> <br /> &lt;code&gt;&lt;nowiki&gt;<br /> inline_javascript = '''sometext=&quot;%s&quot;;''' % sometext<br /> &lt;/nowiki&gt;&lt;/code&gt;<br /> <br /> is a '''potential bug''' - the script breaks when &lt;code&gt;sometext&lt;/code&gt; contains a &lt;code&gt;&quot;&lt;/code&gt;. A safer way to do that is:<br /> <br /> &lt;code&gt;&lt;nowiki&gt;<br /> inline_javascript = '''sometext=%s;''' % json.dumps(sometext)<br /> &lt;/nowiki&gt;&lt;/code&gt;<br /> <br /> <br /> * for string literals in '''JavaScript''' use single-quotes &lt;code&gt;' '&lt;/code&gt;, unless the string contains single-quotes<br /> <br /> <br /> * for attributes in '''HTML''' (such as ''view templates'') use single-quotes &lt;code&gt;attr='value'&lt;/code&gt;<br /> * for attributes in other '''XML''' (e.g. ''XSLT'') use double-quotes &lt;code&gt;&quot; &quot;&lt;/code&gt; (inner quotes must be escaped anyway)<br /> <br /> === Names ===<br /> <br /> ==== General ====<br /> <br /> * Names should be obvious and explicit, but not overly verbose (i.e. as long as they need to be to not make people think). They shouldn't require someone to look in another file or solve a puzzle to figure out what they mean, but shouldn't take too long to write. Avoid inventing new acronyms. e.g. <br /> bad: &lt;code&gt; prm_lkp&lt;/code&gt;, &lt;code&gt;method_that_allows_us_to_create_a_gis_layer&lt;/code&gt;<br /> good: &lt;code&gt;personnel_search&lt;/code&gt;, &lt;code&gt;create_gis_layer&lt;/code&gt;<br /> <br /> ==== Python ====<br /> <br /> * Class names start with an uppercase letter.<br /> * CamelCase is for class names only.<br /> * Constant names are all-uppercase and with underscores as word separator.<br /> * everything else (including table names and field names) should be all-lowercase with underscores as word separator.<br /> * Names should not be Python keywords or standard library names<br /> * Variable names should not start with _undersore (a trailing underscore_ is acceptable in local scope, though)<br /> * Indexes in names should be avoided (e.g. file1, file2), except where they designate new versions of classes/functions (e.g. AddPersonWidget2)<br /> <br /> <br /> * Names for Eden-specific subclasses of web2py classes and all classes which replace existing web2py classes should have the suffix &quot;S3&quot; (e.g. &lt;code&gt;AuthS3&lt;/code&gt;)<br /> * Names for Eden-specific methods (not overrides) in subclasses of web2py classes should start with the prefix &quot;s3_&quot; (e.g. &lt;code&gt;s3_logged_in()&lt;/code&gt;)<br /> * Eden-specific classes ''can'' have an &quot;S3&quot; prefix to their name in order to avoid name collisions, but ideally they ''should not'' (i.e. &lt;code&gt;BasicCRUD&lt;/code&gt; rather than &lt;code&gt;S3BasicCRUD&lt;/code&gt;)<br /> * Method names in Eden-specific classes do not need to (and thus should not) be prefixed<br /> * avoid &quot;s3&quot; or &quot;S3&quot; prefixes in all other cases<br /> <br /> <br /> * &lt;code&gt;DataModel&lt;/code&gt; subclasses in &lt;code&gt;s3db&lt;/code&gt; should start with the all-uppercase module prefix, e.g. &lt;code&gt;DVRCaseModel&lt;/code&gt;<br /> * &lt;code&gt;CRUDMethod&lt;/code&gt; subclasses in &lt;code&gt;s3db&lt;/code&gt; must start with the all-lowercase module prefix plus underscore, e.g. &lt;code&gt;pr_Contacts&lt;/code&gt;<br /> <br /> === Docstrings ===<br /> <br /> All classes and functions must have docstrings that explain what the class or function is intended for and how it is to be used. <br /> <br /> Exceptions can be made where the docstring would merely repeat documentation that already exists in another place, e.g. controllers, or standard interface methods inherited from (and thus documented in) a parent class.<br /> <br /> The function description in the docstring should be a statement in the third person about what the function does — not an imperative instruction telling it what to do.<br /> <br /> ==== Python ====<br /> <br /> We follow loosely the ''Google Style Guide'' for docstrings in Python, albeit with additional indentation:<br /> <br /> &lt;syntaxhighlight lang=&quot;python&quot;&gt;<br /> def card_details(r, idcard):<br /> &quot;&quot;&quot;<br /> Displays the details of the new registration card, and offers<br /> a button to download the PDF.<br /> <br /> Args:<br /> (CRUDRequest) r: the request context<br /> (IDCard) idcard: the new registration card<br /> <br /> Returns:<br /> DIV: the card contents<br /> <br /> Raises:<br /> ValueError: if the idcard is invalid<br /> <br /> Note:<br /> Card secrets will not be rendered.<br /> &quot;&quot;&quot;<br /> &lt;/syntaxhighlight&gt;<br /> <br /> Type specifications for parameters and return value are optional, but strongly recommended where the types are not obvious.<br /> <br /> In some trivial cases, ''PEP484-style type hints'' can also be acceptable - but are otherwise discouraged as they can easily impair comprehensibility, and not every syntax highlighter will aid the visual parsing of complex function annotations.<br /> <br /> &lt;syntaxhighlight lang=&quot;python&quot;&gt;<br /> def card_details(r: CRUDRequest, idcard: IDCard) -&gt; DIV:<br /> &quot;&quot;&quot;<br /> Displays the details of the new registration card, and offers<br /> a button to download the PDF<br /> <br /> Args:<br /> r: the request context<br /> idcard: the new registration card<br /> <br /> Returns:<br /> the card contents<br /> <br /> Raises:<br /> ValueError: if the idcard is invalid or expired<br /> <br /> Note:<br /> Card secrets will not be rendered.<br /> &quot;&quot;&quot;<br /> &lt;/syntaxhighlight&gt;<br /> <br /> ==== JavaScript ====<br /> <br /> In JavaScript, we use Java Docstrings.<br /> <br /> &lt;syntaxhighlight lang=&quot;JavaScript&quot;&gt;<br /> /**<br /> * Retrieves events within a certain time interval.<br /> *<br /> * @param {moment|Date|string} start - the start of the interval<br /> * @param {moment|Date|string} end - the end of the interval<br /> *<br /> * @returns {Array} - the events within the interval,<br /> * or null if the interval is not completely cached<br /> */<br /> EventCache.prototype.retrieve = function(start, end) {<br /> ...<br /> };<br /> &lt;/syntaxhighlight&gt;<br /> <br /> Type specifications for parameters and return values are mandatory here.<br /> <br /> === Internationalisation ===<br /> <br /> * All user-visible strings and labels ''must'' be internationalised: &lt;code&gt;T(&quot;My string&quot;)&lt;/code&gt;<br /> <br /> === Exceptions ===</div>

Dominic https://eden.sahanafoundation.org/index.php?title=Guidelines:CodingStyle&diff=302 2026-10-28T21:48:26Z

<p>Dominic: /* Python */</p> <hr /> <div>* [[Guidelines:Index|All Guidelines]]<br /> <br /> == Coding Style Guide ==<br /> <br /> These conventions should be followed in all code.<br /> <br /> This facilitates a team of developers working on the same code base. If each developer were to use their own style, there would be jarring changes in the code as someone read through it. This slows comprehension and can also cause spurious differences in changesets as developers alter style in frivolous ways on the code they touch.<br /> <br /> Our style guide aims to make the code base appear as if it was written by one precise punctilious programmer, rather than a a cacophony of competing coders. As with many aspects of coding and writing, there can be differences of opinion about the best style. These issues distract from the goal of writing code that works. Most project contributors have a slightly different personal coding style, but we all use the Sahana Eden style when contributing to the Sahana Eden project.<br /> <br /> === Quotes ===<br /> <br /> * for string literals in '''Python''' use double-quotes &lt;code&gt;&quot; &quot;&lt;/code&gt;, unless the string contains double-quotes<br /> * for triple-quoted strings (such as ''Docstrings'' or ''Inline-XML'') use &lt;code&gt;&quot;&quot;&quot; &quot;&quot;&quot;&lt;/code&gt; with double-quotes, except:<br /> * for ''Inline-JavaScript'' or ''JSON'' inside '''Python''' code use &lt;code&gt;&lt;nowiki&gt;''' '''&lt;/nowiki&gt;&lt;/code&gt; with single-quotes<br /> <br /> <br /> Note though that this:<br /> <br /> &lt;code&gt;&lt;nowiki&gt;<br /> inline_javascript = '''sometext=&quot;%s&quot;;''' % sometext<br /> &lt;/nowiki&gt;&lt;/code&gt;<br /> <br /> is a '''potential bug''' - the script breaks when &lt;code&gt;sometext&lt;/code&gt; contains a &lt;code&gt;&quot;&lt;/code&gt;. A safer way to do that is:<br /> <br /> &lt;code&gt;&lt;nowiki&gt;<br /> inline_javascript = '''sometext=%s;''' % json.dumps(sometext)<br /> &lt;/nowiki&gt;&lt;/code&gt;<br /> <br /> <br /> * for string literals in '''JavaScript''' use single-quotes &lt;code&gt;' '&lt;/code&gt;, unless the string contains single-quotes<br /> <br /> <br /> * for attributes in '''HTML''' (such as ''view templates'') use single-quotes &lt;code&gt;attr='value'&lt;/code&gt;<br /> * for attributes in other '''XML''' (e.g. ''XSLT'') use double-quotes &lt;code&gt;&quot; &quot;&lt;/code&gt; (inner quotes must be escaped anyway)<br /> <br /> === Names ===<br /> <br /> ==== General ====<br /> <br /> * Names should be obvious and explicit, but not overly verbose (i.e. as long as they need to be to not make people think). They shouldn't require someone to look in another file or solve a puzzle to figure out what they mean, but shouldn't take too long to write. Avoid inventing new acronyms. e.g. <br /> bad: &lt;code&gt; prm_lkp&lt;/code&gt;, &lt;code&gt;method_that_allows_us_to_create_a_gis_layer&lt;/code&gt;<br /> good: &lt;code&gt;personnel_search&lt;/code&gt;, &lt;code&gt;create_gis_layer&lt;/code&gt;<br /> <br /> ==== Python ====<br /> <br /> * Class names start with an uppercase letter.<br /> * CamelCase is for class names only.<br /> * Constant names are all-uppercase and with underscores as word separator.<br /> * everything else (including table names and field names) should be all-lowercase with underscores as word separator.<br /> * Names should not be Python keywords or standard library names<br /> * Variable names should not start with _undersore (a trailing underscore_ is acceptable in local scope, though)<br /> * Indexes in names should be avoided (e.g. file1, file2), except where they designate new versions of classes/functions (e.g. AddPersonWidget2)<br /> <br /> <br /> * Names for Eden-specific subclasses of web2py classes and all classes which replace existing web2py classes should have the suffix &quot;S3&quot; (e.g. &lt;code&gt;AuthS3&lt;/code&gt;)<br /> * Names for Eden-specific methods (not overrides) in subclasses of web2py classes should start with the prefix &quot;s3_&quot; (e.g. &lt;code&gt;s3_logged_in()&lt;/code&gt;)<br /> * Eden-specific classes ''can'' have an &quot;S3&quot; prefix to their name in order to avoid name collisions, but ideally they ''should not'' (i.e. &lt;code&gt;BasicCRUD&lt;/code&gt; rather than &lt;code&gt;S3BasicCRUD&lt;/code&gt;)<br /> * Method names in Eden-specific classes do not need to (and thus should not) be prefixed<br /> * avoid &quot;s3&quot; or &quot;S3&quot; prefixes in all other cases<br /> <br /> <br /> * &lt;code&gt;DataModel&lt;/code&gt; subclasses in &lt;code&gt;s3db&lt;/code&gt; should start with the all-uppercase module prefix, e.g. &lt;code&gt;DVRCaseModel&lt;/code&gt;<br /> * &lt;code&gt;CRUDMethod&lt;/code&gt; subclasses in &lt;code&gt;s3db&lt;/code&gt; must start with the all-lowercase module prefix plus underscore, e.g. &lt;code&gt;pr_Contacts&lt;/code&gt;<br /> <br /> === Docstrings ===<br /> <br /> All classes and functions must have docstrings that explain what the class or function is intended for and how it is to be used. <br /> <br /> Exceptions can be made where the docstring would merely repeat documentation that already exists in another place, e.g. controllers, or standard interface methods inherited from (and thus documented in) a parent class.<br /> <br /> The function description in the docstring should be a statement in the third person about what the function does — not an imperative instruction telling it what to do.<br /> <br /> ==== Python ====<br /> <br /> We follow loosely the Google Style Guide for docstrings in Python, albeit with additional indentation:<br /> <br /> &lt;syntaxhighlight lang=&quot;python&quot;&gt;<br /> def card_details(r, idcard):<br /> &quot;&quot;&quot;<br /> Displays the details of the new registration card, and offers<br /> a button to download the PDF.<br /> <br /> Args:<br /> (CRUDRequest) r: the request context<br /> (IDCard) idcard: the new registration card<br /> <br /> Returns:<br /> DIV: the card contents<br /> <br /> Raises:<br /> ValueError: if the idcard is invalid<br /> <br /> Note:<br /> Card secrets will not be rendered.<br /> &quot;&quot;&quot;<br /> &lt;/syntaxhighlight&gt;<br /> <br /> Type specifications for parameters and return value are optional, but strongly recommended where the types are not obvious.<br /> <br /> In some trivial cases, PEP484-style type hints can also be acceptable - but are otherwise discouraged as they can easily impair comprehensibility, and not every syntax highlighter will aid the visual parsing of complex function annotations.<br /> <br /> &lt;syntaxhighlight lang=&quot;python&quot;&gt;<br /> def card_details(r: CRUDRequest, idcard: IDCard) -&gt; DIV:<br /> &quot;&quot;&quot;<br /> Displays the details of the new registration card, and offers<br /> a button to download the PDF<br /> <br /> Args:<br /> r: the request context<br /> idcard: the new registration card<br /> <br /> Returns:<br /> the card contents<br /> <br /> Raises:<br /> ValueError: if the idcard is invalid or expired<br /> <br /> Note:<br /> Card secrets will not be rendered.<br /> &quot;&quot;&quot;<br /> &lt;/syntaxhighlight&gt;<br /> <br /> ==== JavaScript ====<br /> <br /> In JavaScript, we use Java Docstrings.<br /> <br /> &lt;syntaxhighlight lang=&quot;JavaScript&quot;&gt;<br /> /**<br /> * Retrieves events within a certain time interval.<br /> *<br /> * @param {moment|Date|string} start - the start of the interval<br /> * @param {moment|Date|string} end - the end of the interval<br /> *<br /> * @returns {Array} - the events within the interval,<br /> * or null if the interval is not completely cached<br /> */<br /> EventCache.prototype.retrieve = function(start, end) {<br /> ...<br /> };<br /> &lt;/syntaxhighlight&gt;<br /> <br /> Type specifications for parameters and return values are mandatory here.<br /> <br /> === Internationalisation ===<br /> <br /> * All user-visible strings and labels ''must'' be internationalised: &lt;code&gt;T(&quot;My string&quot;)&lt;/code&gt;<br /> <br /> === Exceptions ===</div>

Dominic https://eden.sahanafoundation.org/index.php?title=Guidelines:CodingStyle&diff=301 2026-10-28T21:43:24Z

<p>Dominic: /* Docstrings */</p> <hr /> <div>* [[Guidelines:Index|All Guidelines]]<br /> <br /> == Coding Style Guide ==<br /> <br /> These conventions should be followed in all code.<br /> <br /> This facilitates a team of developers working on the same code base. If each developer were to use their own style, there would be jarring changes in the code as someone read through it. This slows comprehension and can also cause spurious differences in changesets as developers alter style in frivolous ways on the code they touch.<br /> <br /> Our style guide aims to make the code base appear as if it was written by one precise punctilious programmer, rather than a a cacophony of competing coders. As with many aspects of coding and writing, there can be differences of opinion about the best style. These issues distract from the goal of writing code that works. Most project contributors have a slightly different personal coding style, but we all use the Sahana Eden style when contributing to the Sahana Eden project.<br /> <br /> === Quotes ===<br /> <br /> * for string literals in '''Python''' use double-quotes &lt;code&gt;&quot; &quot;&lt;/code&gt;, unless the string contains double-quotes<br /> * for triple-quoted strings (such as ''Docstrings'' or ''Inline-XML'') use &lt;code&gt;&quot;&quot;&quot; &quot;&quot;&quot;&lt;/code&gt; with double-quotes, except:<br /> * for ''Inline-JavaScript'' or ''JSON'' inside '''Python''' code use &lt;code&gt;&lt;nowiki&gt;''' '''&lt;/nowiki&gt;&lt;/code&gt; with single-quotes<br /> <br /> <br /> Note though that this:<br /> <br /> &lt;code&gt;&lt;nowiki&gt;<br /> inline_javascript = '''sometext=&quot;%s&quot;;''' % sometext<br /> &lt;/nowiki&gt;&lt;/code&gt;<br /> <br /> is a '''potential bug''' - the script breaks when &lt;code&gt;sometext&lt;/code&gt; contains a &lt;code&gt;&quot;&lt;/code&gt;. A safer way to do that is:<br /> <br /> &lt;code&gt;&lt;nowiki&gt;<br /> inline_javascript = '''sometext=%s;''' % json.dumps(sometext)<br /> &lt;/nowiki&gt;&lt;/code&gt;<br /> <br /> <br /> * for string literals in '''JavaScript''' use single-quotes &lt;code&gt;' '&lt;/code&gt;, unless the string contains single-quotes<br /> <br /> <br /> * for attributes in '''HTML''' (such as ''view templates'') use single-quotes &lt;code&gt;attr='value'&lt;/code&gt;<br /> * for attributes in other '''XML''' (e.g. ''XSLT'') use double-quotes &lt;code&gt;&quot; &quot;&lt;/code&gt; (inner quotes must be escaped anyway)<br /> <br /> === Names ===<br /> <br /> ==== General ====<br /> <br /> * Names should be obvious and explicit, but not overly verbose (i.e. as long as they need to be to not make people think). They shouldn't require someone to look in another file or solve a puzzle to figure out what they mean, but shouldn't take too long to write. Avoid inventing new acronyms. e.g. <br /> bad: &lt;code&gt; prm_lkp&lt;/code&gt;, &lt;code&gt;method_that_allows_us_to_create_a_gis_layer&lt;/code&gt;<br /> good: &lt;code&gt;personnel_search&lt;/code&gt;, &lt;code&gt;create_gis_layer&lt;/code&gt;<br /> <br /> ==== Python ====<br /> <br /> * Class names start with an uppercase letter.<br /> * CamelCase is for class names only.<br /> * Constant names are all-uppercase and with underscores as word separator.<br /> * everything else (including table names and field names) should be all-lowercase with underscores as word separator.<br /> * Names should not be Python keywords or standard library names<br /> * Variable names should not start with _undersore (a trailing underscore_ is acceptable in local scope, though)<br /> * Indexes in names should be avoided (e.g. file1, file2), except where they designate new versions of classes/functions (e.g. AddPersonWidget2)<br /> <br /> <br /> * Names for Eden-specific subclasses of web2py classes and all classes which replace existing web2py classes should have the suffix &quot;S3&quot; (e.g. &lt;code&gt;AuthS3&lt;/code&gt;)<br /> * Names for Eden-specific methods (not overrides) in subclasses of web2py classes should start with the prefix &quot;s3_&quot; (e.g. &lt;code&gt;s3_logged_in()&lt;/code&gt;)<br /> * Eden-specific classes ''can'' have an &quot;S3&quot; prefix to their name in order to avoid name collisions, but ideally they ''should not'' (i.e. &lt;code&gt;BasicCRUD&lt;/code&gt; rather than &lt;code&gt;S3BasicCRUD&lt;/code&gt;)<br /> * Method names in Eden-specific classes do not need to (and thus should not) be prefixed<br /> * avoid &quot;s3&quot; or &quot;S3&quot; prefixes in all other cases<br /> <br /> <br /> * &lt;code&gt;DataModel&lt;/code&gt; subclasses in &lt;code&gt;s3db&lt;/code&gt; should start with the all-uppercase module prefix, e.g. &lt;code&gt;DVRCaseModel&lt;/code&gt;<br /> * &lt;code&gt;CRUDMethod&lt;/code&gt; subclasses in &lt;code&gt;s3db&lt;/code&gt; must start with the all-lowercase module prefix plus underscore, e.g. &lt;code&gt;pr_Contacts&lt;/code&gt;<br /> <br /> === Docstrings ===<br /> <br /> All classes and functions must have docstrings that explain what the class or function is intended for and how it is to be used. <br /> <br /> Exceptions can be made where the docstring would merely repeat documentation that already exists in another place, e.g. controllers, or standard interface methods inherited from (and thus documented in) a parent class.<br /> <br /> The function description in the docstring should be a statement in the third person about what the function does — not an imperative instruction telling it what to do.<br /> <br /> ==== Python ====<br /> <br /> Acceptable style:<br /> <br /> &lt;syntaxhighlight lang=&quot;python&quot;&gt;<br /> def card_details(r, idcard):<br /> &quot;&quot;&quot;<br /> Displays the details of the new registration card, and offers<br /> a button to download the PDF.<br /> <br /> Args:<br /> (CRUDRequest) r: the request context<br /> (IDCard) idcard: the new registration card<br /> <br /> Returns:<br /> DIV: the card contents<br /> <br /> Raises:<br /> ValueError: if the idcard is invalid<br /> <br /> Note:<br /> Card secrets will not be rendered.<br /> &quot;&quot;&quot;<br /> &lt;/syntaxhighlight&gt;<br /> <br /> Type specifications for parameters and return value are optional, but strongly recommended where the types are not obvious.<br /> <br /> In some trivial cases, PEP484-style type hints can also be acceptable - but are otherwise discouraged as they can easily impair comprehensibility, and not every syntax highlighter will aid the visual parsing of complex function annotations.<br /> <br /> &lt;syntaxhighlight lang=&quot;python&quot;&gt;<br /> def card_details(r: CRUDRequest, idcard: IDCard) -&gt; DIV:<br /> &quot;&quot;&quot;<br /> Displays the details of the new registration card, and offers<br /> a button to download the PDF<br /> <br /> Args:<br /> r: the request context<br /> idcard: the new registration card<br /> <br /> Returns:<br /> the card contents<br /> <br /> Raises:<br /> ValueError: if the idcard is invalid or expired<br /> <br /> Note:<br /> Card secrets will not be rendered.<br /> &quot;&quot;&quot;<br /> &lt;/syntaxhighlight&gt;<br /> <br /> ==== JavaScript ====<br /> <br /> In JavaScript, we use Java Docstrings.<br /> <br /> &lt;syntaxhighlight lang=&quot;JavaScript&quot;&gt;<br /> /**<br /> * Retrieves events within a certain time interval.<br /> *<br /> * @param {moment|Date|string} start - the start of the interval<br /> * @param {moment|Date|string} end - the end of the interval<br /> *<br /> * @returns {Array} - the events within the interval,<br /> * or null if the interval is not completely cached<br /> */<br /> EventCache.prototype.retrieve = function(start, end) {<br /> ...<br /> };<br /> &lt;/syntaxhighlight&gt;<br /> <br /> Type specifications for parameters and return values are mandatory here.<br /> <br /> === Internationalisation ===<br /> <br /> * All user-visible strings and labels ''must'' be internationalised: &lt;code&gt;T(&quot;My string&quot;)&lt;/code&gt;<br /> <br /> === Exceptions ===</div>

Dominic https://eden.sahanafoundation.org/index.php?title=Guidelines:CodingStyle&diff=300 2026-10-28T21:35:43Z

<p>Dominic: /* Docstrings */</p> <hr /> <div>* [[Guidelines:Index|All Guidelines]]<br /> <br /> == Coding Style Guide ==<br /> <br /> These conventions should be followed in all code.<br /> <br /> This facilitates a team of developers working on the same code base. If each developer were to use their own style, there would be jarring changes in the code as someone read through it. This slows comprehension and can also cause spurious differences in changesets as developers alter style in frivolous ways on the code they touch.<br /> <br /> Our style guide aims to make the code base appear as if it was written by one precise punctilious programmer, rather than a a cacophony of competing coders. As with many aspects of coding and writing, there can be differences of opinion about the best style. These issues distract from the goal of writing code that works. Most project contributors have a slightly different personal coding style, but we all use the Sahana Eden style when contributing to the Sahana Eden project.<br /> <br /> === Quotes ===<br /> <br /> * for string literals in '''Python''' use double-quotes &lt;code&gt;&quot; &quot;&lt;/code&gt;, unless the string contains double-quotes<br /> * for triple-quoted strings (such as ''Docstrings'' or ''Inline-XML'') use &lt;code&gt;&quot;&quot;&quot; &quot;&quot;&quot;&lt;/code&gt; with double-quotes, except:<br /> * for ''Inline-JavaScript'' or ''JSON'' inside '''Python''' code use &lt;code&gt;&lt;nowiki&gt;''' '''&lt;/nowiki&gt;&lt;/code&gt; with single-quotes<br /> <br /> <br /> Note though that this:<br /> <br /> &lt;code&gt;&lt;nowiki&gt;<br /> inline_javascript = '''sometext=&quot;%s&quot;;''' % sometext<br /> &lt;/nowiki&gt;&lt;/code&gt;<br /> <br /> is a '''potential bug''' - the script breaks when &lt;code&gt;sometext&lt;/code&gt; contains a &lt;code&gt;&quot;&lt;/code&gt;. A safer way to do that is:<br /> <br /> &lt;code&gt;&lt;nowiki&gt;<br /> inline_javascript = '''sometext=%s;''' % json.dumps(sometext)<br /> &lt;/nowiki&gt;&lt;/code&gt;<br /> <br /> <br /> * for string literals in '''JavaScript''' use single-quotes &lt;code&gt;' '&lt;/code&gt;, unless the string contains single-quotes<br /> <br /> <br /> * for attributes in '''HTML''' (such as ''view templates'') use single-quotes &lt;code&gt;attr='value'&lt;/code&gt;<br /> * for attributes in other '''XML''' (e.g. ''XSLT'') use double-quotes &lt;code&gt;&quot; &quot;&lt;/code&gt; (inner quotes must be escaped anyway)<br /> <br /> === Names ===<br /> <br /> ==== General ====<br /> <br /> * Names should be obvious and explicit, but not overly verbose (i.e. as long as they need to be to not make people think). They shouldn't require someone to look in another file or solve a puzzle to figure out what they mean, but shouldn't take too long to write. Avoid inventing new acronyms. e.g. <br /> bad: &lt;code&gt; prm_lkp&lt;/code&gt;, &lt;code&gt;method_that_allows_us_to_create_a_gis_layer&lt;/code&gt;<br /> good: &lt;code&gt;personnel_search&lt;/code&gt;, &lt;code&gt;create_gis_layer&lt;/code&gt;<br /> <br /> ==== Python ====<br /> <br /> * Class names start with an uppercase letter.<br /> * CamelCase is for class names only.<br /> * Constant names are all-uppercase and with underscores as word separator.<br /> * everything else (including table names and field names) should be all-lowercase with underscores as word separator.<br /> * Names should not be Python keywords or standard library names<br /> * Variable names should not start with _undersore (a trailing underscore_ is acceptable in local scope, though)<br /> * Indexes in names should be avoided (e.g. file1, file2), except where they designate new versions of classes/functions (e.g. AddPersonWidget2)<br /> <br /> <br /> * Names for Eden-specific subclasses of web2py classes and all classes which replace existing web2py classes should have the suffix &quot;S3&quot; (e.g. &lt;code&gt;AuthS3&lt;/code&gt;)<br /> * Names for Eden-specific methods (not overrides) in subclasses of web2py classes should start with the prefix &quot;s3_&quot; (e.g. &lt;code&gt;s3_logged_in()&lt;/code&gt;)<br /> * Eden-specific classes ''can'' have an &quot;S3&quot; prefix to their name in order to avoid name collisions, but ideally they ''should not'' (i.e. &lt;code&gt;BasicCRUD&lt;/code&gt; rather than &lt;code&gt;S3BasicCRUD&lt;/code&gt;)<br /> * Method names in Eden-specific classes do not need to (and thus should not) be prefixed<br /> * avoid &quot;s3&quot; or &quot;S3&quot; prefixes in all other cases<br /> <br /> <br /> * &lt;code&gt;DataModel&lt;/code&gt; subclasses in &lt;code&gt;s3db&lt;/code&gt; should start with the all-uppercase module prefix, e.g. &lt;code&gt;DVRCaseModel&lt;/code&gt;<br /> * &lt;code&gt;CRUDMethod&lt;/code&gt; subclasses in &lt;code&gt;s3db&lt;/code&gt; must start with the all-lowercase module prefix plus underscore, e.g. &lt;code&gt;pr_Contacts&lt;/code&gt;<br /> <br /> === Docstrings ===<br /> <br /> All classes and functions must have docstrings that explain what the class or function is intended for and how it is to be used. <br /> <br /> Exceptions can be made where the docstring would merely repeat documentation that already exists in another place, e.g. controllers, or standard interface methods inherited from (and thus documented in) a parent class.<br /> <br /> The function description in the docstring should be a statement in the third person about what the function does — not an imperative instruction telling it what to do.<br /> <br /> Acceptable style:<br /> <br /> &lt;syntaxhighlight lang=&quot;python&quot;&gt;<br /> def card_details(r, idcard):<br /> &quot;&quot;&quot;<br /> Displays the details of the new registration card, and offers<br /> a button to download the PDF.<br /> <br /> Args:<br /> (CRUDRequest) r: the request context<br /> (IDCard) idcard: the new registration card<br /> <br /> Returns:<br /> DIV: the card contents<br /> <br /> Raises:<br /> ValueError: if the idcard is invalid<br /> <br /> Note:<br /> Card secrets will not be rendered.<br /> &quot;&quot;&quot;<br /> &lt;/syntaxhighlight&gt;<br /> <br /> Type specifications for parameters and return value are optional, but strongly recommended where the types are not obvious.<br /> <br /> In some trivial cases, PEP484-style type hints can also be acceptable - but are otherwise discouraged as they can easily impair comprehensibility, and not every syntax highlighter will aid the visual parsing of function annotations.<br /> <br /> &lt;syntaxhighlight lang=&quot;python&quot;&gt;<br /> def card_details(r: CRUDRequest, idcard: IDCard) -&gt; DIV:<br /> &quot;&quot;&quot;<br /> Displays the details of the new registration card, and offers<br /> a button to download the PDF<br /> <br /> Args:<br /> r: the request context<br /> idcard: the new registration card<br /> <br /> Returns:<br /> the card contents<br /> <br /> Raises:<br /> ValueError: if the idcard is invalid or expired<br /> <br /> Note:<br /> Card secrets will not be rendered.<br /> &quot;&quot;&quot;<br /> &lt;/syntaxhighlight&gt;<br /> <br /> === Internationalisation ===<br /> <br /> * All user-visible strings and labels ''must'' be internationalised: &lt;code&gt;T(&quot;My string&quot;)&lt;/code&gt;<br /> <br /> === Exceptions ===</div>

Dominic https://eden.sahanafoundation.org/index.php?title=Guidelines:CodingStyle&diff=299 2026-10-28T21:31:56Z

<p>Dominic: /* Docstrings */</p> <hr /> <div>* [[Guidelines:Index|All Guidelines]]<br /> <br /> == Coding Style Guide ==<br /> <br /> These conventions should be followed in all code.<br /> <br /> This facilitates a team of developers working on the same code base. If each developer were to use their own style, there would be jarring changes in the code as someone read through it. This slows comprehension and can also cause spurious differences in changesets as developers alter style in frivolous ways on the code they touch.<br /> <br /> Our style guide aims to make the code base appear as if it was written by one precise punctilious programmer, rather than a a cacophony of competing coders. As with many aspects of coding and writing, there can be differences of opinion about the best style. These issues distract from the goal of writing code that works. Most project contributors have a slightly different personal coding style, but we all use the Sahana Eden style when contributing to the Sahana Eden project.<br /> <br /> === Quotes ===<br /> <br /> * for string literals in '''Python''' use double-quotes &lt;code&gt;&quot; &quot;&lt;/code&gt;, unless the string contains double-quotes<br /> * for triple-quoted strings (such as ''Docstrings'' or ''Inline-XML'') use &lt;code&gt;&quot;&quot;&quot; &quot;&quot;&quot;&lt;/code&gt; with double-quotes, except:<br /> * for ''Inline-JavaScript'' or ''JSON'' inside '''Python''' code use &lt;code&gt;&lt;nowiki&gt;''' '''&lt;/nowiki&gt;&lt;/code&gt; with single-quotes<br /> <br /> <br /> Note though that this:<br /> <br /> &lt;code&gt;&lt;nowiki&gt;<br /> inline_javascript = '''sometext=&quot;%s&quot;;''' % sometext<br /> &lt;/nowiki&gt;&lt;/code&gt;<br /> <br /> is a '''potential bug''' - the script breaks when &lt;code&gt;sometext&lt;/code&gt; contains a &lt;code&gt;&quot;&lt;/code&gt;. A safer way to do that is:<br /> <br /> &lt;code&gt;&lt;nowiki&gt;<br /> inline_javascript = '''sometext=%s;''' % json.dumps(sometext)<br /> &lt;/nowiki&gt;&lt;/code&gt;<br /> <br /> <br /> * for string literals in '''JavaScript''' use single-quotes &lt;code&gt;' '&lt;/code&gt;, unless the string contains single-quotes<br /> <br /> <br /> * for attributes in '''HTML''' (such as ''view templates'') use single-quotes &lt;code&gt;attr='value'&lt;/code&gt;<br /> * for attributes in other '''XML''' (e.g. ''XSLT'') use double-quotes &lt;code&gt;&quot; &quot;&lt;/code&gt; (inner quotes must be escaped anyway)<br /> <br /> === Names ===<br /> <br /> ==== General ====<br /> <br /> * Names should be obvious and explicit, but not overly verbose (i.e. as long as they need to be to not make people think). They shouldn't require someone to look in another file or solve a puzzle to figure out what they mean, but shouldn't take too long to write. Avoid inventing new acronyms. e.g. <br /> bad: &lt;code&gt; prm_lkp&lt;/code&gt;, &lt;code&gt;method_that_allows_us_to_create_a_gis_layer&lt;/code&gt;<br /> good: &lt;code&gt;personnel_search&lt;/code&gt;, &lt;code&gt;create_gis_layer&lt;/code&gt;<br /> <br /> ==== Python ====<br /> <br /> * Class names start with an uppercase letter.<br /> * CamelCase is for class names only.<br /> * Constant names are all-uppercase and with underscores as word separator.<br /> * everything else (including table names and field names) should be all-lowercase with underscores as word separator.<br /> * Names should not be Python keywords or standard library names<br /> * Variable names should not start with _undersore (a trailing underscore_ is acceptable in local scope, though)<br /> * Indexes in names should be avoided (e.g. file1, file2), except where they designate new versions of classes/functions (e.g. AddPersonWidget2)<br /> <br /> <br /> * Names for Eden-specific subclasses of web2py classes and all classes which replace existing web2py classes should have the suffix &quot;S3&quot; (e.g. &lt;code&gt;AuthS3&lt;/code&gt;)<br /> * Names for Eden-specific methods (not overrides) in subclasses of web2py classes should start with the prefix &quot;s3_&quot; (e.g. &lt;code&gt;s3_logged_in()&lt;/code&gt;)<br /> * Eden-specific classes ''can'' have an &quot;S3&quot; prefix to their name in order to avoid name collisions, but ideally they ''should not'' (i.e. &lt;code&gt;BasicCRUD&lt;/code&gt; rather than &lt;code&gt;S3BasicCRUD&lt;/code&gt;)<br /> * Method names in Eden-specific classes do not need to (and thus should not) be prefixed<br /> * avoid &quot;s3&quot; or &quot;S3&quot; prefixes in all other cases<br /> <br /> <br /> * &lt;code&gt;DataModel&lt;/code&gt; subclasses in &lt;code&gt;s3db&lt;/code&gt; should start with the all-uppercase module prefix, e.g. &lt;code&gt;DVRCaseModel&lt;/code&gt;<br /> * &lt;code&gt;CRUDMethod&lt;/code&gt; subclasses in &lt;code&gt;s3db&lt;/code&gt; must start with the all-lowercase module prefix plus underscore, e.g. &lt;code&gt;pr_Contacts&lt;/code&gt;<br /> <br /> === Docstrings ===<br /> <br /> All classes and functions must have docstrings that explain what the class or function is intended for and how it is to be used. <br /> <br /> Exceptions can be made where the docstring would merely repeat documentation that already exists in another place, e.g. controllers, or standard interface methods inherited from (and thus documented in) a parent class.<br /> <br /> The function description in the docstring should be a statement in the third person about what the function does — not an imperative instruction telling it what to do.<br /> <br /> Acceptable style:<br /> <br /> &lt;syntaxhighlight lang=&quot;python&quot;&gt;<br /> def card_details(r, idcard):<br /> &quot;&quot;&quot;<br /> Displays the details of the new registration card, and offers<br /> a button to download the PDF.<br /> <br /> Args:<br /> (CRUDRequest) r: the request context<br /> (IDCard) idcard: the new registration card<br /> <br /> Returns:<br /> DIV: the card contents<br /> <br /> Raises:<br /> ValueError: if the idcard is invalid<br /> <br /> Note:<br /> Card secrets will not be rendered.<br /> &quot;&quot;&quot;<br /> &lt;/syntaxhighlight&gt;<br /> <br /> Type specifications for parameters and return value are optional, but strongly recommended where the types are not obvious.<br /> <br /> In some trivial cases, PEP484-style type hints can also be acceptable - but are otherwise discouraged as not every syntax highlighter will aid the visual parsing of function annotations.<br /> <br /> &lt;syntaxhighlight lang=&quot;python&quot;&gt;<br /> def card_details(r: CRUDRequest, idcard: IDCard) -&gt; DIV:<br /> &quot;&quot;&quot;<br /> Displays the details of the new registration card, and offers<br /> a button to download the PDF<br /> <br /> Args:<br /> r: the request context<br /> idcard: the new registration card<br /> <br /> Returns:<br /> the card contents<br /> <br /> Raises:<br /> ValueError: if the idcard is invalid or expired<br /> <br /> Note:<br /> Card secrets will not be rendered.<br /> &quot;&quot;&quot;<br /> &lt;/syntaxhighlight&gt;<br /> <br /> === Internationalisation ===<br /> <br /> * All user-visible strings and labels ''must'' be internationalised: &lt;code&gt;T(&quot;My string&quot;)&lt;/code&gt;<br /> <br /> === Exceptions ===</div>

Dominic https://eden.sahanafoundation.org/index.php?title=Guidelines:CodingStyle&diff=298 2026-10-28T16:17:40Z

<p>Dominic: Created page with &quot;* All Guidelines == Coding Style Guide == These conventions should be followed in all code. This facilitates a team of developers working on the same code base. If each developer were to use their own style, there would be jarring changes in the code as someone read through it. This slows comprehension and can also cause spurious differences in changesets as developers alter style in frivolous ways on the code they touch. Our style guide aims to...&quot;</p> <hr /> <div>* [[Guidelines:Index|All Guidelines]]<br /> <br /> == Coding Style Guide ==<br /> <br /> These conventions should be followed in all code.<br /> <br /> This facilitates a team of developers working on the same code base. If each developer were to use their own style, there would be jarring changes in the code as someone read through it. This slows comprehension and can also cause spurious differences in changesets as developers alter style in frivolous ways on the code they touch.<br /> <br /> Our style guide aims to make the code base appear as if it was written by one precise punctilious programmer, rather than a a cacophony of competing coders. As with many aspects of coding and writing, there can be differences of opinion about the best style. These issues distract from the goal of writing code that works. Most project contributors have a slightly different personal coding style, but we all use the Sahana Eden style when contributing to the Sahana Eden project.<br /> <br /> === Quotes ===<br /> <br /> * for string literals in '''Python''' use double-quotes &lt;code&gt;&quot; &quot;&lt;/code&gt;, unless the string contains double-quotes<br /> * for triple-quoted strings (such as ''Docstrings'' or ''Inline-XML'') use &lt;code&gt;&quot;&quot;&quot; &quot;&quot;&quot;&lt;/code&gt; with double-quotes, except:<br /> * for ''Inline-JavaScript'' or ''JSON'' inside '''Python''' code use &lt;code&gt;&lt;nowiki&gt;''' '''&lt;/nowiki&gt;&lt;/code&gt; with single-quotes<br /> <br /> <br /> Note though that this:<br /> <br /> &lt;code&gt;&lt;nowiki&gt;<br /> inline_javascript = '''sometext=&quot;%s&quot;;''' % sometext<br /> &lt;/nowiki&gt;&lt;/code&gt;<br /> <br /> is a '''potential bug''' - the script breaks when &lt;code&gt;sometext&lt;/code&gt; contains a &lt;code&gt;&quot;&lt;/code&gt;. A safer way to do that is:<br /> <br /> &lt;code&gt;&lt;nowiki&gt;<br /> inline_javascript = '''sometext=%s;''' % json.dumps(sometext)<br /> &lt;/nowiki&gt;&lt;/code&gt;<br /> <br /> <br /> * for string literals in '''JavaScript''' use single-quotes &lt;code&gt;' '&lt;/code&gt;, unless the string contains single-quotes<br /> <br /> <br /> * for attributes in '''HTML''' (such as ''view templates'') use single-quotes &lt;code&gt;attr='value'&lt;/code&gt;<br /> * for attributes in other '''XML''' (e.g. ''XSLT'') use double-quotes &lt;code&gt;&quot; &quot;&lt;/code&gt; (inner quotes must be escaped anyway)<br /> <br /> === Names ===<br /> <br /> ==== General ====<br /> <br /> * Names should be obvious and explicit, but not overly verbose (i.e. as long as they need to be to not make people think). They shouldn't require someone to look in another file or solve a puzzle to figure out what they mean, but shouldn't take too long to write. Avoid inventing new acronyms. e.g. <br /> bad: &lt;code&gt; prm_lkp&lt;/code&gt;, &lt;code&gt;method_that_allows_us_to_create_a_gis_layer&lt;/code&gt;<br /> good: &lt;code&gt;personnel_search&lt;/code&gt;, &lt;code&gt;create_gis_layer&lt;/code&gt;<br /> <br /> ==== Python ====<br /> <br /> * Class names start with an uppercase letter.<br /> * CamelCase is for class names only.<br /> * Constant names are all-uppercase and with underscores as word separator.<br /> * everything else (including table names and field names) should be all-lowercase with underscores as word separator.<br /> * Names should not be Python keywords or standard library names<br /> * Variable names should not start with _undersore (a trailing underscore_ is acceptable in local scope, though)<br /> * Indexes in names should be avoided (e.g. file1, file2), except where they designate new versions of classes/functions (e.g. AddPersonWidget2)<br /> <br /> <br /> * Names for Eden-specific subclasses of web2py classes and all classes which replace existing web2py classes should have the suffix &quot;S3&quot; (e.g. &lt;code&gt;AuthS3&lt;/code&gt;)<br /> * Names for Eden-specific methods (not overrides) in subclasses of web2py classes should start with the prefix &quot;s3_&quot; (e.g. &lt;code&gt;s3_logged_in()&lt;/code&gt;)<br /> * Eden-specific classes ''can'' have an &quot;S3&quot; prefix to their name in order to avoid name collisions, but ideally they ''should not'' (i.e. &lt;code&gt;BasicCRUD&lt;/code&gt; rather than &lt;code&gt;S3BasicCRUD&lt;/code&gt;)<br /> * Method names in Eden-specific classes do not need to (and thus should not) be prefixed<br /> * avoid &quot;s3&quot; or &quot;S3&quot; prefixes in all other cases<br /> <br /> <br /> * &lt;code&gt;DataModel&lt;/code&gt; subclasses in &lt;code&gt;s3db&lt;/code&gt; should start with the all-uppercase module prefix, e.g. &lt;code&gt;DVRCaseModel&lt;/code&gt;<br /> * &lt;code&gt;CRUDMethod&lt;/code&gt; subclasses in &lt;code&gt;s3db&lt;/code&gt; must start with the all-lowercase module prefix plus underscore, e.g. &lt;code&gt;pr_Contacts&lt;/code&gt;<br /> <br /> === Docstrings ===<br /> <br /> All classes and functions must have docstrings that explain what the class or function is intended for and how it is to be used. <br /> <br /> Exceptions can be made where the docstring would merely repeat documentation that already exists in another place, e.g. controllers, or standard interface methods inherited from (and thus documented in) a parent class.<br /> <br /> Acceptable style:<br /> <br /> <br /> <br /> === Internationalisation ===<br /> <br /> * All user-visible strings and labels ''must'' be internationalised: &lt;code&gt;T(&quot;My string&quot;)&lt;/code&gt;<br /> <br /> === Exceptions ===</div>

Dominic https://eden.sahanafoundation.org/index.php?title=Guidelines:Edenctl&diff=297 2026-10-26T20:27:31Z

<p>Dominic: /* Switching Templates */</p> <hr /> <div>[[Guidelines:Deployment|All Deployment Guidelines]]<br /> <br /> = Server Administration with Edenctl =<br /> <br /> The '''edenctl''' tool is a ''bash'' script for Eden server administration on '''Debian/Linux''' that comes with the DEB-Packages of the Eden release. The general usage of this script is (as root user):<br /> <br /> &lt;syntaxhighlight lang=&quot;bash&quot;&gt;<br /> edenctl [command] [parameters]<br /> &lt;/syntaxhighlight&gt;<br /> <br /> === Commands Overview ===<br /> <br /> {| class=&quot;wikitable&quot;<br /> |-<br /> ! Command !! Explanation !! Comments<br /> |-<br /> | setup || Set up a newly installed Eden instance ||<br /> |-<br /> | teardown || Undo a completed setup ||<br /> |-<br /> | start || Start the web interface || <br /> |-<br /> | stop || Stop the web interface || <br /> |-<br /> | shell || Open a Python shell in the web2py+Eden environment || <br /> |-<br /> | run || Run a Python script in the web2py+Eden environment || <br /> |-<br /> | clean || Reset the Eden instance || <br /> |-<br /> | pull || Update Eden from GitHub || new in Eden-6.1<br /> |-<br /> | template || Switch to another configuration template || new in Eden-6.2<br /> |-<br /> | compile || (Re-)compile models, controllers and views || <br /> |}<br /> <br /> == Setup and Teardown ==<br /> <br /> To set up a newly installed Eden, run:<br /> <br /> &lt;syntaxhighlight lang=&quot;bash&quot;&gt;<br /> edenctl setup<br /> &lt;/syntaxhighlight&gt;<br /> <br /> This will run you step-by-step through the setup process. Enter your server details as prompted for (or click enter to accept the default value as shown in square brackets).<br /> <br /> '''''Note:''' The '''setup''' command will not work if the Eden instance has already been set up. To make changes in an already-configured instance, you must edit the configuration files manually.''<br /> <br /> Once completed, you can undo the setup with:<br /> <br /> &lt;syntaxhighlight lang=&quot;bash&quot;&gt;<br /> edenctl teardown<br /> &lt;/syntaxhighlight&gt;<br /> <br /> '''''Note:''' The '''teardown''' command will not drop the Eden database - this must be done manually.''<br /> <br /> == Start and Stop ==<br /> <br /> After the setup, you can start the Eden web interface using:<br /> <br /> &lt;syntaxhighlight lang=&quot;bash&quot;&gt;<br /> edenctl start<br /> &lt;/syntaxhighlight&gt;<br /> <br /> To stop the Eden web interface and thereby prevent user access, run:<br /> <br /> &lt;syntaxhighlight lang=&quot;bash&quot;&gt;<br /> edenctl stop<br /> &lt;/syntaxhighlight&gt;<br /> <br /> '''''Note:''' the front-end web server is always running, so that it can deliver a maintenance info-page to the web user if Eden is not active - the '''start''' and '''stop''' commands only start/stop the uWSGI daemon.''<br /> <br /> == Pull ==<br /> <br /> It is possible to upgrade your Eden instance directly from GitHub, using:<br /> <br /> &lt;syntaxhighlight lang=&quot;bash&quot;&gt;<br /> edenctl pull<br /> &lt;/syntaxhighlight&gt;<br /> <br /> '''''Note:''' It can be necessary to perform certain database migrations after the '''pull''' for Eden to work correctly - always check the release for migration advice.''<br /> <br /> == Shell ==<br /> <br /> To open a Python shell in the web2py+Eden environment, you can use:<br /> <br /> &lt;syntaxhighlight lang=&quot;bash&quot;&gt;<br /> edenctl shell<br /> &lt;/syntaxhighlight&gt;<br /> <br /> == Running Scripts ==<br /> <br /> To run a Python script in the web2py+Eden shell, use:<br /> <br /> &lt;syntaxhighlight lang=&quot;bash&quot;&gt;<br /> edenctl run /path/to/script.py<br /> &lt;/syntaxhighlight&gt;<br /> <br /> == Clean ==<br /> <br /> You can reset the Eden database using:<br /> <br /> &lt;syntaxhighlight lang=&quot;bash&quot;&gt;<br /> edenctl clean<br /> &lt;/syntaxhighlight&gt;<br /> <br /> This will remove all data from the database, and perform a fresh '''first run'''.<br /> <br /> '''''Note:''' This operation is primarily intended for demos, and not recommended for production servers.''<br /> <br /> == Switching Templates ==<br /> <br /> You can switch to a different template using:<br /> <br /> &lt;syntaxhighlight lang=&quot;bash&quot;&gt;<br /> edenctl template &quot;TEMPLATE&quot;<br /> &lt;/syntaxhighlight&gt;<br /> <br /> Instead of a single template, you can also specify a template cascade as a comma-separated list of templates:<br /> <br /> &lt;syntaxhighlight lang=&quot;bash&quot;&gt;<br /> edenctl template &quot;TEMPLATE,TEMPLATE.SUB,TEMPLATE.SUB.Demo&quot;<br /> &lt;/syntaxhighlight&gt;<br /> <br /> '''''Note:''' After switching templates, you need to reset the instance using &lt;code&gt;edenctl clean&lt;/code&gt;.''</div>

Dominic https://eden.sahanafoundation.org/index.php?title=Guidelines:Edenctl&diff=296 2026-10-26T20:27:20Z

<p>Dominic: /* Commands Overview */</p> <hr /> <div>[[Guidelines:Deployment|All Deployment Guidelines]]<br /> <br /> = Server Administration with Edenctl =<br /> <br /> The '''edenctl''' tool is a ''bash'' script for Eden server administration on '''Debian/Linux''' that comes with the DEB-Packages of the Eden release. The general usage of this script is (as root user):<br /> <br /> &lt;syntaxhighlight lang=&quot;bash&quot;&gt;<br /> edenctl [command] [parameters]<br /> &lt;/syntaxhighlight&gt;<br /> <br /> === Commands Overview ===<br /> <br /> {| class=&quot;wikitable&quot;<br /> |-<br /> ! Command !! Explanation !! Comments<br /> |-<br /> | setup || Set up a newly installed Eden instance ||<br /> |-<br /> | teardown || Undo a completed setup ||<br /> |-<br /> | start || Start the web interface || <br /> |-<br /> | stop || Stop the web interface || <br /> |-<br /> | shell || Open a Python shell in the web2py+Eden environment || <br /> |-<br /> | run || Run a Python script in the web2py+Eden environment || <br /> |-<br /> | clean || Reset the Eden instance || <br /> |-<br /> | pull || Update Eden from GitHub || new in Eden-6.1<br /> |-<br /> | template || Switch to another configuration template || new in Eden-6.2<br /> |-<br /> | compile || (Re-)compile models, controllers and views || <br /> |}<br /> <br /> == Setup and Teardown ==<br /> <br /> To set up a newly installed Eden, run:<br /> <br /> &lt;syntaxhighlight lang=&quot;bash&quot;&gt;<br /> edenctl setup<br /> &lt;/syntaxhighlight&gt;<br /> <br /> This will run you step-by-step through the setup process. Enter your server details as prompted for (or click enter to accept the default value as shown in square brackets).<br /> <br /> '''''Note:''' The '''setup''' command will not work if the Eden instance has already been set up. To make changes in an already-configured instance, you must edit the configuration files manually.''<br /> <br /> Once completed, you can undo the setup with:<br /> <br /> &lt;syntaxhighlight lang=&quot;bash&quot;&gt;<br /> edenctl teardown<br /> &lt;/syntaxhighlight&gt;<br /> <br /> '''''Note:''' The '''teardown''' command will not drop the Eden database - this must be done manually.''<br /> <br /> == Start and Stop ==<br /> <br /> After the setup, you can start the Eden web interface using:<br /> <br /> &lt;syntaxhighlight lang=&quot;bash&quot;&gt;<br /> edenctl start<br /> &lt;/syntaxhighlight&gt;<br /> <br /> To stop the Eden web interface and thereby prevent user access, run:<br /> <br /> &lt;syntaxhighlight lang=&quot;bash&quot;&gt;<br /> edenctl stop<br /> &lt;/syntaxhighlight&gt;<br /> <br /> '''''Note:''' the front-end web server is always running, so that it can deliver a maintenance info-page to the web user if Eden is not active - the '''start''' and '''stop''' commands only start/stop the uWSGI daemon.''<br /> <br /> == Pull ==<br /> <br /> It is possible to upgrade your Eden instance directly from GitHub, using:<br /> <br /> &lt;syntaxhighlight lang=&quot;bash&quot;&gt;<br /> edenctl pull<br /> &lt;/syntaxhighlight&gt;<br /> <br /> '''''Note:''' It can be necessary to perform certain database migrations after the '''pull''' for Eden to work correctly - always check the release for migration advice.''<br /> <br /> == Shell ==<br /> <br /> To open a Python shell in the web2py+Eden environment, you can use:<br /> <br /> &lt;syntaxhighlight lang=&quot;bash&quot;&gt;<br /> edenctl shell<br /> &lt;/syntaxhighlight&gt;<br /> <br /> == Running Scripts ==<br /> <br /> To run a Python script in the web2py+Eden shell, use:<br /> <br /> &lt;syntaxhighlight lang=&quot;bash&quot;&gt;<br /> edenctl run /path/to/script.py<br /> &lt;/syntaxhighlight&gt;<br /> <br /> == Clean ==<br /> <br /> You can reset the Eden database using:<br /> <br /> &lt;syntaxhighlight lang=&quot;bash&quot;&gt;<br /> edenctl clean<br /> &lt;/syntaxhighlight&gt;<br /> <br /> This will remove all data from the database, and perform a fresh '''first run'''.<br /> <br /> '''''Note:''' This operation is primarily intended for demos, and not recommended for production servers.''<br /> <br /> == Switching Templates ==<br /> <br /> * ''new in Eden-6.2 (not yet released)''<br /> <br /> You can switch to a different template using:<br /> <br /> &lt;syntaxhighlight lang=&quot;bash&quot;&gt;<br /> edenctl template &quot;TEMPLATE&quot;<br /> &lt;/syntaxhighlight&gt;<br /> <br /> Instead of a single template, you can also specify a template cascade as a comma-separated list of templates:<br /> <br /> &lt;syntaxhighlight lang=&quot;bash&quot;&gt;<br /> edenctl template &quot;TEMPLATE,TEMPLATE.SUB,TEMPLATE.SUB.Demo&quot;<br /> &lt;/syntaxhighlight&gt;<br /> <br /> '''''Note:''' After switching templates, you need to reset the instance using &lt;code&gt;edenctl clean&lt;/code&gt;.''</div>

Dominic https://eden.sahanafoundation.org/index.php?title=Guidelines:DualHost&diff=295 2026-10-26T20:25:43Z

<p>Dominic: /* Dual Host Setup */</p> <hr /> <div>[[Guidelines:Deployment|All Deployment Guidelines]]<br /> <br /> = Dual Host Setup =<br /> <br /> In certain situations, you may want to deploy Eden with the database on a separate host. Follow these steps for Debian/Linux:<br /> <br /> == Prerequisites and Terminology ==<br /> <br /> This guideline assumes that you have two hosts running on Debian/Linux - we will use the '''App Host''' and '''DB Host''' designations here to distinguish between the two.<br /> <br /> Further, we assume that each host has a '''public IP''' (exposed to the internet) and a '''private IP''' (local network only; in some intranet setups, public IP and private IP may be the same). Make a note of the IPs, like this:<br /> <br /> &lt;pre&gt;<br /> apphost-public-ip 000.000.000.000<br /> apphost-private-ip 000.000.000.000<br /> dbhost-public-ip 000.000.000.000<br /> dbhost-private-ip 000.000.000.000<br /> &lt;/pre&gt;<br /> <br /> ...so that you have them readily at hand when walking through this guide. We will use designations like ''&lt;apphost-public-ip&gt;'', for instance, to refer to the public IP of the App Host. In these places, replace the designation with the respective IP address.<br /> <br /> Make sure that you have a '''DNS A-record''' set up for the public IP of the App Host, e.g. in the '''FQDN''' (fully qualified domain name) &quot;eden.example.com&quot;, the &quot;eden&quot; part constitutes the '''hostname''', and &quot;example.com&quot; the '''domain'''.<br /> <br /> == Setting Up Eden Account ==<br /> <br /> Login to the DB Host and create a user account for Eden:<br /> <br /> &lt;syntaxhighlight lang=&quot;bash&quot;&gt;<br /> adduser eden<br /> &lt;/syntaxhighlight&gt;<br /> <br /> Use &lt;code&gt;visudo&lt;/code&gt; to add the following lines to the ''sudoers'' configuration:<br /> <br /> &lt;syntaxhighlight lang=&quot;bash&quot;&gt;<br /> # User rules for eden<br /> eden ALL=(ALL) NOPASSWD:ALL<br /> &lt;/syntaxhighlight&gt;<br /> <br /> This will allow Eden to become ''root'' without password.<br /> <br /> == Configuring Key-based Login ==<br /> <br /> On your local machine, generate a new RSA key pair:<br /> <br /> &lt;syntaxhighlight lang=&quot;bash&quot;&gt;<br /> ssh-keygen -t rsa -m PEM -b 4096 -f eden -C &quot;eden&quot;<br /> &lt;/syntaxhighlight&gt;<br /> <br /> '''''Note:''' Leave the password empty as this key is to be used for script automation''<br /> <br /> This will generate two files, ''eden'' (=private key) and ''eden.pub'' (=public key), in the current directory. Install the public key on the DB Host:<br /> <br /> &lt;syntaxhighlight lang=&quot;bash&quot;&gt;<br /> cat eden.pub | ssh eden@&lt;dbhost-public-ip&gt; &quot;mkdir -p ~/.ssh &amp;&amp; chmod 700 ~/.ssh &amp;&amp; cat &gt;&gt; ~/.ssh/authorized_keys &amp;&amp; chmod 600 ~/.ssh/authorized_keys&quot;<br /> &lt;/syntaxhighlight&gt;<br /> <br /> Copy the private key to the App Host:<br /> <br /> &lt;syntaxhighlight lang=&quot;bash&quot;&gt;<br /> scp eden admin@&lt;apphost-public-ip&gt;:/tmp<br /> &lt;/syntaxhighlight&gt;<br /> <br /> Login to the App Host and store the key in a safe location:<br /> <br /> &lt;syntaxhighlight lang=&quot;bash&quot;&gt;<br /> sudo su -<br /> cp /tmp/eden ~/.ssh<br /> chown root.root ~/.ssh/eden<br /> chmod 600 ~/.ssh/eden<br /> &lt;/syntaxhighlight&gt;<br /> <br /> Verify that you can use this key to SSH-login from the App Host to the DB Host (via private IP), as user ''eden'':<br /> <br /> &lt;syntaxhighlight lang=&quot;bash&quot;&gt;<br /> ssh -i ~/.ssh/eden eden@&lt;dbhost-private-ip&gt;<br /> &lt;/syntaxhighlight&gt;<br /> <br /> == PostgreSQL ==<br /> <br /> === Installing PostgreSQL ===<br /> <br /> On the DB Host, make yourself ''root'':<br /> <br /> &lt;syntaxhighlight lang=&quot;bash&quot;&gt;<br /> sudo su -<br /> &lt;/syntaxhighlight&gt;<br /> <br /> Then install PostgreSQL and PostGIS:<br /> <br /> &lt;syntaxhighlight lang=&quot;bash&quot;&gt;<br /> apt-get update<br /> apt-get install -y postgresql-17 postgresql-17-postgis-3<br /> &lt;/syntaxhighlight&gt;<br /> <br /> === Configuring Host-based Access ===<br /> <br /> You need to tell PostgreSQL that the App Host is permitted to access the DB server. To do so, edit the file &lt;code&gt;/etc/postgresql/17/main/pg_hba.conf&lt;/code&gt;, adding the following lines at the end (using the private IP of the App Host):<br /> <br /> &lt;syntaxhighlight lang=&quot;bash&quot;&gt;<br /> # Eden App Host<br /> host all all &lt;apphost-private-ip&gt;/32 md5<br /> &lt;/syntaxhighlight&gt;<br /> <br /> '''''Note:''' if your DB Host is behind a firewall, access from this IP/subnet to the port 5432 must be allowed. Adjust your firewall configuration as necessary.''<br /> <br /> Further, you must tell PostgreSQL to listen on the private IP of the DB Host. For that, edit the file &lt;code&gt;/etc/postgresql/17/main/postgresql.conf&lt;/code&gt;, and modify the &lt;code&gt;listen_address&lt;/code&gt; setting, adding the private IP of the DB Host:<br /> <br /> &lt;syntaxhighlight lang=&quot;python&quot;&gt;<br /> listen_address = '&lt;dbhost-private-ip&gt;,localhost' # what IP address(es) to listen on;<br /> &lt;/syntaxhighlight&gt;<br /> <br /> Finally, restart PostgreSQL:<br /> <br /> &lt;syntaxhighlight lang=&quot;bash&quot;&gt;<br /> systemctl restart postgresql<br /> &lt;/syntaxhighlight&gt;<br /> <br /> Logout from the DB Host, going back to the App Host.<br /> <br /> == Eden ==<br /> <br /> === Installing Release Package ===<br /> <br /> Copy the Eden DEB-package to the App Host - either using &lt;code&gt;scp&lt;/code&gt; from your local machine, or &lt;code&gt;wget&lt;/code&gt; to fetch it from GitHub, e.g.:<br /> <br /> &lt;syntaxhighlight lang=&quot;bash&quot;&gt;<br /> cd /tmp<br /> wget https://github.com/sahana/eden/releases/download/6.2/sahana-eden-debian13_6.2-1_all.deb<br /> &lt;/syntaxhighlight&gt;<br /> <br /> '''''Note:''' The actual location and name of the package depends on the release - check on GitHub for the latest available package.''<br /> <br /> Login to the App Host and make yourself ''root'':<br /> <br /> &lt;syntaxhighlight lang=&quot;bash&quot;&gt;<br /> sudo su -<br /> &lt;/syntaxhighlight&gt;<br /> <br /> Install the package:<br /> <br /> &lt;syntaxhighlight lang=&quot;bash&quot;&gt;<br /> apt-get update<br /> apt-get install -f /tmp/sahana-eden-debian13_6.2-1_all.deb<br /> &lt;/syntaxhighlight&gt;<br /> <br /> === Configuring DB Host ===<br /> <br /> Create a file &lt;code&gt;/etc/sahana/dbhost.conf&lt;/code&gt;, with the details of the DB Host, so that ''edenctl'' can login there:<br /> <br /> &lt;syntaxhighlight lang=&quot;bash&quot; line&gt;<br /> DBHOST=&lt;dbhost-private-ip&gt;<br /> DBHOST_USER=eden<br /> DBHOST_KEY=/root/.ssh/eden<br /> &lt;/syntaxhighlight&gt;<br /> <br /> === Setup with Edenctl ===<br /> <br /> After that, you can set up the Eden instance as usual:<br /> <br /> &lt;syntaxhighlight lang=&quot;bash&quot;&gt;<br /> edenctl setup<br /> &lt;/syntaxhighlight&gt;<br /> <br /> Eventually, start the Eden instance with:<br /> <br /> &lt;syntaxhighlight lang=&quot;bash&quot;&gt;<br /> edenctl start<br /> &lt;/syntaxhighlight&gt;</div>

Dominic https://eden.sahanafoundation.org/index.php?title=Blueprint:InlineValueSet&diff=294 2026-10-23T08:59:32Z

<p>Dominic: /* Solution Ideas / Proposals */</p> <hr /> <div>* [[Blueprint:Index|All Blueprints]]<br /> <br /> == Inline Components with Specifications from a third Table ==<br /> <br /> === Background ===<br /> <br /> Certain data models define semi-abstract components, with concrete specifications and constraints for the component data determined by records in a third table (spec table).<br /> <br /> One example are medical analyses (e.g. blood tests), where the concrete analysis results that can be recorded are specified in a third table, including data types and plausible/permitted ranges:<br /> <br /> * Master: &lt;code&gt;med_analysis&lt;/code&gt;<br /> * Component: &lt;code&gt;med_analysis_result&lt;/code&gt;<br /> * Specification: &lt;code&gt;med_parameter&lt;/code&gt;<br /> <br /> === Problems ===<br /> <br /> While the current &lt;code&gt;InlineComponent&lt;/code&gt; concept can facilitate the inline data entry for components, it cannot be configured to use specifications from a third table to build the sub-form rows. Validation is done against the component table model alone, without taking constraints from a third table into account.<br /> <br /> Additionally, &lt;code&gt;InlineComponent&lt;/code&gt; does not limit the sub-form to a fixed set of specifications - any number of records, including multiple of the same type, can be added. Selection of sub-form rows from a set of specifications is not supported.<br /> <br /> === Analysis / Requirements ===<br /> <br /> We want a SubForm implementation that<br /> <br /> * generates a list of specifications (parameters) that can be selected by the user for data entry (and de-select, if necessary), permitting only one sub-record per spec<br /> * support the display of additional information about the selectable specs (parameters), such as normal ranges or instructions<br /> * reads these specification from a third table, including validation constraints for each individual parameter, using them to provide a suitable input field (varying SELECT or text-INPUT) and validate the input<br /> * creates or updates the sub-records upon form submission, de-duplicating them by specification (parameter), so that only one record per spec can exist (or zero)<br /> * supports at least one value-field, as well as additional fields for status or references (which could be boolean or choice)<br /> * can be embedded and configured in &lt;code&gt;CustomCRUDForm&lt;/code&gt; declarations, like &lt;code&gt;InlineComponent&lt;/code&gt;<br /> * (possibly) supports a workflow separation, where the initial planning stage allows the selection of parameters, while a later data entry stage only allows the entry of values into already selected parameters (i.e. hiding the selector); reading the current stage/mode either from the master table, or determining it from user permissions (CREATE+UPDATE vs UPDATE-only), or both<br /> <br /> === Solution Ideas / Proposals ===<br /> [https://github.com/sahana/eden/blob/dev/modules/core/methods/dseries.py '''DataSeriesForm'''] is a draft implementation of a widget that renders a form with selectable specifications for sub-record rows. This design has the widget control the entire form rather than only the sub-record rows, and is tailored to the ''med_analysis'' use-case rather than generic.<br /> <br /> The &lt;code&gt;DataSeriesForm&lt;/code&gt; design could be morphed into a &lt;code&gt;SubForm&lt;/code&gt; (proposed class name: ''InlineValueSet'') that can be embedded in a &lt;code&gt;CustomCRUDForm&lt;/code&gt;, where it would only control the sub-record rows, analogous to &lt;code&gt;InlineComponent&lt;/code&gt; or &lt;code&gt;InlineLink&lt;/code&gt;. The client-side control script could use Ajax to retrieve the specifications and validate input via either an extended &lt;code&gt;BasicCRUD.validate&lt;/code&gt; or a new, specific end-point. Further, it could be generalized to cover use-cases beyond ''med_analysis'', including supporting configurable secondary fields and workflow separation.<br /> <br /> === Implementation ===<br /> <br /> === Feedback ===</div>

Dominic https://eden.sahanafoundation.org/index.php?title=Blueprint:InlineValueSet&diff=293 2026-10-23T08:58:00Z

<p>Dominic: /* Solution Ideas / Proposals */</p> <hr /> <div>* [[Blueprint:Index|All Blueprints]]<br /> <br /> == Inline Components with Specifications from a third Table ==<br /> <br /> === Background ===<br /> <br /> Certain data models define semi-abstract components, with concrete specifications and constraints for the component data determined by records in a third table (spec table).<br /> <br /> One example are medical analyses (e.g. blood tests), where the concrete analysis results that can be recorded are specified in a third table, including data types and plausible/permitted ranges:<br /> <br /> * Master: &lt;code&gt;med_analysis&lt;/code&gt;<br /> * Component: &lt;code&gt;med_analysis_result&lt;/code&gt;<br /> * Specification: &lt;code&gt;med_parameter&lt;/code&gt;<br /> <br /> === Problems ===<br /> <br /> While the current &lt;code&gt;InlineComponent&lt;/code&gt; concept can facilitate the inline data entry for components, it cannot be configured to use specifications from a third table to build the sub-form rows. Validation is done against the component table model alone, without taking constraints from a third table into account.<br /> <br /> Additionally, &lt;code&gt;InlineComponent&lt;/code&gt; does not limit the sub-form to a fixed set of specifications - any number of records, including multiple of the same type, can be added. Selection of sub-form rows from a set of specifications is not supported.<br /> <br /> === Analysis / Requirements ===<br /> <br /> We want a SubForm implementation that<br /> <br /> * generates a list of specifications (parameters) that can be selected by the user for data entry (and de-select, if necessary), permitting only one sub-record per spec<br /> * support the display of additional information about the selectable specs (parameters), such as normal ranges or instructions<br /> * reads these specification from a third table, including validation constraints for each individual parameter, using them to provide a suitable input field (varying SELECT or text-INPUT) and validate the input<br /> * creates or updates the sub-records upon form submission, de-duplicating them by specification (parameter), so that only one record per spec can exist (or zero)<br /> * supports at least one value-field, as well as additional fields for status or references (which could be boolean or choice)<br /> * can be embedded and configured in &lt;code&gt;CustomCRUDForm&lt;/code&gt; declarations, like &lt;code&gt;InlineComponent&lt;/code&gt;<br /> * (possibly) supports a workflow separation, where the initial planning stage allows the selection of parameters, while a later data entry stage only allows the entry of values into already selected parameters (i.e. hiding the selector); reading the current stage/mode either from the master table, or determining it from user permissions (CREATE+UPDATE vs UPDATE-only), or both<br /> <br /> === Solution Ideas / Proposals ===<br /> [https://github.com/sahana/eden/blob/dev/modules/core/methods/dseries.py '''DataSeriesForm'''] is a draft implementation of a widget that renders a form with selectable specifications for sub-record rows. This design has the widget control the entire form rather than only the sub-record rows, and is tailored to the med_analysis use-case rather than generic.<br /> <br /> The &lt;code&gt;DataSeriesForm&lt;/code&gt; design could be morphed into a &lt;code&gt;SubForm&lt;/code&gt; (proposed class name: ''InlineValueSet'') that can be embedded in a &lt;code&gt;CustomCRUDForm&lt;/code&gt;, where it would only control the sub-record rows, analogous to &lt;code&gt;InlineComponent&lt;/code&gt; or &lt;code&gt;InlineLink&lt;/code&gt;. The client-side control script could use Ajax to retrieve the specifications and validate input via either an extended &lt;code&gt;BasicCRUD.validate&lt;/code&gt; or a new, specific end-point.<br /> <br /> === Implementation ===<br /> <br /> === Feedback ===</div>

Dominic https://eden.sahanafoundation.org/index.php?title=Blueprint:InlineValueSet&diff=292 2026-10-23T08:36:44Z

<p>Dominic: /* Analysis / Requirements */</p> <hr /> <div>* [[Blueprint:Index|All Blueprints]]<br /> <br /> == Inline Components with Specifications from a third Table ==<br /> <br /> === Background ===<br /> <br /> Certain data models define semi-abstract components, with concrete specifications and constraints for the component data determined by records in a third table (spec table).<br /> <br /> One example are medical analyses (e.g. blood tests), where the concrete analysis results that can be recorded are specified in a third table, including data types and plausible/permitted ranges:<br /> <br /> * Master: &lt;code&gt;med_analysis&lt;/code&gt;<br /> * Component: &lt;code&gt;med_analysis_result&lt;/code&gt;<br /> * Specification: &lt;code&gt;med_parameter&lt;/code&gt;<br /> <br /> === Problems ===<br /> <br /> While the current &lt;code&gt;InlineComponent&lt;/code&gt; concept can facilitate the inline data entry for components, it cannot be configured to use specifications from a third table to build the sub-form rows. Validation is done against the component table model alone, without taking constraints from a third table into account.<br /> <br /> Additionally, &lt;code&gt;InlineComponent&lt;/code&gt; does not limit the sub-form to a fixed set of specifications - any number of records, including multiple of the same type, can be added. Selection of sub-form rows from a set of specifications is not supported.<br /> <br /> === Analysis / Requirements ===<br /> <br /> We want a SubForm implementation that<br /> <br /> * generates a list of specifications (parameters) that can be selected by the user for data entry (and de-select, if necessary), permitting only one sub-record per spec<br /> * support the display of additional information about the selectable specs (parameters), such as normal ranges or instructions<br /> * reads these specification from a third table, including validation constraints for each individual parameter, using them to provide a suitable input field (varying SELECT or text-INPUT) and validate the input<br /> * creates or updates the sub-records upon form submission, de-duplicating them by specification (parameter), so that only one record per spec can exist (or zero)<br /> * supports at least one value-field, as well as additional fields for status or references (which could be boolean or choice)<br /> * can be embedded and configured in &lt;code&gt;CustomCRUDForm&lt;/code&gt; declarations, like &lt;code&gt;InlineComponent&lt;/code&gt;<br /> * (possibly) supports a workflow separation, where the initial planning stage allows the selection of parameters, while a later data entry stage only allows the entry of values into already selected parameters (i.e. hiding the selector); reading the current stage/mode either from the master table, or determining it from user permissions (CREATE+UPDATE vs UPDATE-only), or both<br /> <br /> === Solution Ideas / Proposals ===<br /> <br /> === Implementation ===<br /> <br /> === Feedback ===</div>

Dominic https://eden.sahanafoundation.org/index.php?title=Blueprint:InlineValueSet&diff=291 2026-10-23T08:35:45Z

<p>Dominic: /* Analysis / Requirements */</p> <hr /> <div>* [[Blueprint:Index|All Blueprints]]<br /> <br /> == Inline Components with Specifications from a third Table ==<br /> <br /> === Background ===<br /> <br /> Certain data models define semi-abstract components, with concrete specifications and constraints for the component data determined by records in a third table (spec table).<br /> <br /> One example are medical analyses (e.g. blood tests), where the concrete analysis results that can be recorded are specified in a third table, including data types and plausible/permitted ranges:<br /> <br /> * Master: &lt;code&gt;med_analysis&lt;/code&gt;<br /> * Component: &lt;code&gt;med_analysis_result&lt;/code&gt;<br /> * Specification: &lt;code&gt;med_parameter&lt;/code&gt;<br /> <br /> === Problems ===<br /> <br /> While the current &lt;code&gt;InlineComponent&lt;/code&gt; concept can facilitate the inline data entry for components, it cannot be configured to use specifications from a third table to build the sub-form rows. Validation is done against the component table model alone, without taking constraints from a third table into account.<br /> <br /> Additionally, &lt;code&gt;InlineComponent&lt;/code&gt; does not limit the sub-form to a fixed set of specifications - any number of records, including multiple of the same type, can be added. Selection of sub-form rows from a set of specifications is not supported.<br /> <br /> === Analysis / Requirements ===<br /> <br /> We want a SubForm implementation that<br /> <br /> * generates a list of specifications (parameters) that can be selected by the user for data entry (and de-select, if necessary), permitting only one sub-record per spec<br /> * support the display of additional information about the selectable specs (parameters), such as normal ranges or instructions<br /> * reads these specification from a third table, including validation constraints for each individual parameter, using them to provide a suitable input field (varying SELECT or text-INPUT) and validate the input<br /> * creates or updates the sub-records upon form submission, de-duplicating them by specification (parameter), so that only one record per spec can exist (or zero)<br /> * supports at least one value-field, as well as additional fields for status or references (which could be boolean or choice)<br /> * can be embedded and configured in &lt;code&gt;CustomCRUDForm&lt;/code&gt; declarations, like &lt;code&gt;InlineComponent&lt;/code&gt;<br /> * (possibly) supports a stage separation, where the initial planning stage allows the selection of parameters, while a later data entry stage only allows the entry of values into already selected parameters (i.e. hiding the selector); reading the current stage/mode from the master table, or from user permissions (CREATE+UPDATE vs UPDATE-only)<br /> <br /> === Solution Ideas / Proposals ===<br /> <br /> === Implementation ===<br /> <br /> === Feedback ===</div>

Dominic https://eden.sahanafoundation.org/index.php?title=Blueprint:InlineValueSet&diff=290 2026-10-23T08:30:32Z

<p>Dominic: /* Problems */</p> <hr /> <div>* [[Blueprint:Index|All Blueprints]]<br /> <br /> == Inline Components with Specifications from a third Table ==<br /> <br /> === Background ===<br /> <br /> Certain data models define semi-abstract components, with concrete specifications and constraints for the component data determined by records in a third table (spec table).<br /> <br /> One example are medical analyses (e.g. blood tests), where the concrete analysis results that can be recorded are specified in a third table, including data types and plausible/permitted ranges:<br /> <br /> * Master: &lt;code&gt;med_analysis&lt;/code&gt;<br /> * Component: &lt;code&gt;med_analysis_result&lt;/code&gt;<br /> * Specification: &lt;code&gt;med_parameter&lt;/code&gt;<br /> <br /> === Problems ===<br /> <br /> While the current &lt;code&gt;InlineComponent&lt;/code&gt; concept can facilitate the inline data entry for components, it cannot be configured to use specifications from a third table to build the sub-form rows. Validation is done against the component table model alone, without taking constraints from a third table into account.<br /> <br /> Additionally, &lt;code&gt;InlineComponent&lt;/code&gt; does not limit the sub-form to a fixed set of specifications - any number of records, including multiple of the same type, can be added. Selection of sub-form rows from a set of specifications is not supported.<br /> <br /> === Analysis / Requirements ===<br /> <br /> We want a SubForm implementation that<br /> <br /> * generates a list of specifications (parameters) that can be selected by the user for data entry (and de-selected), permitting only one sub-record per spec<br /> * reads these specification from a third table, including validation constraints for each individual parameter, using them to provide a suitable input field (varying SELECT or text-INPUT) and validate the input<br /> * creates or updates the sub-records upon form submission, de-duplicating them by specification (parameter), so that only one record per spec can exist (or zero)<br /> * supports at least one value-field, as well as additional fields for status or references (which could be boolean or choice)<br /> * can be embedded and configured in &lt;code&gt;CustomCRUDForm&lt;/code&gt; declarations, like &lt;code&gt;InlineComponent&lt;/code&gt;<br /> <br /> === Solution Ideas / Proposals ===<br /> <br /> === Implementation ===<br /> <br /> === Feedback ===</div>

Dominic https://eden.sahanafoundation.org/index.php?title=Blueprint:InlineValueSet&diff=289 2026-10-23T08:29:21Z

<p>Dominic: /* Problems */</p> <hr /> <div>* [[Blueprint:Index|All Blueprints]]<br /> <br /> == Inline Components with Specifications from a third Table ==<br /> <br /> === Background ===<br /> <br /> Certain data models define semi-abstract components, with concrete specifications and constraints for the component data determined by records in a third table (spec table).<br /> <br /> One example are medical analyses (e.g. blood tests), where the concrete analysis results that can be recorded are specified in a third table, including data types and plausible/permitted ranges:<br /> <br /> * Master: &lt;code&gt;med_analysis&lt;/code&gt;<br /> * Component: &lt;code&gt;med_analysis_result&lt;/code&gt;<br /> * Specification: &lt;code&gt;med_parameter&lt;/code&gt;<br /> <br /> === Problems ===<br /> <br /> While the current &lt;code&gt;InlineComponent&lt;/code&gt; concept can facilitate the inline data entry for components, it cannot be configured to use specifications from a third table to build the sub-form rows. Validation is done against the component table model alone, without taking constraints from a third table into account.<br /> <br /> Additionally, &lt;code&gt;InlineComponent&lt;/code&gt; does not limit the sub-form to a fixed set of specifications - any number of records, including multiple of the same type, can be added.<br /> <br /> === Analysis / Requirements ===<br /> <br /> We want a SubForm implementation that<br /> <br /> * generates a list of specifications (parameters) that can be selected by the user for data entry (and de-selected), permitting only one sub-record per spec<br /> * reads these specification from a third table, including validation constraints for each individual parameter, using them to provide a suitable input field (varying SELECT or text-INPUT) and validate the input<br /> * creates or updates the sub-records upon form submission, de-duplicating them by specification (parameter), so that only one record per spec can exist (or zero)<br /> * supports at least one value-field, as well as additional fields for status or references (which could be boolean or choice)<br /> * can be embedded and configured in &lt;code&gt;CustomCRUDForm&lt;/code&gt; declarations, like &lt;code&gt;InlineComponent&lt;/code&gt;<br /> <br /> === Solution Ideas / Proposals ===<br /> <br /> === Implementation ===<br /> <br /> === Feedback ===</div>

Dominic https://eden.sahanafoundation.org/index.php?title=Blueprint:InlineValueSet&diff=288 2026-10-23T08:27:02Z

<p>Dominic: Created page with &quot;* All Blueprints == Inline Components with Specifications from a third Table == === Background === Certain data models define semi-abstract components, with concrete specifications and constraints for the component data determined by records in a third table (spec table). One example are medical analyses (e.g. blood tests), where the concrete analysis results that can be recorded are specified in a third table, including data types and plausible/p...&quot;</p> <hr /> <div>* [[Blueprint:Index|All Blueprints]]<br /> <br /> == Inline Components with Specifications from a third Table ==<br /> <br /> === Background ===<br /> <br /> Certain data models define semi-abstract components, with concrete specifications and constraints for the component data determined by records in a third table (spec table).<br /> <br /> One example are medical analyses (e.g. blood tests), where the concrete analysis results that can be recorded are specified in a third table, including data types and plausible/permitted ranges:<br /> <br /> * Master: &lt;code&gt;med_analysis&lt;/code&gt;<br /> * Component: &lt;code&gt;med_analysis_result&lt;/code&gt;<br /> * Specification: &lt;code&gt;med_parameter&lt;/code&gt;<br /> <br /> === Problems ===<br /> <br /> Wile the current &lt;code&gt;InlineComponent&lt;/code&gt; concept can facilitate the inline data entry for components, it cannot be configured to use specifications from a third table to build the sub-form rows. Validation is done against the component table model alone, without taking constraints from a third table into account.<br /> <br /> Additionally, &lt;code&gt;InlineComponent&lt;/code&gt; does not limit the sub-form to a fixed set of specifications - any number of records, including multiple of the same type, can be added.<br /> <br /> === Analysis / Requirements ===<br /> <br /> We want a SubForm implementation that<br /> <br /> * generates a list of specifications (parameters) that can be selected by the user for data entry (and de-selected), permitting only one sub-record per spec<br /> * reads these specification from a third table, including validation constraints for each individual parameter, using them to provide a suitable input field (varying SELECT or text-INPUT) and validate the input<br /> * creates or updates the sub-records upon form submission, de-duplicating them by specification (parameter), so that only one record per spec can exist (or zero)<br /> * supports at least one value-field, as well as additional fields for status or references (which could be boolean or choice)<br /> * can be embedded and configured in &lt;code&gt;CustomCRUDForm&lt;/code&gt; declarations, like &lt;code&gt;InlineComponent&lt;/code&gt;<br /> <br /> === Solution Ideas / Proposals ===<br /> <br /> === Implementation ===<br /> <br /> === Feedback ===</div>

Dominic https://eden.sahanafoundation.org/index.php?title=Blueprint:Index&diff=287 2026-10-23T08:02:16Z

<p>Dominic: </p> <hr /> <div>= Blueprint Index =<br /> <br /> This is a list of Blueprints on this wiki:<br /> <br /> == Implemented ==<br /> <br /> These blueprints have been implemented, with features currently in productive use. Those marked with an asterisk (*) may need maintenance or an overhaul:<br /> <br /> * [[Blueprint:MapViewer]]<br /> <br /> == Under Development ==<br /> <br /> These are blueprints currently being implemented. The teams implementing them may be looking for additional hands - look out for GitHub issues relating to them, or simply ask on the mailing list:<br /> <br /> === Methodology ===<br /> * [[Blueprint:Blueprint]] - Purpose and Structure of Blueprints<br /> <br /> === Feature Sets ===<br /> * [[Blueprint:FailedLogins]] - Handling of failed logins<br /> * [[Blueprint:InlineValueSet]] - Inline component data entry with constraints set by a third table<br /> <br /> == Accepted ==<br /> <br /> These are blueprints that have been accepted, and are looking for a team to implement them. If you are interested to take the lead on any of these, you can just start working on it and/or ask on the mailing list for further guidance:<br /> <br /> * ''tbw''<br /> <br /> == Proposed ==<br /> <br /> These blueprints have been proposed but not yet considered for implementation, because they may need more research and refinement. If you want to discuss these, just do so on the mailing list:<br /> <br /> * [[Blueprint:ObsTable]] - Observation Tables, a monitoring and decision support tool</div>

Dominic https://eden.sahanafoundation.org/index.php?title=Guidelines:Deployment&diff=286 2026-09-28T07:48:53Z

<p>Dominic: </p> <hr /> <div>* [[Guidelines:Index|All Guidelines]]<br /> <br /> = Installation and Setup =<br /> <br /> == Installation from Release Package ==<br /> <br /> As of version 6.0, Eden provides packaged releases. This is the recommended setup method for production servers. The packages are available as assets attached to the respective GitHub release.<br /> <br /> * [[Guidelines:DebianPackages|Installation on Debian/Linux]]<br /> * [[Guidelines:DualHost|Installation on Debian/Linux with separate DB Host]]<br /> * [[Guidelines:Edenctl|Server Setup and Management with edenctl]]<br /> * [[Guidelines:SecureOperation|SSH Setup Recommendations]]<br /> <br /> == Installation from GitHub Repository ==<br /> <br /> It is also possible to install Eden directly from a GitHub repository. This option is recommended for demos and UAT, where you want to install a development version.<br /> <br /> * [[Guidelines:InstallationScripts|Installation and Configuration scripts for Debian/Linux]]<br /> * [[Guidelines:ServiceScripts|Server Setup and Management using traditional Service Scripts]]</div>

Dominic https://eden.sahanafoundation.org/index.php?title=Guidelines:AI&diff=285 2026-09-28T07:48:39Z

<p>Dominic: </p> <hr /> <div>* [[Guidelines:Index|All Guidelines]]<br /> <br /> = Policy for Responsible AI Contributions =<br /> <br /> We welcome AI-generated, -assisted, or -embedded contributions, provided they<br /> adhere to the following criteria:<br /> <br /> === 1. Clear Identification ===<br /> <br /> Contributions are explicitly labeled as AI-generated, -assisted, or -embedded, including unambiguous disclosure of the AI systems involved, the organizations providing and operating these systems, and the specific infrastructure used.<br /> <br /> === 2. Legal and Licensing Compliance ===<br /> <br /> The organizations responsible for providing and operating the AI technology have signed a ''Contributor License Agreement'' granting the '''Sahana Software Foundation''' unrestricted and irrevocable licenses over the contributions. These agreements include assurances that such organizations are legally entitled to sublicense their rights.<br /> <br /> === 3. Alignment with Goals and Mission ===<br /> <br /> Contributions align with the immediate objectives of the '''Eden''' project and support the broader mission of the '''Sahana Software Foundation'''.<br /> <br /> === 4. Transparent Reasoning ===<br /> <br /> Each contribution is accompanied by a sufficiently detailed, human-understandable rationale, which is reviewed, comprehended, and accepted by the human developer community.<br /> <br /> === 5. Fair Recognition and Compensation ===<br /> <br /> Contributions transparently credit any human efforts or prior art involved and<br /> do not undermine fair compensation where such remuneration was initially intended.<br /> <br /> === 6. Respect for Human Contributors and Oversight ===<br /> <br /> The scale, pace, or impact of AI contributions must not overwhelm or displace human reviewers and contributors. They should not diminish the capacity for human oversight, scrutiny, and understanding nor undermine human efforts to study, develop, maintain, or implement '''Eden'''-based solutions. AI contributions should support, not hinder, meaningful human engagement and the sustainable oversight of the project.<br /> <br /> === 7. Avoidance of Proprietary Dependencies and Ethical Concerns ===<br /> <br /> Contributions do not introduce dependencies on proprietary technologies or services, or on such technologies and services that contribute to or exacerbate the humanitarian challenges that the Eden project aims to address.<br /> <br /> === 8. Non-Discrimination ===<br /> <br /> Contributions must not introduce or perpetuate discrimination against any group based on background, condition or identity, particularly regarding project accessibility and participation.<br /> <br /> === 9. Alignment with Sustainable Development Goals ===<br /> <br /> The resource consumption, structural design, and operational framework of the AI technologies used must be fully verifiable as supporting the [https://sdgs.un.org/goals UN Sustainable Development Goals], ensuring progress in one area does not come at the expense of others.</div>

Dominic https://eden.sahanafoundation.org/index.php?title=Guidelines:Index&diff=284 2026-09-28T07:48:13Z

<p>Dominic: </p> <hr /> <div>== Implementer Guidelines ==<br /> <br /> * [[Guidelines:Deployment|Deployment Guidelines]]<br /> <br /> == Contributor Guidelines ==<br /> <br /> * [[Guidelines:ContributorWorkflow|Git Workflow for Code Contributions]]<br /> * [[Guidelines:AI|Guideline for Responsible AI Contributions]]</div>

Dominic https://eden.sahanafoundation.org/index.php?title=Main_Page&diff=283 2026-09-28T07:47:33Z

<p>Dominic: /* Project Conventions */</p> <hr /> <div>'''Sahana Eden''' is an ''Application Development Kit'' designed to build database-driven web applications tailored for emergency and humanitarian management. It provides a robust foundation for application developers and IT service providers to meet the information management needs of aid organizations and governmental agencies during emergencies, disaster preparedness, and humanitarian operations.<br /> <br /> Eden is '''free and open-source software''' (FOSS) that can be freely used, modified, extended, and integrated by anyone without restrictions.<br /> <br /> As an open project, Eden fosters collaboration and the exchange of knowledge, experiences, and best practices among humanitarian organizations. The project is guided by input from experienced aid organizations worldwide and emphasizes the use of open technology and standards. Nearly all of Eden’s code is developed in close cooperation with humanitarians in the field, ensuring it is directly aligned with real-world needs.<br /> <br /> == Implementing Eden ==<br /> <br /> Sahana Eden is a multi-purpose ''web application'' written for the [https://web2py.com web2py] framework. <br /> <br /> The appearance and business logic of this application can be adjusted to the needs of a particular deployment by altering settings in the &lt;code&gt;models/000_config.py&lt;/code&gt; configuration file on the server. Such adjustments can be minimal, or (more commonly) be extensive customization involving menus, forms, user roles, workflows, data models and even processing logic - so that Eden can be repurposed and adapted for many different use-cases and scenarios.<br /> <br /> Rather than putting all these customizations into one server-side configuration file, they would normally be implemented as Python packages which are then imported as '''configuration templates'''. This way, complex custom configurations can be developed, tested and maintained away from the server - and can easily be shared and re-used in other deployments.<br /> <br /> An '''Eden application''' is understood as such a re-usable configuration template (or a combination of templates), and '''Application Development''' is focused on these templates. <br /> <br /> A small selection of configuration templates is included in the Eden code base. However, downstream projects will often develop their own templates, and may publish and/or market them independently - a business model which we encourage and support.<br /> <br /> == Deploying Eden ==<br /> <br /> === Installation and Setup ===<br /> * [[Guidelines:Deployment|Deployment Guidelines]]<br /> <br /> == How to Contribute ==<br /> <br /> === What to Do ===<br /> <br /> ==== Code ====<br /> * [https://github.com/sahana/eden/issues Issues] are a good starting point for short-term contribution<br /> * [[Blueprint:Index|Blueprints]] describe more complex feature sets and requirements, best suited for longer-term contribution<br /> * Many core modules are looking for a maintainer, who takes long-term overall responsibility for their continuous development, support and documentation. Tell us on our [https://groups.google.com/g/eden-asp mailing list] what you would be interested in leading, and we will guide you to the role.<br /> <br /> ==== Documentation ====<br /> * Our [https://eden-asp.readthedocs.io/en/latest Handbook for Application Developers] needs continuous maintenance and improvement. You can work on the handbook in the [https://github.com/sahana/eden/tree/dev/docs/source code base].<br /> * If you want to contribute to this wiki, you can start by discussing your idea on our [https://groups.google.com/g/eden-asp mailing list] - we will then create a wiki account for you as needed.<br /> <br /> === Information Resources ===<br /> <br /> * [[Code Repository]]<br /> * [[Guidelines:ContributorWorkflow|Git Workflow for Code Contributions]]<br /> <br /> === Project Conventions ===<br /> <br /> * [[Guidelines:AI|Policy for Responsible AI Contributions]]</div>

Dominic https://eden.sahanafoundation.org/index.php?title=Guidelines:AI&diff=282 2026-09-28T07:47:09Z

<p>Dominic: /* Policy for Responsible AI Contributions */</p> <hr /> <div>= Policy for Responsible AI Contributions =<br /> <br /> We welcome AI-generated, -assisted, or -embedded contributions, provided they<br /> adhere to the following criteria:<br /> <br /> === 1. Clear Identification ===<br /> <br /> Contributions are explicitly labeled as AI-generated, -assisted, or -embedded, including unambiguous disclosure of the AI systems involved, the organizations providing and operating these systems, and the specific infrastructure used.<br /> <br /> === 2. Legal and Licensing Compliance ===<br /> <br /> The organizations responsible for providing and operating the AI technology have signed a ''Contributor License Agreement'' granting the '''Sahana Software Foundation''' unrestricted and irrevocable licenses over the contributions. These agreements include assurances that such organizations are legally entitled to sublicense their rights.<br /> <br /> === 3. Alignment with Goals and Mission ===<br /> <br /> Contributions align with the immediate objectives of the '''Eden''' project and support the broader mission of the '''Sahana Software Foundation'''.<br /> <br /> === 4. Transparent Reasoning ===<br /> <br /> Each contribution is accompanied by a sufficiently detailed, human-understandable rationale, which is reviewed, comprehended, and accepted by the human developer community.<br /> <br /> === 5. Fair Recognition and Compensation ===<br /> <br /> Contributions transparently credit any human efforts or prior art involved and<br /> do not undermine fair compensation where such remuneration was initially intended.<br /> <br /> === 6. Respect for Human Contributors and Oversight ===<br /> <br /> The scale, pace, or impact of AI contributions must not overwhelm or displace human reviewers and contributors. They should not diminish the capacity for human oversight, scrutiny, and understanding nor undermine human efforts to study, develop, maintain, or implement '''Eden'''-based solutions. AI contributions should support, not hinder, meaningful human engagement and the sustainable oversight of the project.<br /> <br /> === 7. Avoidance of Proprietary Dependencies and Ethical Concerns ===<br /> <br /> Contributions do not introduce dependencies on proprietary technologies or services, or on such technologies and services that contribute to or exacerbate the humanitarian challenges that the Eden project aims to address.<br /> <br /> === 8. Non-Discrimination ===<br /> <br /> Contributions must not introduce or perpetuate discrimination against any group based on background, condition or identity, particularly regarding project accessibility and participation.<br /> <br /> === 9. Alignment with Sustainable Development Goals ===<br /> <br /> The resource consumption, structural design, and operational framework of the AI technologies used must be fully verifiable as supporting the [https://sdgs.un.org/goals UN Sustainable Development Goals], ensuring progress in one area does not come at the expense of others.</div>

Dominic https://eden.sahanafoundation.org/index.php?title=Guidelines:AI&diff=281 2026-09-16T16:00:44Z

<p>Dominic: /* 9. Alignment with Sustainable Development Goals */</p> <hr /> <div>= Policy for Responsible AI Contributions (Draft Version) =<br /> <br /> We welcome AI-generated, -assisted, or -embedded contributions, provided they<br /> adhere to the following criteria:<br /> <br /> === 1. Clear Identification ===<br /> <br /> Contributions are explicitly labeled as AI-generated, -assisted, or -embedded, including unambiguous disclosure of the AI systems involved, the organizations providing and operating these systems, and the specific infrastructure used.<br /> <br /> === 2. Legal and Licensing Compliance ===<br /> <br /> The organizations responsible for providing and operating the AI technology have signed a ''Contributor License Agreement'' granting the '''Sahana Software Foundation''' unrestricted and irrevocable licenses over the contributions. These agreements include assurances that such organizations are legally entitled to sublicense their rights.<br /> <br /> === 3. Alignment with Goals and Mission ===<br /> <br /> Contributions align with the immediate objectives of the '''Eden''' project and support the broader mission of the '''Sahana Software Foundation'''.<br /> <br /> === 4. Transparent Reasoning ===<br /> <br /> Each contribution is accompanied by a sufficiently detailed, human-understandable rationale, which is reviewed, comprehended, and accepted by the human developer community.<br /> <br /> === 5. Fair Recognition and Compensation ===<br /> <br /> Contributions transparently credit any human efforts or prior art involved and<br /> do not undermine fair compensation where such remuneration was initially intended.<br /> <br /> === 6. Respect for Human Contributors and Oversight ===<br /> <br /> The scale, pace, or impact of AI contributions must not overwhelm or displace human reviewers and contributors. They should not diminish the capacity for human oversight, scrutiny, and understanding nor undermine human efforts to study, develop, maintain, or implement '''Eden'''-based solutions. AI contributions should support, not hinder, meaningful human engagement and the sustainable oversight of the project.<br /> <br /> === 7. Avoidance of Proprietary Dependencies and Ethical Concerns ===<br /> <br /> Contributions do not introduce dependencies on proprietary technologies or services, or on such technologies and services that contribute to or exacerbate the humanitarian challenges that the Eden project aims to address.<br /> <br /> === 8. Non-Discrimination ===<br /> <br /> Contributions must not introduce or perpetuate discrimination against any group based on background, condition or identity, particularly regarding project accessibility and participation.<br /> <br /> === 9. Alignment with Sustainable Development Goals ===<br /> <br /> The resource consumption, structural design, and operational framework of the AI technologies used must be fully verifiable as supporting the [https://sdgs.un.org/goals UN Sustainable Development Goals], ensuring progress in one area does not come at the expense of others.</div>

Dominic https://eden.sahanafoundation.org/index.php?title=Guidelines:AI&diff=280 2026-09-16T15:59:07Z

<p>Dominic: /* 8. Non-Discrimination */</p> <hr /> <div>= Policy for Responsible AI Contributions (Draft Version) =<br /> <br /> We welcome AI-generated, -assisted, or -embedded contributions, provided they<br /> adhere to the following criteria:<br /> <br /> === 1. Clear Identification ===<br /> <br /> Contributions are explicitly labeled as AI-generated, -assisted, or -embedded, including unambiguous disclosure of the AI systems involved, the organizations providing and operating these systems, and the specific infrastructure used.<br /> <br /> === 2. Legal and Licensing Compliance ===<br /> <br /> The organizations responsible for providing and operating the AI technology have signed a ''Contributor License Agreement'' granting the '''Sahana Software Foundation''' unrestricted and irrevocable licenses over the contributions. These agreements include assurances that such organizations are legally entitled to sublicense their rights.<br /> <br /> === 3. Alignment with Goals and Mission ===<br /> <br /> Contributions align with the immediate objectives of the '''Eden''' project and support the broader mission of the '''Sahana Software Foundation'''.<br /> <br /> === 4. Transparent Reasoning ===<br /> <br /> Each contribution is accompanied by a sufficiently detailed, human-understandable rationale, which is reviewed, comprehended, and accepted by the human developer community.<br /> <br /> === 5. Fair Recognition and Compensation ===<br /> <br /> Contributions transparently credit any human efforts or prior art involved and<br /> do not undermine fair compensation where such remuneration was initially intended.<br /> <br /> === 6. Respect for Human Contributors and Oversight ===<br /> <br /> The scale, pace, or impact of AI contributions must not overwhelm or displace human reviewers and contributors. They should not diminish the capacity for human oversight, scrutiny, and understanding nor undermine human efforts to study, develop, maintain, or implement '''Eden'''-based solutions. AI contributions should support, not hinder, meaningful human engagement and the sustainable oversight of the project.<br /> <br /> === 7. Avoidance of Proprietary Dependencies and Ethical Concerns ===<br /> <br /> Contributions do not introduce dependencies on proprietary technologies or services, or on such technologies and services that contribute to or exacerbate the humanitarian challenges that the Eden project aims to address.<br /> <br /> === 8. Non-Discrimination ===<br /> <br /> Contributions must not introduce or perpetuate discrimination against any group based on background, condition or identity, particularly regarding project accessibility and participation.<br /> <br /> === 9. Alignment with Sustainable Development Goals ===<br /> <br /> The resource consumption, structural design, and operational framework of the AI technologies used must be fully verifiable as supporting the UN Sustainable Development Goals, ensuring progress in one area does not come at the expense of others.</div>

Dominic https://eden.sahanafoundation.org/index.php?title=Main_Page&diff=279 2026-09-16T15:56:52Z

<p>Dominic: /* Project Conventions and Policies */</p> <hr /> <div>'''Sahana Eden''' is an ''Application Development Kit'' designed to build database-driven web applications tailored for emergency and humanitarian management. It provides a robust foundation for application developers and IT service providers to meet the information management needs of aid organizations and governmental agencies during emergencies, disaster preparedness, and humanitarian operations.<br /> <br /> Eden is '''free and open-source software''' (FOSS) that can be freely used, modified, extended, and integrated by anyone without restrictions.<br /> <br /> As an open project, Eden fosters collaboration and the exchange of knowledge, experiences, and best practices among humanitarian organizations. The project is guided by input from experienced aid organizations worldwide and emphasizes the use of open technology and standards. Nearly all of Eden’s code is developed in close cooperation with humanitarians in the field, ensuring it is directly aligned with real-world needs.<br /> <br /> == Implementing Eden ==<br /> <br /> Sahana Eden is a multi-purpose ''web application'' written for the [https://web2py.com web2py] framework. <br /> <br /> The appearance and business logic of this application can be adjusted to the needs of a particular deployment by altering settings in the &lt;code&gt;models/000_config.py&lt;/code&gt; configuration file on the server. Such adjustments can be minimal, or (more commonly) be extensive customization involving menus, forms, user roles, workflows, data models and even processing logic - so that Eden can be repurposed and adapted for many different use-cases and scenarios.<br /> <br /> Rather than putting all these customizations into one server-side configuration file, they would normally be implemented as Python packages which are then imported as '''configuration templates'''. This way, complex custom configurations can be developed, tested and maintained away from the server - and can easily be shared and re-used in other deployments.<br /> <br /> An '''Eden application''' is understood as such a re-usable configuration template (or a combination of templates), and '''Application Development''' is focused on these templates. <br /> <br /> A small selection of configuration templates is included in the Eden code base. However, downstream projects will often develop their own templates, and may publish and/or market them independently - a business model which we encourage and support.<br /> <br /> == Deploying Eden ==<br /> <br /> === Installation and Setup ===<br /> * [[Guidelines:Deployment|Deployment Guidelines]]<br /> <br /> == How to Contribute ==<br /> <br /> === What to Do ===<br /> <br /> ==== Code ====<br /> * [https://github.com/sahana/eden/issues Issues] are a good starting point for short-term contribution<br /> * [[Blueprint:Index|Blueprints]] describe more complex feature sets and requirements, best suited for longer-term contribution<br /> * Many core modules are looking for a maintainer, who takes long-term overall responsibility for their continuous development, support and documentation. Tell us on our [https://groups.google.com/g/eden-asp mailing list] what you would be interested in leading, and we will guide you to the role.<br /> <br /> ==== Documentation ====<br /> * Our [https://eden-asp.readthedocs.io/en/latest Handbook for Application Developers] needs continuous maintenance and improvement. You can work on the handbook in the [https://github.com/sahana/eden/tree/dev/docs/source code base].<br /> * If you want to contribute to this wiki, you can start by discussing your idea on our [https://groups.google.com/g/eden-asp mailing list] - we will then create a wiki account for you as needed.<br /> <br /> === Information Resources ===<br /> <br /> * [[Code Repository]]<br /> * [[Guidelines:ContributorWorkflow|Git Workflow for Code Contributions]]<br /> <br /> === Project Conventions ===<br /> <br /> * [[Guidelines:AI|Policy for Responsible AI Contributions (Draft)]]</div>

Dominic https://eden.sahanafoundation.org/index.php?title=Main_Page&diff=278 2026-09-16T15:56:34Z

<p>Dominic: /* How to Do It */</p> <hr /> <div>'''Sahana Eden''' is an ''Application Development Kit'' designed to build database-driven web applications tailored for emergency and humanitarian management. It provides a robust foundation for application developers and IT service providers to meet the information management needs of aid organizations and governmental agencies during emergencies, disaster preparedness, and humanitarian operations.<br /> <br /> Eden is '''free and open-source software''' (FOSS) that can be freely used, modified, extended, and integrated by anyone without restrictions.<br /> <br /> As an open project, Eden fosters collaboration and the exchange of knowledge, experiences, and best practices among humanitarian organizations. The project is guided by input from experienced aid organizations worldwide and emphasizes the use of open technology and standards. Nearly all of Eden’s code is developed in close cooperation with humanitarians in the field, ensuring it is directly aligned with real-world needs.<br /> <br /> == Implementing Eden ==<br /> <br /> Sahana Eden is a multi-purpose ''web application'' written for the [https://web2py.com web2py] framework. <br /> <br /> The appearance and business logic of this application can be adjusted to the needs of a particular deployment by altering settings in the &lt;code&gt;models/000_config.py&lt;/code&gt; configuration file on the server. Such adjustments can be minimal, or (more commonly) be extensive customization involving menus, forms, user roles, workflows, data models and even processing logic - so that Eden can be repurposed and adapted for many different use-cases and scenarios.<br /> <br /> Rather than putting all these customizations into one server-side configuration file, they would normally be implemented as Python packages which are then imported as '''configuration templates'''. This way, complex custom configurations can be developed, tested and maintained away from the server - and can easily be shared and re-used in other deployments.<br /> <br /> An '''Eden application''' is understood as such a re-usable configuration template (or a combination of templates), and '''Application Development''' is focused on these templates. <br /> <br /> A small selection of configuration templates is included in the Eden code base. However, downstream projects will often develop their own templates, and may publish and/or market them independently - a business model which we encourage and support.<br /> <br /> == Deploying Eden ==<br /> <br /> === Installation and Setup ===<br /> * [[Guidelines:Deployment|Deployment Guidelines]]<br /> <br /> == How to Contribute ==<br /> <br /> === What to Do ===<br /> <br /> ==== Code ====<br /> * [https://github.com/sahana/eden/issues Issues] are a good starting point for short-term contribution<br /> * [[Blueprint:Index|Blueprints]] describe more complex feature sets and requirements, best suited for longer-term contribution<br /> * Many core modules are looking for a maintainer, who takes long-term overall responsibility for their continuous development, support and documentation. Tell us on our [https://groups.google.com/g/eden-asp mailing list] what you would be interested in leading, and we will guide you to the role.<br /> <br /> ==== Documentation ====<br /> * Our [https://eden-asp.readthedocs.io/en/latest Handbook for Application Developers] needs continuous maintenance and improvement. You can work on the handbook in the [https://github.com/sahana/eden/tree/dev/docs/source code base].<br /> * If you want to contribute to this wiki, you can start by discussing your idea on our [https://groups.google.com/g/eden-asp mailing list] - we will then create a wiki account for you as needed.<br /> <br /> === Information Resources ===<br /> <br /> * [[Code Repository]]<br /> * [[Guidelines:ContributorWorkflow|Git Workflow for Code Contributions]]<br /> <br /> === Project Conventions and Policies ===<br /> <br /> * [[Guidelines:AI|Policy for Responsible AI Contributions (Draft)]]</div>

Dominic https://eden.sahanafoundation.org/index.php?title=Main_Page&diff=277 2026-09-16T15:53:56Z

<p>Dominic: /* How to Contribute */</p> <hr /> <div>'''Sahana Eden''' is an ''Application Development Kit'' designed to build database-driven web applications tailored for emergency and humanitarian management. It provides a robust foundation for application developers and IT service providers to meet the information management needs of aid organizations and governmental agencies during emergencies, disaster preparedness, and humanitarian operations.<br /> <br /> Eden is '''free and open-source software''' (FOSS) that can be freely used, modified, extended, and integrated by anyone without restrictions.<br /> <br /> As an open project, Eden fosters collaboration and the exchange of knowledge, experiences, and best practices among humanitarian organizations. The project is guided by input from experienced aid organizations worldwide and emphasizes the use of open technology and standards. Nearly all of Eden’s code is developed in close cooperation with humanitarians in the field, ensuring it is directly aligned with real-world needs.<br /> <br /> == Implementing Eden ==<br /> <br /> Sahana Eden is a multi-purpose ''web application'' written for the [https://web2py.com web2py] framework. <br /> <br /> The appearance and business logic of this application can be adjusted to the needs of a particular deployment by altering settings in the &lt;code&gt;models/000_config.py&lt;/code&gt; configuration file on the server. Such adjustments can be minimal, or (more commonly) be extensive customization involving menus, forms, user roles, workflows, data models and even processing logic - so that Eden can be repurposed and adapted for many different use-cases and scenarios.<br /> <br /> Rather than putting all these customizations into one server-side configuration file, they would normally be implemented as Python packages which are then imported as '''configuration templates'''. This way, complex custom configurations can be developed, tested and maintained away from the server - and can easily be shared and re-used in other deployments.<br /> <br /> An '''Eden application''' is understood as such a re-usable configuration template (or a combination of templates), and '''Application Development''' is focused on these templates. <br /> <br /> A small selection of configuration templates is included in the Eden code base. However, downstream projects will often develop their own templates, and may publish and/or market them independently - a business model which we encourage and support.<br /> <br /> == Deploying Eden ==<br /> <br /> === Installation and Setup ===<br /> * [[Guidelines:Deployment|Deployment Guidelines]]<br /> <br /> == How to Contribute ==<br /> <br /> === What to Do ===<br /> <br /> ==== Code ====<br /> * [https://github.com/sahana/eden/issues Issues] are a good starting point for short-term contribution<br /> * [[Blueprint:Index|Blueprints]] describe more complex feature sets and requirements, best suited for longer-term contribution<br /> * Many core modules are looking for a maintainer, who takes long-term overall responsibility for their continuous development, support and documentation. Tell us on our [https://groups.google.com/g/eden-asp mailing list] what you would be interested in leading, and we will guide you to the role.<br /> <br /> ==== Documentation ====<br /> * Our [https://eden-asp.readthedocs.io/en/latest Handbook for Application Developers] needs continuous maintenance and improvement. You can work on the handbook in the [https://github.com/sahana/eden/tree/dev/docs/source code base].<br /> * If you want to contribute to this wiki, you can start by discussing your idea on our [https://groups.google.com/g/eden-asp mailing list] - we will then create a wiki account for you as needed.<br /> <br /> === Information Resources ===<br /> <br /> * [[Code Repository]]<br /> * [[Guidelines:ContributorWorkflow|Git Workflow for Code Contributions]]<br /> <br /> === How to Do It ===<br /> <br /> * [[Guidelines:AI|Policy for Responsible AI Contributions (Draft)]]</div>

Dominic