LimeSurvey Manual - User contributions [en]

Database documentation

2021-05-19T15:04:47Z

Olle: /* question_themes */

This page contains documentation for all database tables and their functionality.

Without prefix, this is all tables, as of 2021-05-19:

answer_l10ns
answers
archived_table_settings
assessments
asset_version
boxes
conditions
defaultvalue_l10ns
defaultvalues
expression_errors
failed_login_attempts
group_l10ns
groups
label_l10ns
labels
labelsets
map_tutorial_users
notifications
old_survey_882234_20210512154558
old_tokens_882234_20210512154558
participant_attribute
participant_attribute_names
participant_attribute_names_lang
participant_attribute_values
participant_shares
participants
permissions
permissiontemplates
plugin_settings
plugins
question_attributes
question_l10ns
question_themes
questions
quota
quota_languagesettings
quota_members
saved_control
sessions
settings_global
settings_user
survey_882234
survey_links
survey_url_parameters
surveymenu
surveymenu_entries
surveys
surveys_groups
surveys_groupsettings
surveys_languagesettings
template_configuration
templates
tutorial_entries
tutorial_entry_relation
tutorials
user_groups
user_in_groups
user_in_permissionrole
users

====question_themes====

Columns:

{|class="wikitable zebra"
! Name || Type || Null || Key || Default || Extra || Description
|-
| id || int(11) || NO || PRI || NULL || auto_increment ||
|-
| name || varchar(150) || NO || MUL || NULL || ||
|-
| visible || varchar(1) || YES || || NULL || ||
|-
| xml_path || varchar(255) || YES || || NULL || || Relative path to the folder which contains config.xml. Relative to different paths depending on theme type (core, user).
|-
| image_path || varchar(255) || YES || || NULL || ||
|-
| title || varchar(100) || NO || || NULL || ||
|-
| creation_date || datetime || YES || || NULL || ||
|-
| author || varchar(150) || YES || || NULL || ||
|-
| author_email || varchar(255) || YES || || NULL || ||
|-
| author_url || varchar(255) || YES || || NULL || ||
|-
| copyright || text || YES || || NULL || ||
|-
| license || text || YES || || NULL || ||
|-
| version || varchar(45) || YES || || NULL || ||
|-
| api_version || varchar(45) || NO || || NULL || ||
|-
| description || text || YES || || NULL || ||
|-
| last_update || datetime || YES || || NULL || ||
|-
| owner_id || int(11) || YES || || NULL || ||
|-
| theme_type || varchar(150) || YES || || NULL || || Always "question_theme"?
|-
| question_type || varchar(150) || NO || || NULL || ||
|-
| core_theme || tinyint(1) || YES || || NULL || ||
|-
| extends || varchar(150) || YES || || NULL || ||
|-
| group || varchar(150) || YES || || NULL || ||
|-
| settings || text || YES || || NULL || ||
|}

Database documentation

2021-05-19T14:03:30Z

Olle: /* question_themes */

This page contains documentation for all database tables and their functionality.

Without prefix, this is all tables, as of 2021-05-19:

answer_l10ns
answers
archived_table_settings
assessments
asset_version
boxes
conditions
defaultvalue_l10ns
defaultvalues
expression_errors
failed_login_attempts
group_l10ns
groups
label_l10ns
labels
labelsets
map_tutorial_users
notifications
old_survey_882234_20210512154558
old_tokens_882234_20210512154558
participant_attribute
participant_attribute_names
participant_attribute_names_lang
participant_attribute_values
participant_shares
participants
permissions
permissiontemplates
plugin_settings
plugins
question_attributes
question_l10ns
question_themes
questions
quota
quota_languagesettings
quota_members
saved_control
sessions
settings_global
settings_user
survey_882234
survey_links
survey_url_parameters
surveymenu
surveymenu_entries
surveys
surveys_groups
surveys_groupsettings
surveys_languagesettings
template_configuration
templates
tutorial_entries
tutorial_entry_relation
tutorials
user_groups
user_in_groups
user_in_permissionrole
users

====question_themes====

Columns:

{|class="wikitable zebra"
! Name || Type || Null || Key || Default || Extra || Description
|-
| id || int(11) || NO || PRI || NULL || auto_increment ||
|-
| name || varchar(150) || NO || MUL || NULL || ||
|-
| visible || varchar(1) || YES || || NULL || ||
|-
| xml_path || varchar(255) || YES || || NULL || || Relative path to the folder which contains config.xml. Relative to different paths depending on theme type (core, user).
|-
| image_path || varchar(255) || YES || || NULL || ||
|-
| title || varchar(100) || NO || || NULL || ||
|-
| creation_date || datetime || YES || || NULL || ||
|-
| author || varchar(150) || YES || || NULL || ||
|-
| author_email || varchar(255) || YES || || NULL || ||
|-
| author_url || varchar(255) || YES || || NULL || ||
|-
| copyright || text || YES || || NULL || ||
|-
| license || text || YES || || NULL || ||
|-
| version || varchar(45) || YES || || NULL || ||
|-
| api_version || varchar(45) || NO || || NULL || ||
|-
| description || text || YES || || NULL || ||
|-
| last_update || datetime || YES || || NULL || ||
|-
| owner_id || int(11) || YES || || NULL || ||
|-
| theme_type || varchar(150) || YES || || NULL || ||
|-
| question_type || varchar(150) || NO || || NULL || ||
|-
| core_theme || tinyint(1) || YES || || NULL || ||
|-
| extends || varchar(150) || YES || || NULL || ||
|-
| group || varchar(150) || YES || || NULL || ||
|-
| settings || text || YES || || NULL || ||
|}

Database documentation

2021-05-19T13:59:51Z

Olle: /* question_themes */

This page contains documentation for all database tables and their functionality.

Without prefix, this is all tables, as of 2021-05-19:

answer_l10ns
answers
archived_table_settings
assessments
asset_version
boxes
conditions
defaultvalue_l10ns
defaultvalues
expression_errors
failed_login_attempts
group_l10ns
groups
label_l10ns
labels
labelsets
map_tutorial_users
notifications
old_survey_882234_20210512154558
old_tokens_882234_20210512154558
participant_attribute
participant_attribute_names
participant_attribute_names_lang
participant_attribute_values
participant_shares
participants
permissions
permissiontemplates
plugin_settings
plugins
question_attributes
question_l10ns
question_themes
questions
quota
quota_languagesettings
quota_members
saved_control
sessions
settings_global
settings_user
survey_882234
survey_links
survey_url_parameters
surveymenu
surveymenu_entries
surveys
surveys_groups
surveys_groupsettings
surveys_languagesettings
template_configuration
templates
tutorial_entries
tutorial_entry_relation
tutorials
user_groups
user_in_groups
user_in_permissionrole
users

====question_themes====

Columns:

{|class="wikitable zebra"
! Name || Type || Null || Key || Default || Extra || Description
|-
| id || int(11) || NO || PRI || NULL || auto_increment ||
|-
| name || varchar(150) || NO || MUL || NULL || ||
|-
| visible || varchar(1) || YES || || NULL || ||
|-
| xml_path || varchar(255) || YES || || NULL || ||
|-
| image_path || varchar(255) || YES || || NULL || ||
|-
| title || varchar(100) || NO || || NULL || ||
|-
| creation_date || datetime || YES || || NULL || ||
|-
| author || varchar(150) || YES || || NULL || ||
|-
| author_email || varchar(255) || YES || || NULL || ||
|-
| author_url || varchar(255) || YES || || NULL || ||
|-
| copyright || text || YES || || NULL || ||
|-
| license || text || YES || || NULL || ||
|-
| version || varchar(45) || YES || || NULL || ||
|-
| api_version || varchar(45) || NO || || NULL || ||
|-
| description || text || YES || || NULL || ||
|-
| last_update || datetime || YES || || NULL || ||
|-
| owner_id || int(11) || YES || || NULL || ||
|-
| theme_type || varchar(150) || YES || || NULL || ||
|-
| question_type || varchar(150) || NO || || NULL || ||
|-
| core_theme || tinyint(1) || YES || || NULL || ||
|-
| extends || varchar(150) || YES || || NULL || ||
|-
| group || varchar(150) || YES || || NULL || ||
|-
| settings || text || YES || || NULL || ||
|}

Database documentation

2021-05-19T13:56:08Z

Olle: /* question_themes */

This page contains documentation for all database tables and their functionality.

Without prefix, this is all tables, as of 2021-05-19:

answer_l10ns
answers
archived_table_settings
assessments
asset_version
boxes
conditions
defaultvalue_l10ns
defaultvalues
expression_errors
failed_login_attempts
group_l10ns
groups
label_l10ns
labels
labelsets
map_tutorial_users
notifications
old_survey_882234_20210512154558
old_tokens_882234_20210512154558
participant_attribute
participant_attribute_names
participant_attribute_names_lang
participant_attribute_values
participant_shares
participants
permissions
permissiontemplates
plugin_settings
plugins
question_attributes
question_l10ns
question_themes
questions
quota
quota_languagesettings
quota_members
saved_control
sessions
settings_global
settings_user
survey_882234
survey_links
survey_url_parameters
surveymenu
surveymenu_entries
surveys
surveys_groups
surveys_groupsettings
surveys_languagesettings
template_configuration
templates
tutorial_entries
tutorial_entry_relation
tutorials
user_groups
user_in_groups
user_in_permissionrole
users

====question_themes====

Columns:

{|class="wikitable stripe"
! Name || Type || Null || Key || Default || Extra || Description
|-
| id || int(11) || NO || PRI || NULL || auto_increment ||
|-
| name || varchar(150) || NO || MUL || NULL || ||
|-
| visible || varchar(1) || YES || || NULL || ||
|-
| xml_path || varchar(255) || YES || || NULL || ||
|-
| image_path || varchar(255) || YES || || NULL || ||
|-
| title || varchar(100) || NO || || NULL || ||
|-
| creation_date || datetime || YES || || NULL || ||
|-
| author || varchar(150) || YES || || NULL || ||
|-
| author_email || varchar(255) || YES || || NULL || ||
|-
| author_url || varchar(255) || YES || || NULL || ||
|-
| copyright || text || YES || || NULL || ||
|-
| license || text || YES || || NULL || ||
|-
| version || varchar(45) || YES || || NULL || ||
|-
| api_version || varchar(45) || NO || || NULL || ||
|-
| description || text || YES || || NULL || ||
|-
| last_update || datetime || YES || || NULL || ||
|-
| owner_id || int(11) || YES || || NULL || ||
|-
| theme_type || varchar(150) || YES || || NULL || ||
|-
| question_type || varchar(150) || NO || || NULL || ||
|-
| core_theme || tinyint(1) || YES || || NULL || ||
|-
| extends || varchar(150) || YES || || NULL || ||
|-
| group || varchar(150) || YES || || NULL || ||
|-
| settings || text || YES || || NULL || ||
|}

Database documentation

2021-05-19T13:55:09Z

Olle: /* question_themes */

This page contains documentation for all database tables and their functionality.

Without prefix, this is all tables, as of 2021-05-19:

answer_l10ns
answers
archived_table_settings
assessments
asset_version
boxes
conditions
defaultvalue_l10ns
defaultvalues
expression_errors
failed_login_attempts
group_l10ns
groups
label_l10ns
labels
labelsets
map_tutorial_users
notifications
old_survey_882234_20210512154558
old_tokens_882234_20210512154558
participant_attribute
participant_attribute_names
participant_attribute_names_lang
participant_attribute_values
participant_shares
participants
permissions
permissiontemplates
plugin_settings
plugins
question_attributes
question_l10ns
question_themes
questions
quota
quota_languagesettings
quota_members
saved_control
sessions
settings_global
settings_user
survey_882234
survey_links
survey_url_parameters
surveymenu
surveymenu_entries
surveys
surveys_groups
surveys_groupsettings
surveys_languagesettings
template_configuration
templates
tutorial_entries
tutorial_entry_relation
tutorials
user_groups
user_in_groups
user_in_permissionrole
users

====question_themes====

Columns:

{|class="wikitable"
! Name || Type || Null || Key || Default || Extra || Description
|-
| id || int(11) || NO || PRI || NULL || auto_increment ||
|-
| name || varchar(150) || NO || MUL || NULL || ||
|-
| visible || varchar(1) || YES || || NULL || ||
|-
| xml_path || varchar(255) || YES || || NULL || ||
|-
| image_path || varchar(255) || YES || || NULL || ||
|-
| title || varchar(100) || NO || || NULL || ||
|-
| creation_date || datetime || YES || || NULL || ||
|-
| author || varchar(150) || YES || || NULL || ||
|-
| author_email || varchar(255) || YES || || NULL || ||
|-
| author_url || varchar(255) || YES || || NULL || ||
|-
| copyright || text || YES || || NULL || ||
|-
| license || text || YES || || NULL || ||
|-
| version || varchar(45) || YES || || NULL || ||
|-
| api_version || varchar(45) || NO || || NULL || ||
|-
| description || text || YES || || NULL || ||
|-
| last_update || datetime || YES || || NULL || ||
|-
| owner_id || int(11) || YES || || NULL || ||
|-
| theme_type || varchar(150) || YES || || NULL || ||
|-
| question_type || varchar(150) || NO || || NULL || ||
|-
| core_theme || tinyint(1) || YES || || NULL || ||
|-
| extends || varchar(150) || YES || || NULL || ||
|-
| group || varchar(150) || YES || || NULL || ||
|-
| settings || text || YES || || NULL || ||
|}

Database documentation

2021-05-19T13:54:41Z

Olle: /* question_themes */

This page contains documentation for all database tables and their functionality.

Without prefix, this is all tables, as of 2021-05-19:

answer_l10ns
answers
archived_table_settings
assessments
asset_version
boxes
conditions
defaultvalue_l10ns
defaultvalues
expression_errors
failed_login_attempts
group_l10ns
groups
label_l10ns
labels
labelsets
map_tutorial_users
notifications
old_survey_882234_20210512154558
old_tokens_882234_20210512154558
participant_attribute
participant_attribute_names
participant_attribute_names_lang
participant_attribute_values
participant_shares
participants
permissions
permissiontemplates
plugin_settings
plugins
question_attributes
question_l10ns
question_themes
questions
quota
quota_languagesettings
quota_members
saved_control
sessions
settings_global
settings_user
survey_882234
survey_links
survey_url_parameters
surveymenu
surveymenu_entries
surveys
surveys_groups
surveys_groupsettings
surveys_languagesettings
template_configuration
templates
tutorial_entries
tutorial_entry_relation
tutorials
user_groups
user_in_groups
user_in_permissionrole
users

====question_themes====

Columns:
{|class="wikitable"
! Name | Type | Null | Key | Default | Extra | Description
|-
| id || int(11) || NO || PRI || NULL || auto_increment ||
|-
| name || varchar(150) || NO || MUL || NULL || ||
|-
| visible || varchar(1) || YES || || NULL || ||
|-
| xml_path || varchar(255) || YES || || NULL || ||
|-
| image_path || varchar(255) || YES || || NULL || ||
|-
| title || varchar(100) || NO || || NULL || ||
|-
| creation_date || datetime || YES || || NULL || ||
|-
| author || varchar(150) || YES || || NULL || ||
|-
| author_email || varchar(255) || YES || || NULL || ||
|-
| author_url || varchar(255) || YES || || NULL || ||
|-
| copyright || text || YES || || NULL || ||
|-
| license || text || YES || || NULL || ||
|-
| version || varchar(45) || YES || || NULL || ||
|-
| api_version || varchar(45) || NO || || NULL || ||
|-
| description || text || YES || || NULL || ||
|-
| last_update || datetime || YES || || NULL || ||
|-
| owner_id || int(11) || YES || || NULL || ||
|-
| theme_type || varchar(150) || YES || || NULL || ||
|-
| question_type || varchar(150) || NO || || NULL || ||
|-
| core_theme || tinyint(1) || YES || || NULL || ||
|-
| extends || varchar(150) || YES || || NULL || ||
|-
| group || varchar(150) || YES || || NULL || ||
|-
| settings || text || YES || || NULL || ||
|}

Database documentation

2021-05-19T13:51:22Z

Olle:

This page contains documentation for all database tables and their functionality.

Without prefix, this is all tables, as of 2021-05-19:

answer_l10ns
answers
archived_table_settings
assessments
asset_version
boxes
conditions
defaultvalue_l10ns
defaultvalues
expression_errors
failed_login_attempts
group_l10ns
groups
label_l10ns
labels
labelsets
map_tutorial_users
notifications
old_survey_882234_20210512154558
old_tokens_882234_20210512154558
participant_attribute
participant_attribute_names
participant_attribute_names_lang
participant_attribute_values
participant_shares
participants
permissions
permissiontemplates
plugin_settings
plugins
question_attributes
question_l10ns
question_themes
questions
quota
quota_languagesettings
quota_members
saved_control
sessions
settings_global
settings_user
survey_882234
survey_links
survey_url_parameters
surveymenu
surveymenu_entries
surveys
surveys_groups
surveys_groupsettings
surveys_languagesettings
template_configuration
templates
tutorial_entries
tutorial_entry_relation
tutorials
user_groups
user_in_groups
user_in_permissionrole
users

====question_themes====

Columns:

{| class="wikitable"
! Name ! Type ! Null ! Key ! Default ! Extra ! Description
|-
| id | int(11) | NO | PRI | NULL | auto_increment |
|-
| name | varchar(150) | NO | MUL | NULL | |
|-
| visible | varchar(1) | YES | | NULL | |
|-
| xml_path | varchar(255) | YES | | NULL | |
|-
| image_path | varchar(255) | YES | | NULL | |
|-
| title | varchar(100) | NO | | NULL | |
|-
| creation_date | datetime | YES | | NULL | |
|-
| author | varchar(150) | YES | | NULL | |
|-
| author_email | varchar(255) | YES | | NULL | |
|-
| author_url | varchar(255) | YES | | NULL | |
|-
| copyright | text | YES | | NULL | |
|-
| license | text | YES | | NULL | |
|-
| version | varchar(45) | YES | | NULL | |
|-
| api_version | varchar(45) | NO | | NULL | |
|-
| description | text | YES | | NULL | |
|-
| last_update | datetime | YES | | NULL | |
|-
| owner_id | int(11) | YES | | NULL | |
|-
| theme_type | varchar(150) | YES | | NULL | |
|-
| question_type | varchar(150) | NO | | NULL | |
|-
| core_theme | tinyint(1) | YES | | NULL | |
|-
| extends | varchar(150) | YES | | NULL | |
|-
| group | varchar(150) | YES | | NULL | |
|-
| settings | text | YES | | NULL | |
|}

Database documentation

2021-05-19T13:50:34Z

Olle:

This page contains documentation for all database tables and their functionality.

Without prefix, this is all tables, as of 2021-05-19:

answer_l10ns
answers
archived_table_settings
assessments
asset_version
boxes
conditions
defaultvalue_l10ns
defaultvalues
expression_errors
failed_login_attempts
group_l10ns
groups
label_l10ns
labels
labelsets
map_tutorial_users
notifications
old_survey_882234_20210512154558
old_tokens_882234_20210512154558
participant_attribute
participant_attribute_names
participant_attribute_names_lang
participant_attribute_values
participant_shares
participants
permissions
permissiontemplates
plugin_settings
plugins
question_attributes
question_l10ns
question_themes
questions
quota
quota_languagesettings
quota_members
saved_control
sessions
settings_global
settings_user
survey_882234
survey_links
survey_url_parameters
surveymenu
surveymenu_entries
surveys
surveys_groups
surveys_groupsettings
surveys_languagesettings
template_configuration
templates
tutorial_entries
tutorial_entry_relation
tutorials
user_groups
user_in_groups
user_in_permissionrole
users

'''question_themes'''

Columns:

{| class="wikitable"
! Name ! Type ! Null ! Key ! Default ! Extra ! Description
|-
| id | int(11) | NO | PRI | NULL | auto_increment |
|-
| name | varchar(150) | NO | MUL | NULL | |
|-
| visible | varchar(1) | YES | | NULL | |
|-
| xml_path | varchar(255) | YES | | NULL | |
|-
| image_path | varchar(255) | YES | | NULL | |
|-
| title | varchar(100) | NO | | NULL | |
|-
| creation_date | datetime | YES | | NULL | |
|-
| author | varchar(150) | YES | | NULL | |
|-
| author_email | varchar(255) | YES | | NULL | |
|-
| author_url | varchar(255) | YES | | NULL | |
|-
| copyright | text | YES | | NULL | |
|-
| license | text | YES | | NULL | |
|-
| version | varchar(45) | YES | | NULL | |
|-
| api_version | varchar(45) | NO | | NULL | |
|-
| description | text | YES | | NULL | |
|-
| last_update | datetime | YES | | NULL | |
|-
| owner_id | int(11) | YES | | NULL | |
|-
| theme_type | varchar(150) | YES | | NULL | |
|-
| question_type | varchar(150) | NO | | NULL | |
|-
| core_theme | tinyint(1) | YES | | NULL | |
|-
| extends | varchar(150) | YES | | NULL | |
|-
| group | varchar(150) | YES | | NULL | |
|-
| settings | text | YES | | NULL | |
|}

Database documentation

2021-05-19T13:49:22Z

Olle:

This page contains documentation for all database tables and their functionality.

Without prefix, this is all tables, as of 2021-05-19:

answer_l10ns
answers
archived_table_settings
assessments
asset_version
boxes
conditions
defaultvalue_l10ns
defaultvalues
expression_errors
failed_login_attempts
group_l10ns
groups
label_l10ns
labels
labelsets
map_tutorial_users
notifications
old_survey_882234_20210512154558
old_tokens_882234_20210512154558
participant_attribute
participant_attribute_names
participant_attribute_names_lang
participant_attribute_values
participant_shares
participants
permissions
permissiontemplates
plugin_settings
plugins
question_attributes
question_l10ns
question_themes
questions
quota
quota_languagesettings
quota_members
saved_control
sessions
settings_global
settings_user
survey_882234
survey_links
survey_url_parameters
surveymenu
surveymenu_entries
surveys
surveys_groups
surveys_groupsettings
surveys_languagesettings
template_configuration
templates
tutorial_entries
tutorial_entry_relation
tutorials
user_groups
user_in_groups
user_in_permissionrole
users

'''question_themes'''

Columns:

{| class="wikitable"
! Name ! Type ! Null ! Key ! Default ! Extra ! Description
|-
| id | int(11) | NO | PRI | NULL | auto_increment |
|-
| name | varchar(150) | NO | MUL | NULL | |
|-
| visible | varchar(1) | YES | | NULL | |
| xml_path | varchar(255) | YES | | NULL | |
| image_path | varchar(255) | YES | | NULL | |
| title | varchar(100) | NO | | NULL | |
| creation_date | datetime | YES | | NULL | |
| author | varchar(150) | YES | | NULL | |
| author_email | varchar(255) | YES | | NULL | |
| author_url | varchar(255) | YES | | NULL | |
| copyright | text | YES | | NULL | |
| license | text | YES | | NULL | |
| version | varchar(45) | YES | | NULL | |
| api_version | varchar(45) | NO | | NULL | |
| description | text | YES | | NULL | |
| last_update | datetime | YES | | NULL | |
| owner_id | int(11) | YES | | NULL | |
| theme_type | varchar(150) | YES | | NULL | |
| question_type | varchar(150) | NO | | NULL | |
| core_theme | tinyint(1) | YES | | NULL | |
| extends | varchar(150) | YES | | NULL | |
| group | varchar(150) | YES | | NULL | |
| settings | text | YES | | NULL | |

Database documentation

2021-05-19T13:42:48Z

Olle:

Database documentation

2021-05-19T13:42:20Z

Olle: Created page with "This page contains documentation for all database tables and their functionality. Without prefix, this is all tables, as of 2021-05-19: answer_l10ns ans..."

Development overview

2021-05-19T13:40:33Z

Olle:

Table of contents:

*[[LimeSurvey roadmap]]
*[[How to join the LimeSurvey project team]]
**[[How to become a LimeSurvey Developer]]
*[[Accessing the source code]]
**[[Switch from Subversion to Git]]
*[[Coding guidelines]]
*[[How to document your source code]]
*[[Standard for Git commit messages]]
*[[Help us: Tasks]]
*[[How can I support LimeSurvey?]]
*[[How to contribute new features]]
*[[Database versioning]]
*[[Database documentation]]
*[[The bugtracker and git]]
*[[Plugin system architecture]]
**[[Authentication plugin development]]
**[[Question plugins]]
***[[Creating a question plugin]]
****[[Question signature]]
**[[Defining attributes]]
*[[HTML editor : needed functionality]]
**[[Update ckeditor]]
**[[redactor]]
**[[summernote]]
**[[tinyMCE]]
*[[VueJS]]
*[[Replace_jqGrid]]
*[[Accessibity]]
*[[Templating]]
*[[Regression and unit tests]]
*[[Survey settings inheritance]]
[[Category:Development]]

Code quality guide

2021-05-19T10:20:13Z

Olle: /* Modules */

DRAFT

== Prologue ==

# '''Be risk aware'''. Too good code can be a business risk (slow to write, maybe over-designed). Too sloppy code can also be a business risk (hard to maintain and understand). You have to find a balance that is adapted to the current situation and risk analysis, in which code quality becomes a '''risk mitigation''' technique among others.
# '''Be humble'''. LimeSurvey was made by developers from all over the world, with different age, education and experience. Your code might be read by a completely different team ten years from now, in the same way you are now reading code by developers that no longer work with us, but which work pays our rent.
# '''Performance matters sometimes''', and shouldn't be disregarded completely. In particular, database queries using the ORM and ActiveRecord can be problematic. Some surveys have thousands of questions and hundreds of thousands of responses. Fast response time is also important for a fluid user experience.
# '''It's harder to read code than to write code'''. Don't choose patterns that are easy or fast to write, but that are easy to read.
# Make your code '''communicate intent'''.
# It's easy to forget '''cross-cutting concerns''' like translation and security. Keep a mental note.
# '''Stress affects code quality''' and your risk behaviour. If your stress level is too high to write code with proper quality, take a step back and discuss it with your boss, or you'll push problems to the future.

== Quality ==

The purpose of this guide is to increase the quality of the LimeSurvey code-base. What is quality? Which aspects of quality can be measured? Which kind of company culture gives rise to appropriate code quality?

It's usually easier to get along what is "bad" code than what's "best" code. Blacklist instead of whitelist?

Quality attributes related to code quality:

* Readability
* Testability
* Maintainability
* Performance
* Security
* Reliability

Can not increase all at the same time - performance vs readability.

It's better to avoid emotional language when describing code quality, like "clean" or "dirty". Be precise, objective and suggest solutions.

Idiomatic code is more readable than non-idiomatic code. What's idiomatic depends on which context or domain you work in. We work in PHP and web application development, and have other idioms than in, say, functional or hardware-close programming.

Some code are "hot spots" - changed often. Those parts should require higher quality than other code.

== Risk ==

todo

Why a risk-based approach? Waterfall vs agile, code driven.

Couple of different definition of risk:

* Tuple of probability and severity
* Triple of consequence, uncertainty and knowledge base

Ambiguity vs uncertainty.

Possible risks related to LimeSurvey (technical or business):

* Data loss
* Regressions
* Bad UI (higher churn-rate for users)
* Hard to maintain (reduced sprint velocity)
*

How know which is the biggest risk? How many risks can be approached at once?

Connection to architecture. Risk --> quality attributes --> architectural decisions.

usability a business risk - hard to use or understand, people will choose another tool

risks relevant when fixing bugs

risks relevant when adding new features (lack of testing, wrong requirements, scope creep)

risks relevant when refactoring (regressions)

unit tests and QA as risk mitigation

partial deployment, alpha/beta/rc, risk communication

software rot, design pattern rot/grime, software evolution

rot = non-pattern related code

testing by community, bug fixing by community

risk based on knowledge, evidence, P(A|K)

== Modules ==

There's no inherit module functionality in PHP, but Yii has a module system. Libraries can be seen as a module system.

Examples of implicit modules in LimeSurvey:

* Front-end (survey taking)
* Back-end (survey design)
* Back-end (non-survey specific pages, like label sets, CPDB)
* Survey theme editing
* Expression manager
* Plugin system

In the future, they need to be separated and implemented more clearly as whatever Yii 3 module system is in use.

Some data models are common for all modules, e.g. surveys and users. Can have a "Common" module for such data.

todo, relation to Yii config system

== Classes ==

* Avoid empty OOP ceremony, like defining getters and setters for all properties. Might as well make them public, ''unless'' they have invariants that need to be upheld, e.g. "this number is always between 1 and 10" or "this string is maximum length 20".
* Almost always avoid static methods. They cannot be mocked. One exception is (possibly) factory methods (Foo::make(...)).
* Inject all dependencies. This will make sure the class can be unit-tested (unit-tests have several benefits over integrity tests - they can be run in parallel and don't require any setup and teardown)
* A second way to achieve testability is to factor out the methods that access the dependencies

todo, state vs behaviour, state vs dependencies

=== OOP design ===

Start from top-down, with domain, behaviour, interaction between objects, database design, pseudo-code if needed. Can also include scenarios, use-cases and UML diagrams.

Object reification - not only domain models, but also domain actions, relations and activities can be objects, e.g. a class ActivateSurvey or ExportSurvey.

Hierarchy depth should be kept reasonable shallow to avoid conflicts between methods, spooky action at a distance. Compare with Yii 3, where controllers no longer inherit anything.

Some people advocate for composition instead of inheritance. Lots of blog posts available for more info.

Multiple inheritance is done with traits in PHP. Use-case: ActiveRecords where some but not all models support encryption.

==== Shape design problem ====

Imagine you have three shapes: Point, rectangle and circle, with the following properties:

* Point: int x, int y
* Rectangle: Point bottomLeft, Point topRight
* Circle: Point center, int radius

Add two behaviours: area(), draw(surface).

* Cohesion: A class (or module) should be responsible for one thing only
* Coupling: You should be able to ''isolate change'' in the system
* Encapsulation: Classes shouldn’t share internal representation
* Polymorphism: The design should be based on interfaces

Questions to consider:

* How easy would it be to move to a 3D representation?
* How easy would it be to add a new shape, say, triangle?
* How easy would it be to add a new behaviour to all shapes, like save/load from a SQL database?
* Which classes ''change together''?

Keep polymorphism and encapsulation - all properties are private.

Example pseudo-code:

forall shapes as shape, do shape.draw(surface)

forall shapes as shape, do surface.draw(shape) (where shape.getDrawData(), or shape.getPath())

=== Software evolution ===

Design rot after time - how to keep it tight? (Grime.)

Architecture design roundtrip, based on risk.

todo

==== Grime and rot ====

design pattern rot --> lose behaviour relevant for pattern (active record without db connection)

design patter grime --> add behaviour irrelevant for pattern (active record that's also a singleton)

==== Class cohesion ====

[[File:cohesion.png]]

==== Modular coupling ====

[[File:coupling.png]]

Clearer boundaries between classes and modules make it easier to isolate change.

=== State ===

Heuristics to consider but not follow slavishly.

Keep a clear separation between classes with state and classes with no state.

Classes with state should not have dependencies with IO (it's OK to depend on classes in the same application layer, e.g. other DTO classes), and vice versa. ActiveRecord is an example which violates this principle.

class Survey
// Confusion - first params are domain state, last a resource
__construct(id, language, dbConnection)

If a method does not call "this", should it instead be outside the class? A separate class or function, maybe.

todo, elaborate

=== Types of classes ===

Different categories of classes:

* Entity (domain class; has state and validation behaviour)
* Resource (database connection, file, curl, logger; state is in the resource (open, closed))
* Repository classes (database interaction, like splitting ActiveRecord in two parts: Entity class and database interaction)
* DAO, data access object (similar to resource)
* Builders (e.g. query builder, HTML message builder)
* Data-transfer object (no behaviour; pass to views to have better documentation and intent than associative arrays)
* Value classes (e.g. Email address to wrap email string around)
* Command object (e.g. SurveyActivator)
* Helper (no state; e.g. QuestionAttributeHelper to bake attributes into different formats used by the views)
* Wrapper

todo, immutability, possible with private properties that are set in the constructor,

todo: command-query separation for classes?

todo: dependencies between layers, dependencies to the framework

todo, pure vs effectful classes

=== Types of classes in LimeSurvey ===

* ActiveRecord, used to communicate with the database, and should not do ''anything'' else
* Controllers, used for glue code; should not contain business-logic (also CLI controllers)
* Helper functions (not classes, yet...), should be short and obey command-query separation (TODO: Long functions should be separated into command objects or service classes); todo: should not have any dependencies?
* Helper classes, similar to helper functions but have dependencies that need to be mocked during tests; should not have any state
* Service classes, contains logic related to a clear and separate task, like create or import survey
* Question render classes, contains logic related to how questions are rendered (TODO: Need better separation between state and logic and more clear design); similar to widgets
* Plugin classes, using the plugin event system
* Widgets, containing HTML logic for custom HTML widgets
* HTML helpers (Yii)
* Customizations to the Yii framework by inheritance
* Unit and functional test classes

A couple of classes contain only data, like LsDefaultDataSet.

todo, no difference between state property and dependency property in OOP

=== What is "glue code"? ===

todo

Putting the pieces together, e.g. service class A need data from model B, fetch it and run.

todo, add example

=== "Where do I cut?" ===

Separation of concerns, but which concerns and which type of separation? Command-query (function core, imperative shell) is one type of separation. Other separation between layers, e.g. logic layer and data persistency layer (similar in thought).

Other separation, that one class should have a clear purpose. A design pattern should only implement ''one'' pattern, not multiple, and not half a pattern.

There's a problem with "helper" or "manager" classes that they can grow indefinitely, but might be better than nothing. Example when moving business logic out of ActiveRecord class to a helper class it can sometimes hard to be more specific than "helper".

=== Size ===

A class should have a single and clear purpose; compare with [https://en.wikipedia.org/wiki/SOLID SOLID].

=== Class name ===

* ActiveRecord classes are named after the database table they are bound to, but with singular instead of plural. E.g. table "lime_users" have model "User".
* Command classes are named after what they ''do'' and imperatively, e.g. CreateSurvey
* Helper classes should probably be named as specific as possible when possible, to avoid them from growing too big
* Follow the naming tradition of the framework with regard to controllers, e.g. UserController or UserAdministrationController.
* Class properties of ActiveRecord classes will follow the naming of the database, using underscore instead of camel case (and ActiveRecord classes should have ''no'' other properties than those (excluding the database connection injected by the framework))

== Functions ==

Functions are one of the fundamental building blocks of programming, so it's important to get it right.

Functions that are part of a class are called "methods", if you want to be formal.

Different types of functions in PHP:

* Functions (not attached to a class)
* Methods (attached to class)
* Anonymous functions (does not capture scope automatically)
* Short functions (does capture scope automatically)

I'm using "function" as a word for all types of functions in PHP below.

<hr>

=== Size ===

* A function should be short enough to be completely readable on one screen, approx 60 lines at most
* A function should not have too many arguments; if you have five or more, consider making it a class instead
* If a function is growing too big, it might be better to create a class instead or split it into several functions (if both functions have '''common state''', a class might be better, unless you want to pass around '''explicit state''')

=== Contract ===

* A function has a contract with its surrounding environment:
** Pre-condition: What needs to be true before the function is executed
** Post-condition: What will be true after the function has returned
* The function contract can be checked with assertions (internal invariants) or exceptions (outside world); see below
* Another good way is to use unit-tests to make sure the function's contract remains stable through changes
* The first line in the docblock should be one sentence describing the relation between function arguments and its output<br>Example<br><syntaxhighlight lang="php">
/**
* Creates a random password of length $length (defaults to 12)
* @param int $length
* @return string
*/
function createPassword($lenght = 12)

/**
* Creates an HTML language drop down for survey with id $surveyId, marking $selectedLanguage as selected
* @param int $surveyId
* @param string $selectedLanguage
* @return string <select> HTML
*/
function createLanguageDropdown($surveyId, $selectedLanguage)

</syntaxhighlight>

=== Push side-effects up in the stack trace ===

This one is a bit abstract.

First, what is a '''side-effect'''? In short, it's anything that happens in a function that ''is not'' described by the ''relation'' between function arguments and output.

Another way to phrase it is, that a side-effect is anything that is not always the same for the given input to a function; a function without any side-effects will always return the same result if it gets the same input.

'''Examples:'''

<syntaxhighlight lang="php">
// gT accesses the file system and will return different result depending on what's in the translation files
function gT($sToTranslate, $sEscapeMode = 'html', $sLanguage = null);

// If $sText and $sEscapeMode is always the same, quoteText() will always return the same string.
function quoteText($sText, $sEscapeMode = 'html');
</syntaxhighlight>

A function with no side-effects is called '''pure'''. A function that is guaranteed to always return (no exceptions, no errors, no warnings, no division by zero) is called '''total'''.

It's a good thing if functions in a code-base ''either'' have side-effects, ''or'' return a result. Not both. This is called [https://en.wikipedia.org/wiki/Command%E2%80%93query_separation command-query separation].

Examples of side-effects:

* Database or file access
* Echo, or write to stdout or stderr
* Randomization

Why does this matter? Because side-effects make testing harder! '''If you have side-effects, you cannot create unit tests''', ''unless'' those side-effects can be mocked. If not, you need integrity tests with database setup or more. The more side-effects you have in a function, the more mocking is required to unit test it.

So, one solution to this is to move side-effects higher up in the stack trace, that is, move them to the calling code.

'''Example:'''

<syntaxhighlight lang="php">
function getSurveyInfo(int $surveyid, string $languagecode = '', boolean $force = false): array;
</syntaxhighlight>

Since this function takes $surveyid, we know it will probably query the database. Quering the database is a side-effect, and thus it requires a database scaffold for the test (or mocking, but the database connection is not injected, so there's no way to do it). One simple solution is to lift the side-effect out and pass in a Survey object instead:

<syntaxhighlight lang="php">
function getSurveyInfo(Survey $survey, string $languagecode = '', boolean $force = false): array;
</syntaxhighlight>

Much better! The side-effect of calling the database now happens ''before'' the function call. Now we can either mock a Survey object, or make an imitating stub for our test.

Reading the function body, there is in fact another database access, but since this is a relation to the Survey model, it could easily be moved out too. We've just made a function testable! Hooray!

This principle is rephrased in an architectural settings as [https://github.com/kbilsted/Functional-core-imperative-shell/blob/master/README.md functional core, imperative shell]. This architecture helps you get a good ratio between fast unit tests and slower integrity tests.

Moving side-effects up makes sure we can have a healthy ratio between integrity tests with scripted browser, and unit-tests; maybe around 20-80.

=== Function name ===

* The function name should tell you '''what''' it does; docs should tell you '''why''' (if this information is not obvious). '''How''' is described by the code itself (hopefully, but can in some cases be relevant to document).
* Function name can often be '''verb [+ adjective] + noun''', like "createFieldmap", "quoteText", "getRelativePath"
* Prefix with "is" for boolean functions

todo: difference between create, get, fetch, generate, ...

'''Good examples:'''

* createPassword() - One verb, one noun - clear
* isCaptchaEnabled() - Using "is" signifies it returns boolean; clear purpose
* getFullResponseTable() - Verb, adjective, noun - but is "full" needed here? Is there a non-full version of the same function?
* replaceExpressionCodes() - Pretty good, but it's obvious that more information is needed in the docblock to describe what "replace" means, and what an "expression code" is
* fixCKeditorText() - "fix" is a bit vague, but maybe best there is? Pray that docblock contains information!

'''Bad examples:'''

* languageDropdown() - No verb, doesn't tell you what it does
* rmdirr() - Two r's, looks like a typo, but the last "r" actually means "recursive"! Better: rmdir($recursive = false), rmdir or removeFolder.
* CSVUnquote() - Is CSV really the namespace? Why is the verb the second word?
* incompleteAnsFilterState() - One verb, but in the middle, or is "filter state" a noun?; why abbreviate "answer" to "ans"?
* reverseTranslateFieldNames() - Two verbs - did author mean "reverseTranslatedFieldNames"? Or "reverse and translate"? If so, it should be two functions, one for reverse and one for translate
* checkUploadedFileSizeAndRenderJson() - If you have an "and" in the function name, you should consider splitting it into two functions

'''Controversial'''

* gT() - An exception to descriptive function names; since this is used everywhere, the minimal name is motivated; maybe even name it "t()"? Still hard to read for someone who just started? But Yii uses t() too? Other frameworks use double underscore (Wordpress, Laravel) as function name.

<hr>

=== Function filename and namespace ===

If your function has dependencies or side-effects, it should be put into a class instead, in which the dependencies can be injected. Another alternative is to put the dependencies as argument in the function, although this muffles the relationship between input and output. Again, this is to increase testability.

Keep in mind that functions outside classes cannot be mocked, so only use them when you ''know'' you won't need to mock them.

todo, autoloading of functions and folder location

=== Assertions ===

NB: This is not assertions as used in unit-tests, but assertions as used to check invariants in production code.

Assertions can be used for mental checks. They are only used for internal logic - failed assertions are not supposed to be seen by the end user. For interaction with the outside world, like database or browser, exceptions should be used instead.

Assertions can be disabled in production mode and have then no runtime cost (since PHP 7).

'''Example:'''

<syntaxhighlight lang="php">
/**
* Translation helper function
*
* @param string $sToTranslate
* @param string $sEscapeMode Valid values are html (this is the default, js and unescaped)
* @param string $sLanguage
* @return string
*/
function gT($sToTranslate, $sEscapeMode = 'html', $sLanguage = null)
{
assert(is_string($sToTranslate));
assert(strlen($sToTranslate) > 0);
assert($sEscapeMode === 'html' || $sEscapeMode === 'js' || $sEscapeMode === 'unescaped');
return quoteText(Yii::t('', $sToTranslate, array(), null, $sLanguage), $sEscapeMode);
}
</syntaxhighlight>

<hr>

=== Exceptions ===

* Exceptions are used to check inputs from the outside world (browser, database, file system)
* Don't use exceptions for control flow, only when fatal errors happen that make further execution impossible
* Exceptions should have clear error messages that make them ''actionable'' - there should be a clear "next step" for the user or developer
* Never, ever, do an empty catch-block
* At the moment, we do not have an exception hierarchy in LimeSurvey

==== Alternatives to exceptions ====

Some people consider exceptions being a hidden form of "goto" which confuses the control flow of the program. They propose different other solutions:

* Return a tuple, like <code>[$result, $errorMessage]</code> where $errorMessage is null at success
* Return <code>null</code> at failure
* Tagged union result type (not yet possible in latest PHP)
* Result object

The con being that you have to manually propagate the error, where an exception can happen from anywhere in the stack trace without any other function knowing about it.

=== If-statements ===

If-statements should not be too long or hard to understand. If they are, consider factor out the checks into separate functions.

<syntaxhighlight lang="php">
if ((empty($instance->oOptions->{$attribute}))
|| (
!empty($instance->oOptions->{$attribute})
&& (
$instance->oOptions->{$attribute} === 'inherit'
|| $instance->oOptions->{$attribute} === 'I'
// NB: Do NOT use === here, it won't work with Postgresql.
|| $instance->oOptions->{$attribute} == '-1'
)
)
) {
</syntaxhighlight>

Can be shortened by factoring out method <code>isInherit</code>:

<syntaxhighlight lang="php">
if (empty($instance->options->{$attribute})
|| $this->isInherit($instance-options->{$attribute})) {
}
/**
* Returns true if $value is set to inherit
* @param mixed|null $value
* @return boolean
*/
public function isInherit($value) {
return !empty($value)
&& (
$value === 'inherit'
|| $value === 'I'
// NB: Do NOT use === here, it won't work with Postgresql.
|| $value == '-1'
);
}
</syntaxhighlight>

And one more time by using a variable for the value:

<syntaxhighlight lang="php">
$value = $instance->options->{$attribute};
if (empty($value) || $this->isInherit($value)) {
}
</syntaxhighlight>

More clear, right? "If it's empty or set to inherit, do this and that."

=== Variables ===

Descriptive naming.

* Follow PSR-12 - no underscore, use camelCaseLikeThis
* Variables of ActiveRecord classes can have same name as the class, like "$survey" or "$question"
* Add -s for plural when it's a list of items: "$surveys", "$questions"
* Never include "array" or "list" in variable names - using plural is enough (for lists, not for associative arrays - see below)
* The ''context'' of the function helps with variable naming, e..g "$name" might be fine in a function about questions; this is extra helpful when functions are short!
* When a function is short, it's much easier to figure out variable meaning based on context
* $qid, $gid, and $sid are so established in the code-base that they could be considered OK
* The -data suffix means "blob of stuff", only use it when needed, like with $viewData
* Use $result when baking a return value; add its exact type as @var annotation (worst possible name, acceptable but anything with more meaning is better)

Not so good:

<syntaxhighlight lang="php">
$result = LabelSet::model()->findAll();
</syntaxhighlight>

Better with model name and -s for plural:

<syntaxhighlight lang="php">
$labelSets = LabelSet::model()->findAll();
</syntaxhighlight>

* Do not use Hungarian notation (prefix with "type"), but instead <code>/** @var */</code> annotations - these can be checked automatically and will then be enforced to be correct, unlike Hungarian notation which can "rot"

<syntaxhighlight lang="php">
/** string[] An array of strings with 0-n elements */
$allFields = [];
</syntaxhighlight>

Psalm can infer types if the function documentation is enough. The strictness can be adjusted. Not all variables will need @var annotation, the tool will warn you when it's confused.

* Data that is sent to views as associative arrays will be:

<syntaxhighlight lang="php">
/** @var array Can be basically anything :( Better would be data-transfer objects or more precise notation */
$data = [];
// Maybe more clear as $viewData? Discuss.
</syntaxhighlight>

You can be more precise when you specify which type of array you're writing:

<syntaxhighlight lang="php">
/** @var array<string, string> This means the array key is string, and the array value is also string */
$data = [];
$data['name'] = 'Olle';
$data['occupation'] = 'Developer';
$data['age'] = 38; // ERROR! Value must be string.
</syntaxhighlight>

For more info about array type notation, see the [https://psalm.dev/docs/annotating_code/type_syntax/array_types/ Psalm documentation].

Some smaller examples:

<syntaxhighlight lang="php">
$theme = App()->request->getPost('theme'); // Should be $themeType - $theme looks like a model/AR
$gridid === 'questionthemes-grid'; // Should be $gridId with capital "I", since it's two words in English
$delete = Yii::app()->request->getParam('delete'); // Tuff one - $delete is ok? Thoughts?
$files = json_decode(stripslashes($sJSON), true); // $file is a resource, $files an array of resources, this is $fileData perhaps?
$valid_extensions_array = explode(",", $aAttributes['allowed_filetypes']); // Should be $validExtensionTypes
$language = Yii::app()->session['survey_' . $surveyid]['s_lang']; // TODO: Should this be a value class? Then Language::make(...);
$surveyInfo = getSurveyInfo($surveyId, $language); // OK, BUT should be a separate DTO!
$fieldMap = createFieldMap($survey, 'short', false, false, $language); // Same, make a DTO
$cquestions = array(); // What's "c"? Method name is getChildQuestions and $questions is an argument - better with $childQuestions?
</syntaxhighlight>

Links:

[https://www.approxion.com/capital-offenses-how-to-handle-abbreviations-in-camelcase/ How to Handle Abbreviations in CamelCase]

[https://stackoverflow.com/questions/15526107/acronyms-in-camelcase Acronyms in CamelCase]

=== Looping ===

* The bodies of foreach-loops are often a good candidate to factor out into separate functions.

'''Example:'''

<syntaxhighlight lang="php">
foreach ($questions as $question) {
processQuestion($question);
}
</syntaxhighlight>

Note the variable naming from plural to singular.

* Loop indexing should be named i, j, k etc.

'''Example:'''

<syntaxhighlight lang="php">
for ($i = 0; $i < $length; $i++) {
for ($j = 0; $j < $otherLength; $j++) {
// ...
}
}
</syntaxhighlight>

<hr>

=== Function composition ===

todo, "doThisAndThat" --> "doThis(doThat())"

=== Cases ===

<syntaxhighlight lang="php">
/**
* This function generates an array containing the fieldcode, and matching data in the same order as the activate script
*
* @param Survey $survey Survey ActiveRecord model
* @param string $style 'short' (default) or 'full' - full creates extra information like default values
* @param boolean $force_refresh - Forces to really refresh the array, not just take the session copy
* @param bool|int $questionid Limit to a certain qid only (for question preview) - default is false
* @param string $sLanguage The language to use
* @param array $aDuplicateQIDs
* @return array
*/
function createFieldMap($survey, $style = 'short', $force_refresh = false, $questionid = false, $sLanguage = '', &$aDuplicateQIDs = array())
</syntaxhighlight>

'''Good:'''

* Name is verb and noun
* Each argument is documented (almost)

'''Bad:'''

* Returns "array", which can be anything. A separate class for "Fieldmap" would be better.
* Not clear if it should be "createFieldMap" or "createFieldmap" - is "fieldmap" one word or two?
* Very many boolean arguments. Should probably be a class with methods like <code>$fieldmapCreator->setForceRefresh(true);</code> instead.
* Too long.
* Doesn't elaborate on what "fieldmap" really is, and does not link to any documentation about it.
* Access super-global, which makes it hard to test. Should instead return a data-transfer object, like:<br><syntaxhighlight lang="php">
$_SESSION['fieldmap'] = createFieldMap(...);
</syntaxhighlight>
* Has no test
* Mixes Hungarian notation with non-Hungarian notation in the argument list

== Defensive programming and error handling ==

* '''Fail hard, fail early'''. The earlier the program crashes when something is wrong, the lower is the probability that you'll end up with corrupt data in the database that will later require manual labor to correct.
* Fail with '''actionable information'''
* Check input to functions and throw <code>InvalidArgumentException</code> if it violates the function's pre-conditions
* Use assert for class-internal invariants
* Use assert to make assumptions explicit for the reader

== Documentation ==

=== PHPDoc ===

* All functions must have a proper docblock
* The first line of the docblock should describe the relation between ''all'' the input arguments and the output of the function in a single sentence
* Each parameter must have the correct type
* Don't use <code>array</code> as type if it's a list of object - instead, use <code>[]</code> like so: <code>Survey[]</code> for a list of surveys

=== Technical documentation ===

todo, UML, scenarios, use-cases

== The PHP of yesterday ==

Old idioms and habits that should be abandoned.

* Don't use associative arrays, almost never. Data-transfer objects have multiple benefits: they are clearly structured, can be documented, can enforce invariants. There's ''no'' performance overhead of objects compared to arrays in modern PHP.
* Objects are already passed by reference; arrays are value types
* Use <code>[]</code> instead of <code>array()</code>
* Hungarian notation was useful before static analysis existed for PHP. These days it's better to use something that can be checked automatically: docblock @param and inline @var annotations.

== The PHP of tomorrow ==

todo

Union tags

Short functions

Match expressions

Partial application, pipe

== Security ==

todo

XSS

Database injection

Permissions and roles

== Performance ==

todo

Loading too many rows into PHP models

== Testing ==

todo

QA

PHPUnit

TDD

Mocks, can't mock functions, static methods, mocking as a DSL, PHPUnit mocking tools

Pure functions, referential transparency, side-effects

Unit, functional, integration

Don't test the framework; don't test PHP

Makes sure the function or class lives up to its specification; make sure it will ''always'' live up to its specification, even in the future, to avoid regressions.

== Static analysis ==

<code>php -l</code>, CodeSniffer, Mess Detector, Psalm

== Database design ==

todo

== JavaScript ==

todo

classes, functions, components, tests

== CSS ==

todo

== HTML ==

todo

== Feedback ==

=== "Why do I have to refactor code that works?" ===

todo, Sadly, it's not enough for the code to live up to the current specification and requirements, it must also be protected against future changes, regressions. Adding tests is the best way for this. Lots of people might read and change the LimeSurvey code the next 5-10 years. The test suite creates a security layer to make sure the specification is fulfilled even as the code changes.

Tests are not a magical solution, however. It does not protect us against other degradation of the code quality, like classes gaining too much responsibility (too many methods, unrelated methods, too many properties).

=== "What's the correct ratio between integrity tests and unit tests?" ===

todo, Don't know. Different pros and cons.

* Unit-test can be run in parallel and are faster
* Unit-tests don't need setup and teardown

Cons of unit-tests is that they need a bigger effort on the side of the developer to make them possible, for example injecting the dependencies properly to enable mocking, or lifting side-effects up in the stack trace.

=== How to disagree ===

All rules can be broken. To break a rule, you should reason in terms of risk and the assumptions used in this guide.

'''Assumptions:'''

# Regressions are the biggest technical risk for LimeSurvey the last five years (2021)
# Automated tests are the best risk mitigation technique against regressions

'''Possible disagreement:'''

# A certain piece of code has very low ''probability'' of regressions (maybe we "know" no one else will every touch or change it?)
# Regression in a certain piece of code would have very low ''impact''

== Architectural Decision Records ==

todo

https://adr.github.io/

== Resources ==

todo

Books, links, videos

Code quality guide

2021-05-19T10:17:25Z

Olle: /* Risk */

DRAFT

== Prologue ==

# '''Be risk aware'''. Too good code can be a business risk (slow to write, maybe over-designed). Too sloppy code can also be a business risk (hard to maintain and understand). You have to find a balance that is adapted to the current situation and risk analysis, in which code quality becomes a '''risk mitigation''' technique among others.
# '''Be humble'''. LimeSurvey was made by developers from all over the world, with different age, education and experience. Your code might be read by a completely different team ten years from now, in the same way you are now reading code by developers that no longer work with us, but which work pays our rent.
# '''Performance matters sometimes''', and shouldn't be disregarded completely. In particular, database queries using the ORM and ActiveRecord can be problematic. Some surveys have thousands of questions and hundreds of thousands of responses. Fast response time is also important for a fluid user experience.
# '''It's harder to read code than to write code'''. Don't choose patterns that are easy or fast to write, but that are easy to read.
# Make your code '''communicate intent'''.
# It's easy to forget '''cross-cutting concerns''' like translation and security. Keep a mental note.
# '''Stress affects code quality''' and your risk behaviour. If your stress level is too high to write code with proper quality, take a step back and discuss it with your boss, or you'll push problems to the future.

== Quality ==

The purpose of this guide is to increase the quality of the LimeSurvey code-base. What is quality? Which aspects of quality can be measured? Which kind of company culture gives rise to appropriate code quality?

It's usually easier to get along what is "bad" code than what's "best" code. Blacklist instead of whitelist?

Quality attributes related to code quality:

* Readability
* Testability
* Maintainability
* Performance
* Security
* Reliability

Can not increase all at the same time - performance vs readability.

It's better to avoid emotional language when describing code quality, like "clean" or "dirty". Be precise, objective and suggest solutions.

Idiomatic code is more readable than non-idiomatic code. What's idiomatic depends on which context or domain you work in. We work in PHP and web application development, and have other idioms than in, say, functional or hardware-close programming.

Some code are "hot spots" - changed often. Those parts should require higher quality than other code.

== Risk ==

todo

Why a risk-based approach? Waterfall vs agile, code driven.

Couple of different definition of risk:

* Tuple of probability and severity
* Triple of consequence, uncertainty and knowledge base

Ambiguity vs uncertainty.

Possible risks related to LimeSurvey (technical or business):

* Data loss
* Regressions
* Bad UI (higher churn-rate for users)
* Hard to maintain (reduced sprint velocity)
*

How know which is the biggest risk? How many risks can be approached at once?

Connection to architecture. Risk --> quality attributes --> architectural decisions.

usability a business risk - hard to use or understand, people will choose another tool

risks relevant when fixing bugs

risks relevant when adding new features (lack of testing, wrong requirements, scope creep)

risks relevant when refactoring (regressions)

unit tests and QA as risk mitigation

partial deployment, alpha/beta/rc, risk communication

software rot, design pattern rot/grime, software evolution

rot = non-pattern related code

testing by community, bug fixing by community

risk based on knowledge, evidence, P(A|K)

== Modules ==

There's no inherit module functionality in PHP, but Yii has a module system. Libraries can be seen as a module system.

Examples of implicit modules in LimeSurvey:

* Front-end (survey taking)
* Back-end (survey design)
* Survey theme editing
* Expression manager
* Plugin system

In the future, they need to be separated and implemented more clearly as whatever Yii 3 module system is in use.

Some data models are common for all modules, e.g. surveys and users. Can have a "Common" module for such data.

todo, relation to Yii config system

== Classes ==

* Avoid empty OOP ceremony, like defining getters and setters for all properties. Might as well make them public, ''unless'' they have invariants that need to be upheld, e.g. "this number is always between 1 and 10" or "this string is maximum length 20".
* Almost always avoid static methods. They cannot be mocked. One exception is (possibly) factory methods (Foo::make(...)).
* Inject all dependencies. This will make sure the class can be unit-tested (unit-tests have several benefits over integrity tests - they can be run in parallel and don't require any setup and teardown)
* A second way to achieve testability is to factor out the methods that access the dependencies

todo, state vs behaviour, state vs dependencies

=== OOP design ===

Start from top-down, with domain, behaviour, interaction between objects, database design, pseudo-code if needed. Can also include scenarios, use-cases and UML diagrams.

Object reification - not only domain models, but also domain actions, relations and activities can be objects, e.g. a class ActivateSurvey or ExportSurvey.

Hierarchy depth should be kept reasonable shallow to avoid conflicts between methods, spooky action at a distance. Compare with Yii 3, where controllers no longer inherit anything.

Some people advocate for composition instead of inheritance. Lots of blog posts available for more info.

Multiple inheritance is done with traits in PHP. Use-case: ActiveRecords where some but not all models support encryption.

==== Shape design problem ====

Imagine you have three shapes: Point, rectangle and circle, with the following properties:

* Point: int x, int y
* Rectangle: Point bottomLeft, Point topRight
* Circle: Point center, int radius

Add two behaviours: area(), draw(surface).

* Cohesion: A class (or module) should be responsible for one thing only
* Coupling: You should be able to ''isolate change'' in the system
* Encapsulation: Classes shouldn’t share internal representation
* Polymorphism: The design should be based on interfaces

Questions to consider:

* How easy would it be to move to a 3D representation?
* How easy would it be to add a new shape, say, triangle?
* How easy would it be to add a new behaviour to all shapes, like save/load from a SQL database?
* Which classes ''change together''?

Keep polymorphism and encapsulation - all properties are private.

Example pseudo-code:

forall shapes as shape, do shape.draw(surface)

forall shapes as shape, do surface.draw(shape) (where shape.getDrawData(), or shape.getPath())

=== Software evolution ===

Design rot after time - how to keep it tight? (Grime.)

Architecture design roundtrip, based on risk.

todo

==== Grime and rot ====

design pattern rot --> lose behaviour relevant for pattern (active record without db connection)

design patter grime --> add behaviour irrelevant for pattern (active record that's also a singleton)

==== Class cohesion ====

[[File:cohesion.png]]

==== Modular coupling ====

[[File:coupling.png]]

Clearer boundaries between classes and modules make it easier to isolate change.

=== State ===

Heuristics to consider but not follow slavishly.

Keep a clear separation between classes with state and classes with no state.

Classes with state should not have dependencies with IO (it's OK to depend on classes in the same application layer, e.g. other DTO classes), and vice versa. ActiveRecord is an example which violates this principle.

class Survey
// Confusion - first params are domain state, last a resource
__construct(id, language, dbConnection)

If a method does not call "this", should it instead be outside the class? A separate class or function, maybe.

todo, elaborate

=== Types of classes ===

Different categories of classes:

* Entity (domain class; has state and validation behaviour)
* Resource (database connection, file, curl, logger; state is in the resource (open, closed))
* Repository classes (database interaction, like splitting ActiveRecord in two parts: Entity class and database interaction)
* DAO, data access object (similar to resource)
* Builders (e.g. query builder, HTML message builder)
* Data-transfer object (no behaviour; pass to views to have better documentation and intent than associative arrays)
* Value classes (e.g. Email address to wrap email string around)
* Command object (e.g. SurveyActivator)
* Helper (no state; e.g. QuestionAttributeHelper to bake attributes into different formats used by the views)
* Wrapper

todo, immutability, possible with private properties that are set in the constructor,

todo: command-query separation for classes?

todo: dependencies between layers, dependencies to the framework

todo, pure vs effectful classes

=== Types of classes in LimeSurvey ===

* ActiveRecord, used to communicate with the database, and should not do ''anything'' else
* Controllers, used for glue code; should not contain business-logic (also CLI controllers)
* Helper functions (not classes, yet...), should be short and obey command-query separation (TODO: Long functions should be separated into command objects or service classes); todo: should not have any dependencies?
* Helper classes, similar to helper functions but have dependencies that need to be mocked during tests; should not have any state
* Service classes, contains logic related to a clear and separate task, like create or import survey
* Question render classes, contains logic related to how questions are rendered (TODO: Need better separation between state and logic and more clear design); similar to widgets
* Plugin classes, using the plugin event system
* Widgets, containing HTML logic for custom HTML widgets
* HTML helpers (Yii)
* Customizations to the Yii framework by inheritance
* Unit and functional test classes

A couple of classes contain only data, like LsDefaultDataSet.

todo, no difference between state property and dependency property in OOP

=== What is "glue code"? ===

todo

Putting the pieces together, e.g. service class A need data from model B, fetch it and run.

todo, add example

=== "Where do I cut?" ===

Separation of concerns, but which concerns and which type of separation? Command-query (function core, imperative shell) is one type of separation. Other separation between layers, e.g. logic layer and data persistency layer (similar in thought).

Other separation, that one class should have a clear purpose. A design pattern should only implement ''one'' pattern, not multiple, and not half a pattern.

There's a problem with "helper" or "manager" classes that they can grow indefinitely, but might be better than nothing. Example when moving business logic out of ActiveRecord class to a helper class it can sometimes hard to be more specific than "helper".

=== Size ===

A class should have a single and clear purpose; compare with [https://en.wikipedia.org/wiki/SOLID SOLID].

=== Class name ===

* ActiveRecord classes are named after the database table they are bound to, but with singular instead of plural. E.g. table "lime_users" have model "User".
* Command classes are named after what they ''do'' and imperatively, e.g. CreateSurvey
* Helper classes should probably be named as specific as possible when possible, to avoid them from growing too big
* Follow the naming tradition of the framework with regard to controllers, e.g. UserController or UserAdministrationController.
* Class properties of ActiveRecord classes will follow the naming of the database, using underscore instead of camel case (and ActiveRecord classes should have ''no'' other properties than those (excluding the database connection injected by the framework))

== Functions ==

Functions are one of the fundamental building blocks of programming, so it's important to get it right.

Functions that are part of a class are called "methods", if you want to be formal.

Different types of functions in PHP:

* Functions (not attached to a class)
* Methods (attached to class)
* Anonymous functions (does not capture scope automatically)
* Short functions (does capture scope automatically)

I'm using "function" as a word for all types of functions in PHP below.

<hr>

=== Size ===

* A function should be short enough to be completely readable on one screen, approx 60 lines at most
* A function should not have too many arguments; if you have five or more, consider making it a class instead
* If a function is growing too big, it might be better to create a class instead or split it into several functions (if both functions have '''common state''', a class might be better, unless you want to pass around '''explicit state''')

=== Contract ===

* A function has a contract with its surrounding environment:
** Pre-condition: What needs to be true before the function is executed
** Post-condition: What will be true after the function has returned
* The function contract can be checked with assertions (internal invariants) or exceptions (outside world); see below
* Another good way is to use unit-tests to make sure the function's contract remains stable through changes
* The first line in the docblock should be one sentence describing the relation between function arguments and its output<br>Example<br><syntaxhighlight lang="php">
/**
* Creates a random password of length $length (defaults to 12)
* @param int $length
* @return string
*/
function createPassword($lenght = 12)

/**
* Creates an HTML language drop down for survey with id $surveyId, marking $selectedLanguage as selected
* @param int $surveyId
* @param string $selectedLanguage
* @return string <select> HTML
*/
function createLanguageDropdown($surveyId, $selectedLanguage)

</syntaxhighlight>

=== Push side-effects up in the stack trace ===

This one is a bit abstract.

First, what is a '''side-effect'''? In short, it's anything that happens in a function that ''is not'' described by the ''relation'' between function arguments and output.

Another way to phrase it is, that a side-effect is anything that is not always the same for the given input to a function; a function without any side-effects will always return the same result if it gets the same input.

'''Examples:'''

<syntaxhighlight lang="php">
// gT accesses the file system and will return different result depending on what's in the translation files
function gT($sToTranslate, $sEscapeMode = 'html', $sLanguage = null);

// If $sText and $sEscapeMode is always the same, quoteText() will always return the same string.
function quoteText($sText, $sEscapeMode = 'html');
</syntaxhighlight>

A function with no side-effects is called '''pure'''. A function that is guaranteed to always return (no exceptions, no errors, no warnings, no division by zero) is called '''total'''.

It's a good thing if functions in a code-base ''either'' have side-effects, ''or'' return a result. Not both. This is called [https://en.wikipedia.org/wiki/Command%E2%80%93query_separation command-query separation].

Examples of side-effects:

* Database or file access
* Echo, or write to stdout or stderr
* Randomization

Why does this matter? Because side-effects make testing harder! '''If you have side-effects, you cannot create unit tests''', ''unless'' those side-effects can be mocked. If not, you need integrity tests with database setup or more. The more side-effects you have in a function, the more mocking is required to unit test it.

So, one solution to this is to move side-effects higher up in the stack trace, that is, move them to the calling code.

'''Example:'''

<syntaxhighlight lang="php">
function getSurveyInfo(int $surveyid, string $languagecode = '', boolean $force = false): array;
</syntaxhighlight>

Since this function takes $surveyid, we know it will probably query the database. Quering the database is a side-effect, and thus it requires a database scaffold for the test (or mocking, but the database connection is not injected, so there's no way to do it). One simple solution is to lift the side-effect out and pass in a Survey object instead:

<syntaxhighlight lang="php">
function getSurveyInfo(Survey $survey, string $languagecode = '', boolean $force = false): array;
</syntaxhighlight>

Much better! The side-effect of calling the database now happens ''before'' the function call. Now we can either mock a Survey object, or make an imitating stub for our test.

Reading the function body, there is in fact another database access, but since this is a relation to the Survey model, it could easily be moved out too. We've just made a function testable! Hooray!

This principle is rephrased in an architectural settings as [https://github.com/kbilsted/Functional-core-imperative-shell/blob/master/README.md functional core, imperative shell]. This architecture helps you get a good ratio between fast unit tests and slower integrity tests.

Moving side-effects up makes sure we can have a healthy ratio between integrity tests with scripted browser, and unit-tests; maybe around 20-80.

=== Function name ===

* The function name should tell you '''what''' it does; docs should tell you '''why''' (if this information is not obvious). '''How''' is described by the code itself (hopefully, but can in some cases be relevant to document).
* Function name can often be '''verb [+ adjective] + noun''', like "createFieldmap", "quoteText", "getRelativePath"
* Prefix with "is" for boolean functions

todo: difference between create, get, fetch, generate, ...

'''Good examples:'''

* createPassword() - One verb, one noun - clear
* isCaptchaEnabled() - Using "is" signifies it returns boolean; clear purpose
* getFullResponseTable() - Verb, adjective, noun - but is "full" needed here? Is there a non-full version of the same function?
* replaceExpressionCodes() - Pretty good, but it's obvious that more information is needed in the docblock to describe what "replace" means, and what an "expression code" is
* fixCKeditorText() - "fix" is a bit vague, but maybe best there is? Pray that docblock contains information!

'''Bad examples:'''

* languageDropdown() - No verb, doesn't tell you what it does
* rmdirr() - Two r's, looks like a typo, but the last "r" actually means "recursive"! Better: rmdir($recursive = false), rmdir or removeFolder.
* CSVUnquote() - Is CSV really the namespace? Why is the verb the second word?
* incompleteAnsFilterState() - One verb, but in the middle, or is "filter state" a noun?; why abbreviate "answer" to "ans"?
* reverseTranslateFieldNames() - Two verbs - did author mean "reverseTranslatedFieldNames"? Or "reverse and translate"? If so, it should be two functions, one for reverse and one for translate
* checkUploadedFileSizeAndRenderJson() - If you have an "and" in the function name, you should consider splitting it into two functions

'''Controversial'''

* gT() - An exception to descriptive function names; since this is used everywhere, the minimal name is motivated; maybe even name it "t()"? Still hard to read for someone who just started? But Yii uses t() too? Other frameworks use double underscore (Wordpress, Laravel) as function name.

<hr>

=== Function filename and namespace ===

If your function has dependencies or side-effects, it should be put into a class instead, in which the dependencies can be injected. Another alternative is to put the dependencies as argument in the function, although this muffles the relationship between input and output. Again, this is to increase testability.

Keep in mind that functions outside classes cannot be mocked, so only use them when you ''know'' you won't need to mock them.

todo, autoloading of functions and folder location

=== Assertions ===

NB: This is not assertions as used in unit-tests, but assertions as used to check invariants in production code.

Assertions can be used for mental checks. They are only used for internal logic - failed assertions are not supposed to be seen by the end user. For interaction with the outside world, like database or browser, exceptions should be used instead.

Assertions can be disabled in production mode and have then no runtime cost (since PHP 7).

'''Example:'''

<syntaxhighlight lang="php">
/**
* Translation helper function
*
* @param string $sToTranslate
* @param string $sEscapeMode Valid values are html (this is the default, js and unescaped)
* @param string $sLanguage
* @return string
*/
function gT($sToTranslate, $sEscapeMode = 'html', $sLanguage = null)
{
assert(is_string($sToTranslate));
assert(strlen($sToTranslate) > 0);
assert($sEscapeMode === 'html' || $sEscapeMode === 'js' || $sEscapeMode === 'unescaped');
return quoteText(Yii::t('', $sToTranslate, array(), null, $sLanguage), $sEscapeMode);
}
</syntaxhighlight>

<hr>

=== Exceptions ===

* Exceptions are used to check inputs from the outside world (browser, database, file system)
* Don't use exceptions for control flow, only when fatal errors happen that make further execution impossible
* Exceptions should have clear error messages that make them ''actionable'' - there should be a clear "next step" for the user or developer
* Never, ever, do an empty catch-block
* At the moment, we do not have an exception hierarchy in LimeSurvey

==== Alternatives to exceptions ====

Some people consider exceptions being a hidden form of "goto" which confuses the control flow of the program. They propose different other solutions:

* Return a tuple, like <code>[$result, $errorMessage]</code> where $errorMessage is null at success
* Return <code>null</code> at failure
* Tagged union result type (not yet possible in latest PHP)
* Result object

The con being that you have to manually propagate the error, where an exception can happen from anywhere in the stack trace without any other function knowing about it.

=== If-statements ===

If-statements should not be too long or hard to understand. If they are, consider factor out the checks into separate functions.

<syntaxhighlight lang="php">
if ((empty($instance->oOptions->{$attribute}))
|| (
!empty($instance->oOptions->{$attribute})
&& (
$instance->oOptions->{$attribute} === 'inherit'
|| $instance->oOptions->{$attribute} === 'I'
// NB: Do NOT use === here, it won't work with Postgresql.
|| $instance->oOptions->{$attribute} == '-1'
)
)
) {
</syntaxhighlight>

Can be shortened by factoring out method <code>isInherit</code>:

<syntaxhighlight lang="php">
if (empty($instance->options->{$attribute})
|| $this->isInherit($instance-options->{$attribute})) {
}
/**
* Returns true if $value is set to inherit
* @param mixed|null $value
* @return boolean
*/
public function isInherit($value) {
return !empty($value)
&& (
$value === 'inherit'
|| $value === 'I'
// NB: Do NOT use === here, it won't work with Postgresql.
|| $value == '-1'
);
}
</syntaxhighlight>

And one more time by using a variable for the value:

<syntaxhighlight lang="php">
$value = $instance->options->{$attribute};
if (empty($value) || $this->isInherit($value)) {
}
</syntaxhighlight>

More clear, right? "If it's empty or set to inherit, do this and that."

=== Variables ===

Descriptive naming.

* Follow PSR-12 - no underscore, use camelCaseLikeThis
* Variables of ActiveRecord classes can have same name as the class, like "$survey" or "$question"
* Add -s for plural when it's a list of items: "$surveys", "$questions"
* Never include "array" or "list" in variable names - using plural is enough (for lists, not for associative arrays - see below)
* The ''context'' of the function helps with variable naming, e..g "$name" might be fine in a function about questions; this is extra helpful when functions are short!
* When a function is short, it's much easier to figure out variable meaning based on context
* $qid, $gid, and $sid are so established in the code-base that they could be considered OK
* The -data suffix means "blob of stuff", only use it when needed, like with $viewData
* Use $result when baking a return value; add its exact type as @var annotation (worst possible name, acceptable but anything with more meaning is better)

Not so good:

<syntaxhighlight lang="php">
$result = LabelSet::model()->findAll();
</syntaxhighlight>

Better with model name and -s for plural:

<syntaxhighlight lang="php">
$labelSets = LabelSet::model()->findAll();
</syntaxhighlight>

* Do not use Hungarian notation (prefix with "type"), but instead <code>/** @var */</code> annotations - these can be checked automatically and will then be enforced to be correct, unlike Hungarian notation which can "rot"

<syntaxhighlight lang="php">
/** string[] An array of strings with 0-n elements */
$allFields = [];
</syntaxhighlight>

Psalm can infer types if the function documentation is enough. The strictness can be adjusted. Not all variables will need @var annotation, the tool will warn you when it's confused.

* Data that is sent to views as associative arrays will be:

<syntaxhighlight lang="php">
/** @var array Can be basically anything :( Better would be data-transfer objects or more precise notation */
$data = [];
// Maybe more clear as $viewData? Discuss.
</syntaxhighlight>

You can be more precise when you specify which type of array you're writing:

<syntaxhighlight lang="php">
/** @var array<string, string> This means the array key is string, and the array value is also string */
$data = [];
$data['name'] = 'Olle';
$data['occupation'] = 'Developer';
$data['age'] = 38; // ERROR! Value must be string.
</syntaxhighlight>

For more info about array type notation, see the [https://psalm.dev/docs/annotating_code/type_syntax/array_types/ Psalm documentation].

Some smaller examples:

<syntaxhighlight lang="php">
$theme = App()->request->getPost('theme'); // Should be $themeType - $theme looks like a model/AR
$gridid === 'questionthemes-grid'; // Should be $gridId with capital "I", since it's two words in English
$delete = Yii::app()->request->getParam('delete'); // Tuff one - $delete is ok? Thoughts?
$files = json_decode(stripslashes($sJSON), true); // $file is a resource, $files an array of resources, this is $fileData perhaps?
$valid_extensions_array = explode(",", $aAttributes['allowed_filetypes']); // Should be $validExtensionTypes
$language = Yii::app()->session['survey_' . $surveyid]['s_lang']; // TODO: Should this be a value class? Then Language::make(...);
$surveyInfo = getSurveyInfo($surveyId, $language); // OK, BUT should be a separate DTO!
$fieldMap = createFieldMap($survey, 'short', false, false, $language); // Same, make a DTO
$cquestions = array(); // What's "c"? Method name is getChildQuestions and $questions is an argument - better with $childQuestions?
</syntaxhighlight>

Links:

[https://www.approxion.com/capital-offenses-how-to-handle-abbreviations-in-camelcase/ How to Handle Abbreviations in CamelCase]

[https://stackoverflow.com/questions/15526107/acronyms-in-camelcase Acronyms in CamelCase]

=== Looping ===

* The bodies of foreach-loops are often a good candidate to factor out into separate functions.

'''Example:'''

<syntaxhighlight lang="php">
foreach ($questions as $question) {
processQuestion($question);
}
</syntaxhighlight>

Note the variable naming from plural to singular.

* Loop indexing should be named i, j, k etc.

'''Example:'''

<syntaxhighlight lang="php">
for ($i = 0; $i < $length; $i++) {
for ($j = 0; $j < $otherLength; $j++) {
// ...
}
}
</syntaxhighlight>

<hr>

=== Function composition ===

todo, "doThisAndThat" --> "doThis(doThat())"

=== Cases ===

<syntaxhighlight lang="php">
/**
* This function generates an array containing the fieldcode, and matching data in the same order as the activate script
*
* @param Survey $survey Survey ActiveRecord model
* @param string $style 'short' (default) or 'full' - full creates extra information like default values
* @param boolean $force_refresh - Forces to really refresh the array, not just take the session copy
* @param bool|int $questionid Limit to a certain qid only (for question preview) - default is false
* @param string $sLanguage The language to use
* @param array $aDuplicateQIDs
* @return array
*/
function createFieldMap($survey, $style = 'short', $force_refresh = false, $questionid = false, $sLanguage = '', &$aDuplicateQIDs = array())
</syntaxhighlight>

'''Good:'''

* Name is verb and noun
* Each argument is documented (almost)

'''Bad:'''

* Returns "array", which can be anything. A separate class for "Fieldmap" would be better.
* Not clear if it should be "createFieldMap" or "createFieldmap" - is "fieldmap" one word or two?
* Very many boolean arguments. Should probably be a class with methods like <code>$fieldmapCreator->setForceRefresh(true);</code> instead.
* Too long.
* Doesn't elaborate on what "fieldmap" really is, and does not link to any documentation about it.
* Access super-global, which makes it hard to test. Should instead return a data-transfer object, like:<br><syntaxhighlight lang="php">
$_SESSION['fieldmap'] = createFieldMap(...);
</syntaxhighlight>
* Has no test
* Mixes Hungarian notation with non-Hungarian notation in the argument list

== Defensive programming and error handling ==

* '''Fail hard, fail early'''. The earlier the program crashes when something is wrong, the lower is the probability that you'll end up with corrupt data in the database that will later require manual labor to correct.
* Fail with '''actionable information'''
* Check input to functions and throw <code>InvalidArgumentException</code> if it violates the function's pre-conditions
* Use assert for class-internal invariants
* Use assert to make assumptions explicit for the reader

== Documentation ==

=== PHPDoc ===

* All functions must have a proper docblock
* The first line of the docblock should describe the relation between ''all'' the input arguments and the output of the function in a single sentence
* Each parameter must have the correct type
* Don't use <code>array</code> as type if it's a list of object - instead, use <code>[]</code> like so: <code>Survey[]</code> for a list of surveys

=== Technical documentation ===

todo, UML, scenarios, use-cases

== The PHP of yesterday ==

Old idioms and habits that should be abandoned.

* Don't use associative arrays, almost never. Data-transfer objects have multiple benefits: they are clearly structured, can be documented, can enforce invariants. There's ''no'' performance overhead of objects compared to arrays in modern PHP.
* Objects are already passed by reference; arrays are value types
* Use <code>[]</code> instead of <code>array()</code>
* Hungarian notation was useful before static analysis existed for PHP. These days it's better to use something that can be checked automatically: docblock @param and inline @var annotations.

== The PHP of tomorrow ==

todo

Union tags

Short functions

Match expressions

Partial application, pipe

== Security ==

todo

XSS

Database injection

Permissions and roles

== Performance ==

todo

Loading too many rows into PHP models

== Testing ==

todo

QA

PHPUnit

TDD

Mocks, can't mock functions, static methods, mocking as a DSL, PHPUnit mocking tools

Pure functions, referential transparency, side-effects

Unit, functional, integration

Don't test the framework; don't test PHP

Makes sure the function or class lives up to its specification; make sure it will ''always'' live up to its specification, even in the future, to avoid regressions.

== Static analysis ==

<code>php -l</code>, CodeSniffer, Mess Detector, Psalm

== Database design ==

todo

== JavaScript ==

todo

classes, functions, components, tests

== CSS ==

todo

== HTML ==

todo

== Feedback ==

=== "Why do I have to refactor code that works?" ===

todo, Sadly, it's not enough for the code to live up to the current specification and requirements, it must also be protected against future changes, regressions. Adding tests is the best way for this. Lots of people might read and change the LimeSurvey code the next 5-10 years. The test suite creates a security layer to make sure the specification is fulfilled even as the code changes.

Tests are not a magical solution, however. It does not protect us against other degradation of the code quality, like classes gaining too much responsibility (too many methods, unrelated methods, too many properties).

=== "What's the correct ratio between integrity tests and unit tests?" ===

todo, Don't know. Different pros and cons.

* Unit-test can be run in parallel and are faster
* Unit-tests don't need setup and teardown

Cons of unit-tests is that they need a bigger effort on the side of the developer to make them possible, for example injecting the dependencies properly to enable mocking, or lifting side-effects up in the stack trace.

=== How to disagree ===

All rules can be broken. To break a rule, you should reason in terms of risk and the assumptions used in this guide.

'''Assumptions:'''

# Regressions are the biggest technical risk for LimeSurvey the last five years (2021)
# Automated tests are the best risk mitigation technique against regressions

'''Possible disagreement:'''

# A certain piece of code has very low ''probability'' of regressions (maybe we "know" no one else will every touch or change it?)
# Regression in a certain piece of code would have very low ''impact''

== Architectural Decision Records ==

todo

https://adr.github.io/

== Resources ==

todo

Books, links, videos

Code quality guide

2021-05-19T10:16:56Z

Olle: /* Risk */

DRAFT

== Prologue ==

# '''Be risk aware'''. Too good code can be a business risk (slow to write, maybe over-designed). Too sloppy code can also be a business risk (hard to maintain and understand). You have to find a balance that is adapted to the current situation and risk analysis, in which code quality becomes a '''risk mitigation''' technique among others.
# '''Be humble'''. LimeSurvey was made by developers from all over the world, with different age, education and experience. Your code might be read by a completely different team ten years from now, in the same way you are now reading code by developers that no longer work with us, but which work pays our rent.
# '''Performance matters sometimes''', and shouldn't be disregarded completely. In particular, database queries using the ORM and ActiveRecord can be problematic. Some surveys have thousands of questions and hundreds of thousands of responses. Fast response time is also important for a fluid user experience.
# '''It's harder to read code than to write code'''. Don't choose patterns that are easy or fast to write, but that are easy to read.
# Make your code '''communicate intent'''.
# It's easy to forget '''cross-cutting concerns''' like translation and security. Keep a mental note.
# '''Stress affects code quality''' and your risk behaviour. If your stress level is too high to write code with proper quality, take a step back and discuss it with your boss, or you'll push problems to the future.

== Quality ==

The purpose of this guide is to increase the quality of the LimeSurvey code-base. What is quality? Which aspects of quality can be measured? Which kind of company culture gives rise to appropriate code quality?

It's usually easier to get along what is "bad" code than what's "best" code. Blacklist instead of whitelist?

Quality attributes related to code quality:

* Readability
* Testability
* Maintainability
* Performance
* Security
* Reliability

Can not increase all at the same time - performance vs readability.

It's better to avoid emotional language when describing code quality, like "clean" or "dirty". Be precise, objective and suggest solutions.

Idiomatic code is more readable than non-idiomatic code. What's idiomatic depends on which context or domain you work in. We work in PHP and web application development, and have other idioms than in, say, functional or hardware-close programming.

Some code are "hot spots" - changed often. Those parts should require higher quality than other code.

== Risk ==

todo

Why a risk-based approach? Waterfall vs agile, code driven.

Couple of different definition of risk:

* Tuple of probability and severity
* Triple of consequence, uncertainty and knowledge base

Possible risks related to LimeSurvey (technical or business):

* Data loss
* Regressions
* Bad UI (higher churn-rate for users)
* Hard to maintain (reduced sprint velocity)
*

How know which is the biggest risk? How many risks can be approached at once?

Connection to architecture. Risk --> quality attributes --> architectural decisions.

usability a business risk - hard to use or understand, people will choose another tool

risks relevant when fixing bugs

risks relevant when adding new features (lack of testing, wrong requirements, scope creep)

risks relevant when refactoring (regressions)

unit tests and QA as risk mitigation

partial deployment, alpha/beta/rc, risk communication

software rot, design pattern rot/grime, software evolution

rot = non-pattern related code

testing by community, bug fixing by community

risk based on knowledge, evidence, P(A|K)

== Modules ==

There's no inherit module functionality in PHP, but Yii has a module system. Libraries can be seen as a module system.

Examples of implicit modules in LimeSurvey:

* Front-end (survey taking)
* Back-end (survey design)
* Survey theme editing
* Expression manager
* Plugin system

In the future, they need to be separated and implemented more clearly as whatever Yii 3 module system is in use.

Some data models are common for all modules, e.g. surveys and users. Can have a "Common" module for such data.

todo, relation to Yii config system

== Classes ==

* Avoid empty OOP ceremony, like defining getters and setters for all properties. Might as well make them public, ''unless'' they have invariants that need to be upheld, e.g. "this number is always between 1 and 10" or "this string is maximum length 20".
* Almost always avoid static methods. They cannot be mocked. One exception is (possibly) factory methods (Foo::make(...)).
* Inject all dependencies. This will make sure the class can be unit-tested (unit-tests have several benefits over integrity tests - they can be run in parallel and don't require any setup and teardown)
* A second way to achieve testability is to factor out the methods that access the dependencies

todo, state vs behaviour, state vs dependencies

=== OOP design ===

Start from top-down, with domain, behaviour, interaction between objects, database design, pseudo-code if needed. Can also include scenarios, use-cases and UML diagrams.

Object reification - not only domain models, but also domain actions, relations and activities can be objects, e.g. a class ActivateSurvey or ExportSurvey.

Hierarchy depth should be kept reasonable shallow to avoid conflicts between methods, spooky action at a distance. Compare with Yii 3, where controllers no longer inherit anything.

Some people advocate for composition instead of inheritance. Lots of blog posts available for more info.

Multiple inheritance is done with traits in PHP. Use-case: ActiveRecords where some but not all models support encryption.

==== Shape design problem ====

Imagine you have three shapes: Point, rectangle and circle, with the following properties:

* Point: int x, int y
* Rectangle: Point bottomLeft, Point topRight
* Circle: Point center, int radius

Add two behaviours: area(), draw(surface).

* Cohesion: A class (or module) should be responsible for one thing only
* Coupling: You should be able to ''isolate change'' in the system
* Encapsulation: Classes shouldn’t share internal representation
* Polymorphism: The design should be based on interfaces

Questions to consider:

* How easy would it be to move to a 3D representation?
* How easy would it be to add a new shape, say, triangle?
* How easy would it be to add a new behaviour to all shapes, like save/load from a SQL database?
* Which classes ''change together''?

Keep polymorphism and encapsulation - all properties are private.

Example pseudo-code:

forall shapes as shape, do shape.draw(surface)

forall shapes as shape, do surface.draw(shape) (where shape.getDrawData(), or shape.getPath())

=== Software evolution ===

Design rot after time - how to keep it tight? (Grime.)

Architecture design roundtrip, based on risk.

todo

==== Grime and rot ====

design pattern rot --> lose behaviour relevant for pattern (active record without db connection)

design patter grime --> add behaviour irrelevant for pattern (active record that's also a singleton)

==== Class cohesion ====

[[File:cohesion.png]]

==== Modular coupling ====

[[File:coupling.png]]

Clearer boundaries between classes and modules make it easier to isolate change.

=== State ===

Heuristics to consider but not follow slavishly.

Keep a clear separation between classes with state and classes with no state.

Classes with state should not have dependencies with IO (it's OK to depend on classes in the same application layer, e.g. other DTO classes), and vice versa. ActiveRecord is an example which violates this principle.

class Survey
// Confusion - first params are domain state, last a resource
__construct(id, language, dbConnection)

If a method does not call "this", should it instead be outside the class? A separate class or function, maybe.

todo, elaborate

=== Types of classes ===

Different categories of classes:

* Entity (domain class; has state and validation behaviour)
* Resource (database connection, file, curl, logger; state is in the resource (open, closed))
* Repository classes (database interaction, like splitting ActiveRecord in two parts: Entity class and database interaction)
* DAO, data access object (similar to resource)
* Builders (e.g. query builder, HTML message builder)
* Data-transfer object (no behaviour; pass to views to have better documentation and intent than associative arrays)
* Value classes (e.g. Email address to wrap email string around)
* Command object (e.g. SurveyActivator)
* Helper (no state; e.g. QuestionAttributeHelper to bake attributes into different formats used by the views)
* Wrapper

todo, immutability, possible with private properties that are set in the constructor,

todo: command-query separation for classes?

todo: dependencies between layers, dependencies to the framework

todo, pure vs effectful classes

=== Types of classes in LimeSurvey ===

* ActiveRecord, used to communicate with the database, and should not do ''anything'' else
* Controllers, used for glue code; should not contain business-logic (also CLI controllers)
* Helper functions (not classes, yet...), should be short and obey command-query separation (TODO: Long functions should be separated into command objects or service classes); todo: should not have any dependencies?
* Helper classes, similar to helper functions but have dependencies that need to be mocked during tests; should not have any state
* Service classes, contains logic related to a clear and separate task, like create or import survey
* Question render classes, contains logic related to how questions are rendered (TODO: Need better separation between state and logic and more clear design); similar to widgets
* Plugin classes, using the plugin event system
* Widgets, containing HTML logic for custom HTML widgets
* HTML helpers (Yii)
* Customizations to the Yii framework by inheritance
* Unit and functional test classes

A couple of classes contain only data, like LsDefaultDataSet.

todo, no difference between state property and dependency property in OOP

=== What is "glue code"? ===

todo

Putting the pieces together, e.g. service class A need data from model B, fetch it and run.

todo, add example

=== "Where do I cut?" ===

Separation of concerns, but which concerns and which type of separation? Command-query (function core, imperative shell) is one type of separation. Other separation between layers, e.g. logic layer and data persistency layer (similar in thought).

Other separation, that one class should have a clear purpose. A design pattern should only implement ''one'' pattern, not multiple, and not half a pattern.

There's a problem with "helper" or "manager" classes that they can grow indefinitely, but might be better than nothing. Example when moving business logic out of ActiveRecord class to a helper class it can sometimes hard to be more specific than "helper".

=== Size ===

A class should have a single and clear purpose; compare with [https://en.wikipedia.org/wiki/SOLID SOLID].

=== Class name ===

* ActiveRecord classes are named after the database table they are bound to, but with singular instead of plural. E.g. table "lime_users" have model "User".
* Command classes are named after what they ''do'' and imperatively, e.g. CreateSurvey
* Helper classes should probably be named as specific as possible when possible, to avoid them from growing too big
* Follow the naming tradition of the framework with regard to controllers, e.g. UserController or UserAdministrationController.
* Class properties of ActiveRecord classes will follow the naming of the database, using underscore instead of camel case (and ActiveRecord classes should have ''no'' other properties than those (excluding the database connection injected by the framework))

== Functions ==

Functions are one of the fundamental building blocks of programming, so it's important to get it right.

Functions that are part of a class are called "methods", if you want to be formal.

Different types of functions in PHP:

* Functions (not attached to a class)
* Methods (attached to class)
* Anonymous functions (does not capture scope automatically)
* Short functions (does capture scope automatically)

I'm using "function" as a word for all types of functions in PHP below.

<hr>

=== Size ===

* A function should be short enough to be completely readable on one screen, approx 60 lines at most
* A function should not have too many arguments; if you have five or more, consider making it a class instead
* If a function is growing too big, it might be better to create a class instead or split it into several functions (if both functions have '''common state''', a class might be better, unless you want to pass around '''explicit state''')

=== Contract ===

* A function has a contract with its surrounding environment:
** Pre-condition: What needs to be true before the function is executed
** Post-condition: What will be true after the function has returned
* The function contract can be checked with assertions (internal invariants) or exceptions (outside world); see below
* Another good way is to use unit-tests to make sure the function's contract remains stable through changes
* The first line in the docblock should be one sentence describing the relation between function arguments and its output<br>Example<br><syntaxhighlight lang="php">
/**
* Creates a random password of length $length (defaults to 12)
* @param int $length
* @return string
*/
function createPassword($lenght = 12)

/**
* Creates an HTML language drop down for survey with id $surveyId, marking $selectedLanguage as selected
* @param int $surveyId
* @param string $selectedLanguage
* @return string <select> HTML
*/
function createLanguageDropdown($surveyId, $selectedLanguage)

</syntaxhighlight>

=== Push side-effects up in the stack trace ===

This one is a bit abstract.

First, what is a '''side-effect'''? In short, it's anything that happens in a function that ''is not'' described by the ''relation'' between function arguments and output.

Another way to phrase it is, that a side-effect is anything that is not always the same for the given input to a function; a function without any side-effects will always return the same result if it gets the same input.

'''Examples:'''

<syntaxhighlight lang="php">
// gT accesses the file system and will return different result depending on what's in the translation files
function gT($sToTranslate, $sEscapeMode = 'html', $sLanguage = null);

// If $sText and $sEscapeMode is always the same, quoteText() will always return the same string.
function quoteText($sText, $sEscapeMode = 'html');
</syntaxhighlight>

A function with no side-effects is called '''pure'''. A function that is guaranteed to always return (no exceptions, no errors, no warnings, no division by zero) is called '''total'''.

It's a good thing if functions in a code-base ''either'' have side-effects, ''or'' return a result. Not both. This is called [https://en.wikipedia.org/wiki/Command%E2%80%93query_separation command-query separation].

Examples of side-effects:

* Database or file access
* Echo, or write to stdout or stderr
* Randomization

Why does this matter? Because side-effects make testing harder! '''If you have side-effects, you cannot create unit tests''', ''unless'' those side-effects can be mocked. If not, you need integrity tests with database setup or more. The more side-effects you have in a function, the more mocking is required to unit test it.

So, one solution to this is to move side-effects higher up in the stack trace, that is, move them to the calling code.

'''Example:'''

<syntaxhighlight lang="php">
function getSurveyInfo(int $surveyid, string $languagecode = '', boolean $force = false): array;
</syntaxhighlight>

Since this function takes $surveyid, we know it will probably query the database. Quering the database is a side-effect, and thus it requires a database scaffold for the test (or mocking, but the database connection is not injected, so there's no way to do it). One simple solution is to lift the side-effect out and pass in a Survey object instead:

<syntaxhighlight lang="php">
function getSurveyInfo(Survey $survey, string $languagecode = '', boolean $force = false): array;
</syntaxhighlight>

Much better! The side-effect of calling the database now happens ''before'' the function call. Now we can either mock a Survey object, or make an imitating stub for our test.

Reading the function body, there is in fact another database access, but since this is a relation to the Survey model, it could easily be moved out too. We've just made a function testable! Hooray!

This principle is rephrased in an architectural settings as [https://github.com/kbilsted/Functional-core-imperative-shell/blob/master/README.md functional core, imperative shell]. This architecture helps you get a good ratio between fast unit tests and slower integrity tests.

Moving side-effects up makes sure we can have a healthy ratio between integrity tests with scripted browser, and unit-tests; maybe around 20-80.

=== Function name ===

* The function name should tell you '''what''' it does; docs should tell you '''why''' (if this information is not obvious). '''How''' is described by the code itself (hopefully, but can in some cases be relevant to document).
* Function name can often be '''verb [+ adjective] + noun''', like "createFieldmap", "quoteText", "getRelativePath"
* Prefix with "is" for boolean functions

todo: difference between create, get, fetch, generate, ...

'''Good examples:'''

* createPassword() - One verb, one noun - clear
* isCaptchaEnabled() - Using "is" signifies it returns boolean; clear purpose
* getFullResponseTable() - Verb, adjective, noun - but is "full" needed here? Is there a non-full version of the same function?
* replaceExpressionCodes() - Pretty good, but it's obvious that more information is needed in the docblock to describe what "replace" means, and what an "expression code" is
* fixCKeditorText() - "fix" is a bit vague, but maybe best there is? Pray that docblock contains information!

'''Bad examples:'''

* languageDropdown() - No verb, doesn't tell you what it does
* rmdirr() - Two r's, looks like a typo, but the last "r" actually means "recursive"! Better: rmdir($recursive = false), rmdir or removeFolder.
* CSVUnquote() - Is CSV really the namespace? Why is the verb the second word?
* incompleteAnsFilterState() - One verb, but in the middle, or is "filter state" a noun?; why abbreviate "answer" to "ans"?
* reverseTranslateFieldNames() - Two verbs - did author mean "reverseTranslatedFieldNames"? Or "reverse and translate"? If so, it should be two functions, one for reverse and one for translate
* checkUploadedFileSizeAndRenderJson() - If you have an "and" in the function name, you should consider splitting it into two functions

'''Controversial'''

* gT() - An exception to descriptive function names; since this is used everywhere, the minimal name is motivated; maybe even name it "t()"? Still hard to read for someone who just started? But Yii uses t() too? Other frameworks use double underscore (Wordpress, Laravel) as function name.

<hr>

=== Function filename and namespace ===

If your function has dependencies or side-effects, it should be put into a class instead, in which the dependencies can be injected. Another alternative is to put the dependencies as argument in the function, although this muffles the relationship between input and output. Again, this is to increase testability.

Keep in mind that functions outside classes cannot be mocked, so only use them when you ''know'' you won't need to mock them.

todo, autoloading of functions and folder location

=== Assertions ===

NB: This is not assertions as used in unit-tests, but assertions as used to check invariants in production code.

Assertions can be used for mental checks. They are only used for internal logic - failed assertions are not supposed to be seen by the end user. For interaction with the outside world, like database or browser, exceptions should be used instead.

Assertions can be disabled in production mode and have then no runtime cost (since PHP 7).

'''Example:'''

<syntaxhighlight lang="php">
/**
* Translation helper function
*
* @param string $sToTranslate
* @param string $sEscapeMode Valid values are html (this is the default, js and unescaped)
* @param string $sLanguage
* @return string
*/
function gT($sToTranslate, $sEscapeMode = 'html', $sLanguage = null)
{
assert(is_string($sToTranslate));
assert(strlen($sToTranslate) > 0);
assert($sEscapeMode === 'html' || $sEscapeMode === 'js' || $sEscapeMode === 'unescaped');
return quoteText(Yii::t('', $sToTranslate, array(), null, $sLanguage), $sEscapeMode);
}
</syntaxhighlight>

<hr>

=== Exceptions ===

* Exceptions are used to check inputs from the outside world (browser, database, file system)
* Don't use exceptions for control flow, only when fatal errors happen that make further execution impossible
* Exceptions should have clear error messages that make them ''actionable'' - there should be a clear "next step" for the user or developer
* Never, ever, do an empty catch-block
* At the moment, we do not have an exception hierarchy in LimeSurvey

==== Alternatives to exceptions ====

Some people consider exceptions being a hidden form of "goto" which confuses the control flow of the program. They propose different other solutions:

* Return a tuple, like <code>[$result, $errorMessage]</code> where $errorMessage is null at success
* Return <code>null</code> at failure
* Tagged union result type (not yet possible in latest PHP)
* Result object

The con being that you have to manually propagate the error, where an exception can happen from anywhere in the stack trace without any other function knowing about it.

=== If-statements ===

If-statements should not be too long or hard to understand. If they are, consider factor out the checks into separate functions.

<syntaxhighlight lang="php">
if ((empty($instance->oOptions->{$attribute}))
|| (
!empty($instance->oOptions->{$attribute})
&& (
$instance->oOptions->{$attribute} === 'inherit'
|| $instance->oOptions->{$attribute} === 'I'
// NB: Do NOT use === here, it won't work with Postgresql.
|| $instance->oOptions->{$attribute} == '-1'
)
)
) {
</syntaxhighlight>

Can be shortened by factoring out method <code>isInherit</code>:

<syntaxhighlight lang="php">
if (empty($instance->options->{$attribute})
|| $this->isInherit($instance-options->{$attribute})) {
}
/**
* Returns true if $value is set to inherit
* @param mixed|null $value
* @return boolean
*/
public function isInherit($value) {
return !empty($value)
&& (
$value === 'inherit'
|| $value === 'I'
// NB: Do NOT use === here, it won't work with Postgresql.
|| $value == '-1'
);
}
</syntaxhighlight>

And one more time by using a variable for the value:

<syntaxhighlight lang="php">
$value = $instance->options->{$attribute};
if (empty($value) || $this->isInherit($value)) {
}
</syntaxhighlight>

More clear, right? "If it's empty or set to inherit, do this and that."

=== Variables ===

Descriptive naming.

* Follow PSR-12 - no underscore, use camelCaseLikeThis
* Variables of ActiveRecord classes can have same name as the class, like "$survey" or "$question"
* Add -s for plural when it's a list of items: "$surveys", "$questions"
* Never include "array" or "list" in variable names - using plural is enough (for lists, not for associative arrays - see below)
* The ''context'' of the function helps with variable naming, e..g "$name" might be fine in a function about questions; this is extra helpful when functions are short!
* When a function is short, it's much easier to figure out variable meaning based on context
* $qid, $gid, and $sid are so established in the code-base that they could be considered OK
* The -data suffix means "blob of stuff", only use it when needed, like with $viewData
* Use $result when baking a return value; add its exact type as @var annotation (worst possible name, acceptable but anything with more meaning is better)

Not so good:

<syntaxhighlight lang="php">
$result = LabelSet::model()->findAll();
</syntaxhighlight>

Better with model name and -s for plural:

<syntaxhighlight lang="php">
$labelSets = LabelSet::model()->findAll();
</syntaxhighlight>

* Do not use Hungarian notation (prefix with "type"), but instead <code>/** @var */</code> annotations - these can be checked automatically and will then be enforced to be correct, unlike Hungarian notation which can "rot"

<syntaxhighlight lang="php">
/** string[] An array of strings with 0-n elements */
$allFields = [];
</syntaxhighlight>

Psalm can infer types if the function documentation is enough. The strictness can be adjusted. Not all variables will need @var annotation, the tool will warn you when it's confused.

* Data that is sent to views as associative arrays will be:

<syntaxhighlight lang="php">
/** @var array Can be basically anything :( Better would be data-transfer objects or more precise notation */
$data = [];
// Maybe more clear as $viewData? Discuss.
</syntaxhighlight>

You can be more precise when you specify which type of array you're writing:

<syntaxhighlight lang="php">
/** @var array<string, string> This means the array key is string, and the array value is also string */
$data = [];
$data['name'] = 'Olle';
$data['occupation'] = 'Developer';
$data['age'] = 38; // ERROR! Value must be string.
</syntaxhighlight>

For more info about array type notation, see the [https://psalm.dev/docs/annotating_code/type_syntax/array_types/ Psalm documentation].

Some smaller examples:

<syntaxhighlight lang="php">
$theme = App()->request->getPost('theme'); // Should be $themeType - $theme looks like a model/AR
$gridid === 'questionthemes-grid'; // Should be $gridId with capital "I", since it's two words in English
$delete = Yii::app()->request->getParam('delete'); // Tuff one - $delete is ok? Thoughts?
$files = json_decode(stripslashes($sJSON), true); // $file is a resource, $files an array of resources, this is $fileData perhaps?
$valid_extensions_array = explode(",", $aAttributes['allowed_filetypes']); // Should be $validExtensionTypes
$language = Yii::app()->session['survey_' . $surveyid]['s_lang']; // TODO: Should this be a value class? Then Language::make(...);
$surveyInfo = getSurveyInfo($surveyId, $language); // OK, BUT should be a separate DTO!
$fieldMap = createFieldMap($survey, 'short', false, false, $language); // Same, make a DTO
$cquestions = array(); // What's "c"? Method name is getChildQuestions and $questions is an argument - better with $childQuestions?
</syntaxhighlight>

Links:

[https://www.approxion.com/capital-offenses-how-to-handle-abbreviations-in-camelcase/ How to Handle Abbreviations in CamelCase]

[https://stackoverflow.com/questions/15526107/acronyms-in-camelcase Acronyms in CamelCase]

=== Looping ===

* The bodies of foreach-loops are often a good candidate to factor out into separate functions.

'''Example:'''

<syntaxhighlight lang="php">
foreach ($questions as $question) {
processQuestion($question);
}
</syntaxhighlight>

Note the variable naming from plural to singular.

* Loop indexing should be named i, j, k etc.

'''Example:'''

<syntaxhighlight lang="php">
for ($i = 0; $i < $length; $i++) {
for ($j = 0; $j < $otherLength; $j++) {
// ...
}
}
</syntaxhighlight>

<hr>

=== Function composition ===

todo, "doThisAndThat" --> "doThis(doThat())"

=== Cases ===

<syntaxhighlight lang="php">
/**
* This function generates an array containing the fieldcode, and matching data in the same order as the activate script
*
* @param Survey $survey Survey ActiveRecord model
* @param string $style 'short' (default) or 'full' - full creates extra information like default values
* @param boolean $force_refresh - Forces to really refresh the array, not just take the session copy
* @param bool|int $questionid Limit to a certain qid only (for question preview) - default is false
* @param string $sLanguage The language to use
* @param array $aDuplicateQIDs
* @return array
*/
function createFieldMap($survey, $style = 'short', $force_refresh = false, $questionid = false, $sLanguage = '', &$aDuplicateQIDs = array())
</syntaxhighlight>

'''Good:'''

* Name is verb and noun
* Each argument is documented (almost)

'''Bad:'''

* Returns "array", which can be anything. A separate class for "Fieldmap" would be better.
* Not clear if it should be "createFieldMap" or "createFieldmap" - is "fieldmap" one word or two?
* Very many boolean arguments. Should probably be a class with methods like <code>$fieldmapCreator->setForceRefresh(true);</code> instead.
* Too long.
* Doesn't elaborate on what "fieldmap" really is, and does not link to any documentation about it.
* Access super-global, which makes it hard to test. Should instead return a data-transfer object, like:<br><syntaxhighlight lang="php">
$_SESSION['fieldmap'] = createFieldMap(...);
</syntaxhighlight>
* Has no test
* Mixes Hungarian notation with non-Hungarian notation in the argument list

== Defensive programming and error handling ==

* '''Fail hard, fail early'''. The earlier the program crashes when something is wrong, the lower is the probability that you'll end up with corrupt data in the database that will later require manual labor to correct.
* Fail with '''actionable information'''
* Check input to functions and throw <code>InvalidArgumentException</code> if it violates the function's pre-conditions
* Use assert for class-internal invariants
* Use assert to make assumptions explicit for the reader

== Documentation ==

=== PHPDoc ===

* All functions must have a proper docblock
* The first line of the docblock should describe the relation between ''all'' the input arguments and the output of the function in a single sentence
* Each parameter must have the correct type
* Don't use <code>array</code> as type if it's a list of object - instead, use <code>[]</code> like so: <code>Survey[]</code> for a list of surveys

=== Technical documentation ===

todo, UML, scenarios, use-cases

== The PHP of yesterday ==

Old idioms and habits that should be abandoned.

* Don't use associative arrays, almost never. Data-transfer objects have multiple benefits: they are clearly structured, can be documented, can enforce invariants. There's ''no'' performance overhead of objects compared to arrays in modern PHP.
* Objects are already passed by reference; arrays are value types
* Use <code>[]</code> instead of <code>array()</code>
* Hungarian notation was useful before static analysis existed for PHP. These days it's better to use something that can be checked automatically: docblock @param and inline @var annotations.

== The PHP of tomorrow ==

todo

Union tags

Short functions

Match expressions

Partial application, pipe

== Security ==

todo

XSS

Database injection

Permissions and roles

== Performance ==

todo

Loading too many rows into PHP models

== Testing ==

todo

QA

PHPUnit

TDD

Mocks, can't mock functions, static methods, mocking as a DSL, PHPUnit mocking tools

Pure functions, referential transparency, side-effects

Unit, functional, integration

Don't test the framework; don't test PHP

Makes sure the function or class lives up to its specification; make sure it will ''always'' live up to its specification, even in the future, to avoid regressions.

== Static analysis ==

<code>php -l</code>, CodeSniffer, Mess Detector, Psalm

== Database design ==

todo

== JavaScript ==

todo

classes, functions, components, tests

== CSS ==

todo

== HTML ==

todo

== Feedback ==

=== "Why do I have to refactor code that works?" ===

todo, Sadly, it's not enough for the code to live up to the current specification and requirements, it must also be protected against future changes, regressions. Adding tests is the best way for this. Lots of people might read and change the LimeSurvey code the next 5-10 years. The test suite creates a security layer to make sure the specification is fulfilled even as the code changes.

Tests are not a magical solution, however. It does not protect us against other degradation of the code quality, like classes gaining too much responsibility (too many methods, unrelated methods, too many properties).

=== "What's the correct ratio between integrity tests and unit tests?" ===

todo, Don't know. Different pros and cons.

* Unit-test can be run in parallel and are faster
* Unit-tests don't need setup and teardown

Cons of unit-tests is that they need a bigger effort on the side of the developer to make them possible, for example injecting the dependencies properly to enable mocking, or lifting side-effects up in the stack trace.

=== How to disagree ===

All rules can be broken. To break a rule, you should reason in terms of risk and the assumptions used in this guide.

'''Assumptions:'''

# Regressions are the biggest technical risk for LimeSurvey the last five years (2021)
# Automated tests are the best risk mitigation technique against regressions

'''Possible disagreement:'''

# A certain piece of code has very low ''probability'' of regressions (maybe we "know" no one else will every touch or change it?)
# Regression in a certain piece of code would have very low ''impact''

== Architectural Decision Records ==

todo

https://adr.github.io/

== Resources ==

todo

Books, links, videos

Code quality guide

2021-05-19T10:16:42Z

Olle: /* Risk */

DRAFT

== Prologue ==

# '''Be risk aware'''. Too good code can be a business risk (slow to write, maybe over-designed). Too sloppy code can also be a business risk (hard to maintain and understand). You have to find a balance that is adapted to the current situation and risk analysis, in which code quality becomes a '''risk mitigation''' technique among others.
# '''Be humble'''. LimeSurvey was made by developers from all over the world, with different age, education and experience. Your code might be read by a completely different team ten years from now, in the same way you are now reading code by developers that no longer work with us, but which work pays our rent.
# '''Performance matters sometimes''', and shouldn't be disregarded completely. In particular, database queries using the ORM and ActiveRecord can be problematic. Some surveys have thousands of questions and hundreds of thousands of responses. Fast response time is also important for a fluid user experience.
# '''It's harder to read code than to write code'''. Don't choose patterns that are easy or fast to write, but that are easy to read.
# Make your code '''communicate intent'''.
# It's easy to forget '''cross-cutting concerns''' like translation and security. Keep a mental note.
# '''Stress affects code quality''' and your risk behaviour. If your stress level is too high to write code with proper quality, take a step back and discuss it with your boss, or you'll push problems to the future.

== Quality ==

The purpose of this guide is to increase the quality of the LimeSurvey code-base. What is quality? Which aspects of quality can be measured? Which kind of company culture gives rise to appropriate code quality?

It's usually easier to get along what is "bad" code than what's "best" code. Blacklist instead of whitelist?

Quality attributes related to code quality:

* Readability
* Testability
* Maintainability
* Performance
* Security
* Reliability

Can not increase all at the same time - performance vs readability.

It's better to avoid emotional language when describing code quality, like "clean" or "dirty". Be precise, objective and suggest solutions.

Idiomatic code is more readable than non-idiomatic code. What's idiomatic depends on which context or domain you work in. We work in PHP and web application development, and have other idioms than in, say, functional or hardware-close programming.

Some code are "hot spots" - changed often. Those parts should require higher quality than other code.

== Risk ==

todo

Why a risk-based approach?

Couple of different definition of risk:

* Tuple of probability and severity
* Triple of consequence, uncertainty and knowledge base

Possible risks related to LimeSurvey (technical or business):

* Data loss
* Regressions
* Bad UI (higher churn-rate for users)
* Hard to maintain (reduced sprint velocity)
*

How know which is the biggest risk? How many risks can be approached at once?

Connection to architecture. Risk --> quality attributes --> architectural decisions.

usability a business risk - hard to use or understand, people will choose another tool

risks relevant when fixing bugs

risks relevant when adding new features (lack of testing, wrong requirements, scope creep)

risks relevant when refactoring (regressions)

unit tests and QA as risk mitigation

partial deployment, alpha/beta/rc, risk communication

software rot, design pattern rot/grime, software evolution

rot = non-pattern related code

testing by community, bug fixing by community

risk based on knowledge, evidence, P(A|K)

== Modules ==

There's no inherit module functionality in PHP, but Yii has a module system. Libraries can be seen as a module system.

Examples of implicit modules in LimeSurvey:

* Front-end (survey taking)
* Back-end (survey design)
* Survey theme editing
* Expression manager
* Plugin system

In the future, they need to be separated and implemented more clearly as whatever Yii 3 module system is in use.

Some data models are common for all modules, e.g. surveys and users. Can have a "Common" module for such data.

todo, relation to Yii config system

== Classes ==

* Avoid empty OOP ceremony, like defining getters and setters for all properties. Might as well make them public, ''unless'' they have invariants that need to be upheld, e.g. "this number is always between 1 and 10" or "this string is maximum length 20".
* Almost always avoid static methods. They cannot be mocked. One exception is (possibly) factory methods (Foo::make(...)).
* Inject all dependencies. This will make sure the class can be unit-tested (unit-tests have several benefits over integrity tests - they can be run in parallel and don't require any setup and teardown)
* A second way to achieve testability is to factor out the methods that access the dependencies

todo, state vs behaviour, state vs dependencies

=== OOP design ===

Start from top-down, with domain, behaviour, interaction between objects, database design, pseudo-code if needed. Can also include scenarios, use-cases and UML diagrams.

Object reification - not only domain models, but also domain actions, relations and activities can be objects, e.g. a class ActivateSurvey or ExportSurvey.

Hierarchy depth should be kept reasonable shallow to avoid conflicts between methods, spooky action at a distance. Compare with Yii 3, where controllers no longer inherit anything.

Some people advocate for composition instead of inheritance. Lots of blog posts available for more info.

Multiple inheritance is done with traits in PHP. Use-case: ActiveRecords where some but not all models support encryption.

==== Shape design problem ====

Imagine you have three shapes: Point, rectangle and circle, with the following properties:

* Point: int x, int y
* Rectangle: Point bottomLeft, Point topRight
* Circle: Point center, int radius

Add two behaviours: area(), draw(surface).

* Cohesion: A class (or module) should be responsible for one thing only
* Coupling: You should be able to ''isolate change'' in the system
* Encapsulation: Classes shouldn’t share internal representation
* Polymorphism: The design should be based on interfaces

Questions to consider:

* How easy would it be to move to a 3D representation?
* How easy would it be to add a new shape, say, triangle?
* How easy would it be to add a new behaviour to all shapes, like save/load from a SQL database?
* Which classes ''change together''?

Keep polymorphism and encapsulation - all properties are private.

Example pseudo-code:

forall shapes as shape, do shape.draw(surface)

forall shapes as shape, do surface.draw(shape) (where shape.getDrawData(), or shape.getPath())

=== Software evolution ===

Design rot after time - how to keep it tight? (Grime.)

Architecture design roundtrip, based on risk.

todo

==== Grime and rot ====

design pattern rot --> lose behaviour relevant for pattern (active record without db connection)

design patter grime --> add behaviour irrelevant for pattern (active record that's also a singleton)

==== Class cohesion ====

[[File:cohesion.png]]

==== Modular coupling ====

[[File:coupling.png]]

Clearer boundaries between classes and modules make it easier to isolate change.

=== State ===

Heuristics to consider but not follow slavishly.

Keep a clear separation between classes with state and classes with no state.

Classes with state should not have dependencies with IO (it's OK to depend on classes in the same application layer, e.g. other DTO classes), and vice versa. ActiveRecord is an example which violates this principle.

class Survey
// Confusion - first params are domain state, last a resource
__construct(id, language, dbConnection)

If a method does not call "this", should it instead be outside the class? A separate class or function, maybe.

todo, elaborate

=== Types of classes ===

Different categories of classes:

* Entity (domain class; has state and validation behaviour)
* Resource (database connection, file, curl, logger; state is in the resource (open, closed))
* Repository classes (database interaction, like splitting ActiveRecord in two parts: Entity class and database interaction)
* DAO, data access object (similar to resource)
* Builders (e.g. query builder, HTML message builder)
* Data-transfer object (no behaviour; pass to views to have better documentation and intent than associative arrays)
* Value classes (e.g. Email address to wrap email string around)
* Command object (e.g. SurveyActivator)
* Helper (no state; e.g. QuestionAttributeHelper to bake attributes into different formats used by the views)
* Wrapper

todo, immutability, possible with private properties that are set in the constructor,

todo: command-query separation for classes?

todo: dependencies between layers, dependencies to the framework

todo, pure vs effectful classes

=== Types of classes in LimeSurvey ===

* ActiveRecord, used to communicate with the database, and should not do ''anything'' else
* Controllers, used for glue code; should not contain business-logic (also CLI controllers)
* Helper functions (not classes, yet...), should be short and obey command-query separation (TODO: Long functions should be separated into command objects or service classes); todo: should not have any dependencies?
* Helper classes, similar to helper functions but have dependencies that need to be mocked during tests; should not have any state
* Service classes, contains logic related to a clear and separate task, like create or import survey
* Question render classes, contains logic related to how questions are rendered (TODO: Need better separation between state and logic and more clear design); similar to widgets
* Plugin classes, using the plugin event system
* Widgets, containing HTML logic for custom HTML widgets
* HTML helpers (Yii)
* Customizations to the Yii framework by inheritance
* Unit and functional test classes

A couple of classes contain only data, like LsDefaultDataSet.

todo, no difference between state property and dependency property in OOP

=== What is "glue code"? ===

todo

Putting the pieces together, e.g. service class A need data from model B, fetch it and run.

todo, add example

=== "Where do I cut?" ===

Separation of concerns, but which concerns and which type of separation? Command-query (function core, imperative shell) is one type of separation. Other separation between layers, e.g. logic layer and data persistency layer (similar in thought).

Other separation, that one class should have a clear purpose. A design pattern should only implement ''one'' pattern, not multiple, and not half a pattern.

There's a problem with "helper" or "manager" classes that they can grow indefinitely, but might be better than nothing. Example when moving business logic out of ActiveRecord class to a helper class it can sometimes hard to be more specific than "helper".

=== Size ===

A class should have a single and clear purpose; compare with [https://en.wikipedia.org/wiki/SOLID SOLID].

=== Class name ===

* ActiveRecord classes are named after the database table they are bound to, but with singular instead of plural. E.g. table "lime_users" have model "User".
* Command classes are named after what they ''do'' and imperatively, e.g. CreateSurvey
* Helper classes should probably be named as specific as possible when possible, to avoid them from growing too big
* Follow the naming tradition of the framework with regard to controllers, e.g. UserController or UserAdministrationController.
* Class properties of ActiveRecord classes will follow the naming of the database, using underscore instead of camel case (and ActiveRecord classes should have ''no'' other properties than those (excluding the database connection injected by the framework))

== Functions ==

Functions are one of the fundamental building blocks of programming, so it's important to get it right.

Functions that are part of a class are called "methods", if you want to be formal.

Different types of functions in PHP:

* Functions (not attached to a class)
* Methods (attached to class)
* Anonymous functions (does not capture scope automatically)
* Short functions (does capture scope automatically)

I'm using "function" as a word for all types of functions in PHP below.

<hr>

=== Size ===

* A function should be short enough to be completely readable on one screen, approx 60 lines at most
* A function should not have too many arguments; if you have five or more, consider making it a class instead
* If a function is growing too big, it might be better to create a class instead or split it into several functions (if both functions have '''common state''', a class might be better, unless you want to pass around '''explicit state''')

=== Contract ===

* A function has a contract with its surrounding environment:
** Pre-condition: What needs to be true before the function is executed
** Post-condition: What will be true after the function has returned
* The function contract can be checked with assertions (internal invariants) or exceptions (outside world); see below
* Another good way is to use unit-tests to make sure the function's contract remains stable through changes
* The first line in the docblock should be one sentence describing the relation between function arguments and its output<br>Example<br><syntaxhighlight lang="php">
/**
* Creates a random password of length $length (defaults to 12)
* @param int $length
* @return string
*/
function createPassword($lenght = 12)

/**
* Creates an HTML language drop down for survey with id $surveyId, marking $selectedLanguage as selected
* @param int $surveyId
* @param string $selectedLanguage
* @return string <select> HTML
*/
function createLanguageDropdown($surveyId, $selectedLanguage)

</syntaxhighlight>

=== Push side-effects up in the stack trace ===

This one is a bit abstract.

First, what is a '''side-effect'''? In short, it's anything that happens in a function that ''is not'' described by the ''relation'' between function arguments and output.

Another way to phrase it is, that a side-effect is anything that is not always the same for the given input to a function; a function without any side-effects will always return the same result if it gets the same input.

'''Examples:'''

<syntaxhighlight lang="php">
// gT accesses the file system and will return different result depending on what's in the translation files
function gT($sToTranslate, $sEscapeMode = 'html', $sLanguage = null);

// If $sText and $sEscapeMode is always the same, quoteText() will always return the same string.
function quoteText($sText, $sEscapeMode = 'html');
</syntaxhighlight>

A function with no side-effects is called '''pure'''. A function that is guaranteed to always return (no exceptions, no errors, no warnings, no division by zero) is called '''total'''.

It's a good thing if functions in a code-base ''either'' have side-effects, ''or'' return a result. Not both. This is called [https://en.wikipedia.org/wiki/Command%E2%80%93query_separation command-query separation].

Examples of side-effects:

* Database or file access
* Echo, or write to stdout or stderr
* Randomization

Why does this matter? Because side-effects make testing harder! '''If you have side-effects, you cannot create unit tests''', ''unless'' those side-effects can be mocked. If not, you need integrity tests with database setup or more. The more side-effects you have in a function, the more mocking is required to unit test it.

So, one solution to this is to move side-effects higher up in the stack trace, that is, move them to the calling code.

'''Example:'''

<syntaxhighlight lang="php">
function getSurveyInfo(int $surveyid, string $languagecode = '', boolean $force = false): array;
</syntaxhighlight>

Since this function takes $surveyid, we know it will probably query the database. Quering the database is a side-effect, and thus it requires a database scaffold for the test (or mocking, but the database connection is not injected, so there's no way to do it). One simple solution is to lift the side-effect out and pass in a Survey object instead:

<syntaxhighlight lang="php">
function getSurveyInfo(Survey $survey, string $languagecode = '', boolean $force = false): array;
</syntaxhighlight>

Much better! The side-effect of calling the database now happens ''before'' the function call. Now we can either mock a Survey object, or make an imitating stub for our test.

Reading the function body, there is in fact another database access, but since this is a relation to the Survey model, it could easily be moved out too. We've just made a function testable! Hooray!

This principle is rephrased in an architectural settings as [https://github.com/kbilsted/Functional-core-imperative-shell/blob/master/README.md functional core, imperative shell]. This architecture helps you get a good ratio between fast unit tests and slower integrity tests.

Moving side-effects up makes sure we can have a healthy ratio between integrity tests with scripted browser, and unit-tests; maybe around 20-80.

=== Function name ===

* The function name should tell you '''what''' it does; docs should tell you '''why''' (if this information is not obvious). '''How''' is described by the code itself (hopefully, but can in some cases be relevant to document).
* Function name can often be '''verb [+ adjective] + noun''', like "createFieldmap", "quoteText", "getRelativePath"
* Prefix with "is" for boolean functions

todo: difference between create, get, fetch, generate, ...

'''Good examples:'''

* createPassword() - One verb, one noun - clear
* isCaptchaEnabled() - Using "is" signifies it returns boolean; clear purpose
* getFullResponseTable() - Verb, adjective, noun - but is "full" needed here? Is there a non-full version of the same function?
* replaceExpressionCodes() - Pretty good, but it's obvious that more information is needed in the docblock to describe what "replace" means, and what an "expression code" is
* fixCKeditorText() - "fix" is a bit vague, but maybe best there is? Pray that docblock contains information!

'''Bad examples:'''

* languageDropdown() - No verb, doesn't tell you what it does
* rmdirr() - Two r's, looks like a typo, but the last "r" actually means "recursive"! Better: rmdir($recursive = false), rmdir or removeFolder.
* CSVUnquote() - Is CSV really the namespace? Why is the verb the second word?
* incompleteAnsFilterState() - One verb, but in the middle, or is "filter state" a noun?; why abbreviate "answer" to "ans"?
* reverseTranslateFieldNames() - Two verbs - did author mean "reverseTranslatedFieldNames"? Or "reverse and translate"? If so, it should be two functions, one for reverse and one for translate
* checkUploadedFileSizeAndRenderJson() - If you have an "and" in the function name, you should consider splitting it into two functions

'''Controversial'''

* gT() - An exception to descriptive function names; since this is used everywhere, the minimal name is motivated; maybe even name it "t()"? Still hard to read for someone who just started? But Yii uses t() too? Other frameworks use double underscore (Wordpress, Laravel) as function name.

<hr>

=== Function filename and namespace ===

If your function has dependencies or side-effects, it should be put into a class instead, in which the dependencies can be injected. Another alternative is to put the dependencies as argument in the function, although this muffles the relationship between input and output. Again, this is to increase testability.

Keep in mind that functions outside classes cannot be mocked, so only use them when you ''know'' you won't need to mock them.

todo, autoloading of functions and folder location

=== Assertions ===

NB: This is not assertions as used in unit-tests, but assertions as used to check invariants in production code.

Assertions can be used for mental checks. They are only used for internal logic - failed assertions are not supposed to be seen by the end user. For interaction with the outside world, like database or browser, exceptions should be used instead.

Assertions can be disabled in production mode and have then no runtime cost (since PHP 7).

'''Example:'''

<syntaxhighlight lang="php">
/**
* Translation helper function
*
* @param string $sToTranslate
* @param string $sEscapeMode Valid values are html (this is the default, js and unescaped)
* @param string $sLanguage
* @return string
*/
function gT($sToTranslate, $sEscapeMode = 'html', $sLanguage = null)
{
assert(is_string($sToTranslate));
assert(strlen($sToTranslate) > 0);
assert($sEscapeMode === 'html' || $sEscapeMode === 'js' || $sEscapeMode === 'unescaped');
return quoteText(Yii::t('', $sToTranslate, array(), null, $sLanguage), $sEscapeMode);
}
</syntaxhighlight>

<hr>

=== Exceptions ===

* Exceptions are used to check inputs from the outside world (browser, database, file system)
* Don't use exceptions for control flow, only when fatal errors happen that make further execution impossible
* Exceptions should have clear error messages that make them ''actionable'' - there should be a clear "next step" for the user or developer
* Never, ever, do an empty catch-block
* At the moment, we do not have an exception hierarchy in LimeSurvey

==== Alternatives to exceptions ====

Some people consider exceptions being a hidden form of "goto" which confuses the control flow of the program. They propose different other solutions:

* Return a tuple, like <code>[$result, $errorMessage]</code> where $errorMessage is null at success
* Return <code>null</code> at failure
* Tagged union result type (not yet possible in latest PHP)
* Result object

The con being that you have to manually propagate the error, where an exception can happen from anywhere in the stack trace without any other function knowing about it.

=== If-statements ===

If-statements should not be too long or hard to understand. If they are, consider factor out the checks into separate functions.

<syntaxhighlight lang="php">
if ((empty($instance->oOptions->{$attribute}))
|| (
!empty($instance->oOptions->{$attribute})
&& (
$instance->oOptions->{$attribute} === 'inherit'
|| $instance->oOptions->{$attribute} === 'I'
// NB: Do NOT use === here, it won't work with Postgresql.
|| $instance->oOptions->{$attribute} == '-1'
)
)
) {
</syntaxhighlight>

Can be shortened by factoring out method <code>isInherit</code>:

<syntaxhighlight lang="php">
if (empty($instance->options->{$attribute})
|| $this->isInherit($instance-options->{$attribute})) {
}
/**
* Returns true if $value is set to inherit
* @param mixed|null $value
* @return boolean
*/
public function isInherit($value) {
return !empty($value)
&& (
$value === 'inherit'
|| $value === 'I'
// NB: Do NOT use === here, it won't work with Postgresql.
|| $value == '-1'
);
}
</syntaxhighlight>

And one more time by using a variable for the value:

<syntaxhighlight lang="php">
$value = $instance->options->{$attribute};
if (empty($value) || $this->isInherit($value)) {
}
</syntaxhighlight>

More clear, right? "If it's empty or set to inherit, do this and that."

=== Variables ===

Descriptive naming.

* Follow PSR-12 - no underscore, use camelCaseLikeThis
* Variables of ActiveRecord classes can have same name as the class, like "$survey" or "$question"
* Add -s for plural when it's a list of items: "$surveys", "$questions"
* Never include "array" or "list" in variable names - using plural is enough (for lists, not for associative arrays - see below)
* The ''context'' of the function helps with variable naming, e..g "$name" might be fine in a function about questions; this is extra helpful when functions are short!
* When a function is short, it's much easier to figure out variable meaning based on context
* $qid, $gid, and $sid are so established in the code-base that they could be considered OK
* The -data suffix means "blob of stuff", only use it when needed, like with $viewData
* Use $result when baking a return value; add its exact type as @var annotation (worst possible name, acceptable but anything with more meaning is better)

Not so good:

<syntaxhighlight lang="php">
$result = LabelSet::model()->findAll();
</syntaxhighlight>

Better with model name and -s for plural:

<syntaxhighlight lang="php">
$labelSets = LabelSet::model()->findAll();
</syntaxhighlight>

* Do not use Hungarian notation (prefix with "type"), but instead <code>/** @var */</code> annotations - these can be checked automatically and will then be enforced to be correct, unlike Hungarian notation which can "rot"

<syntaxhighlight lang="php">
/** string[] An array of strings with 0-n elements */
$allFields = [];
</syntaxhighlight>

Psalm can infer types if the function documentation is enough. The strictness can be adjusted. Not all variables will need @var annotation, the tool will warn you when it's confused.

* Data that is sent to views as associative arrays will be:

<syntaxhighlight lang="php">
/** @var array Can be basically anything :( Better would be data-transfer objects or more precise notation */
$data = [];
// Maybe more clear as $viewData? Discuss.
</syntaxhighlight>

You can be more precise when you specify which type of array you're writing:

<syntaxhighlight lang="php">
/** @var array<string, string> This means the array key is string, and the array value is also string */
$data = [];
$data['name'] = 'Olle';
$data['occupation'] = 'Developer';
$data['age'] = 38; // ERROR! Value must be string.
</syntaxhighlight>

For more info about array type notation, see the [https://psalm.dev/docs/annotating_code/type_syntax/array_types/ Psalm documentation].

Some smaller examples:

<syntaxhighlight lang="php">
$theme = App()->request->getPost('theme'); // Should be $themeType - $theme looks like a model/AR
$gridid === 'questionthemes-grid'; // Should be $gridId with capital "I", since it's two words in English
$delete = Yii::app()->request->getParam('delete'); // Tuff one - $delete is ok? Thoughts?
$files = json_decode(stripslashes($sJSON), true); // $file is a resource, $files an array of resources, this is $fileData perhaps?
$valid_extensions_array = explode(",", $aAttributes['allowed_filetypes']); // Should be $validExtensionTypes
$language = Yii::app()->session['survey_' . $surveyid]['s_lang']; // TODO: Should this be a value class? Then Language::make(...);
$surveyInfo = getSurveyInfo($surveyId, $language); // OK, BUT should be a separate DTO!
$fieldMap = createFieldMap($survey, 'short', false, false, $language); // Same, make a DTO
$cquestions = array(); // What's "c"? Method name is getChildQuestions and $questions is an argument - better with $childQuestions?
</syntaxhighlight>

Links:

[https://www.approxion.com/capital-offenses-how-to-handle-abbreviations-in-camelcase/ How to Handle Abbreviations in CamelCase]

[https://stackoverflow.com/questions/15526107/acronyms-in-camelcase Acronyms in CamelCase]

=== Looping ===

* The bodies of foreach-loops are often a good candidate to factor out into separate functions.

'''Example:'''

<syntaxhighlight lang="php">
foreach ($questions as $question) {
processQuestion($question);
}
</syntaxhighlight>

Note the variable naming from plural to singular.

* Loop indexing should be named i, j, k etc.

'''Example:'''

<syntaxhighlight lang="php">
for ($i = 0; $i < $length; $i++) {
for ($j = 0; $j < $otherLength; $j++) {
// ...
}
}
</syntaxhighlight>

<hr>

=== Function composition ===

todo, "doThisAndThat" --> "doThis(doThat())"

=== Cases ===

<syntaxhighlight lang="php">
/**
* This function generates an array containing the fieldcode, and matching data in the same order as the activate script
*
* @param Survey $survey Survey ActiveRecord model
* @param string $style 'short' (default) or 'full' - full creates extra information like default values
* @param boolean $force_refresh - Forces to really refresh the array, not just take the session copy
* @param bool|int $questionid Limit to a certain qid only (for question preview) - default is false
* @param string $sLanguage The language to use
* @param array $aDuplicateQIDs
* @return array
*/
function createFieldMap($survey, $style = 'short', $force_refresh = false, $questionid = false, $sLanguage = '', &$aDuplicateQIDs = array())
</syntaxhighlight>

'''Good:'''

* Name is verb and noun
* Each argument is documented (almost)

'''Bad:'''

* Returns "array", which can be anything. A separate class for "Fieldmap" would be better.
* Not clear if it should be "createFieldMap" or "createFieldmap" - is "fieldmap" one word or two?
* Very many boolean arguments. Should probably be a class with methods like <code>$fieldmapCreator->setForceRefresh(true);</code> instead.
* Too long.
* Doesn't elaborate on what "fieldmap" really is, and does not link to any documentation about it.
* Access super-global, which makes it hard to test. Should instead return a data-transfer object, like:<br><syntaxhighlight lang="php">
$_SESSION['fieldmap'] = createFieldMap(...);
</syntaxhighlight>
* Has no test
* Mixes Hungarian notation with non-Hungarian notation in the argument list

== Defensive programming and error handling ==

* '''Fail hard, fail early'''. The earlier the program crashes when something is wrong, the lower is the probability that you'll end up with corrupt data in the database that will later require manual labor to correct.
* Fail with '''actionable information'''
* Check input to functions and throw <code>InvalidArgumentException</code> if it violates the function's pre-conditions
* Use assert for class-internal invariants
* Use assert to make assumptions explicit for the reader

== Documentation ==

=== PHPDoc ===

* All functions must have a proper docblock
* The first line of the docblock should describe the relation between ''all'' the input arguments and the output of the function in a single sentence
* Each parameter must have the correct type
* Don't use <code>array</code> as type if it's a list of object - instead, use <code>[]</code> like so: <code>Survey[]</code> for a list of surveys

=== Technical documentation ===

todo, UML, scenarios, use-cases

== The PHP of yesterday ==

Old idioms and habits that should be abandoned.

* Don't use associative arrays, almost never. Data-transfer objects have multiple benefits: they are clearly structured, can be documented, can enforce invariants. There's ''no'' performance overhead of objects compared to arrays in modern PHP.
* Objects are already passed by reference; arrays are value types
* Use <code>[]</code> instead of <code>array()</code>
* Hungarian notation was useful before static analysis existed for PHP. These days it's better to use something that can be checked automatically: docblock @param and inline @var annotations.

== The PHP of tomorrow ==

todo

Union tags

Short functions

Match expressions

Partial application, pipe

== Security ==

todo

XSS

Database injection

Permissions and roles

== Performance ==

todo

Loading too many rows into PHP models

== Testing ==

todo

QA

PHPUnit

TDD

Mocks, can't mock functions, static methods, mocking as a DSL, PHPUnit mocking tools

Pure functions, referential transparency, side-effects

Unit, functional, integration

Don't test the framework; don't test PHP

Makes sure the function or class lives up to its specification; make sure it will ''always'' live up to its specification, even in the future, to avoid regressions.

== Static analysis ==

<code>php -l</code>, CodeSniffer, Mess Detector, Psalm

== Database design ==

todo

== JavaScript ==

todo

classes, functions, components, tests

== CSS ==

todo

== HTML ==

todo

== Feedback ==

=== "Why do I have to refactor code that works?" ===

todo, Sadly, it's not enough for the code to live up to the current specification and requirements, it must also be protected against future changes, regressions. Adding tests is the best way for this. Lots of people might read and change the LimeSurvey code the next 5-10 years. The test suite creates a security layer to make sure the specification is fulfilled even as the code changes.

Tests are not a magical solution, however. It does not protect us against other degradation of the code quality, like classes gaining too much responsibility (too many methods, unrelated methods, too many properties).

=== "What's the correct ratio between integrity tests and unit tests?" ===

todo, Don't know. Different pros and cons.

* Unit-test can be run in parallel and are faster
* Unit-tests don't need setup and teardown

Cons of unit-tests is that they need a bigger effort on the side of the developer to make them possible, for example injecting the dependencies properly to enable mocking, or lifting side-effects up in the stack trace.

=== How to disagree ===

All rules can be broken. To break a rule, you should reason in terms of risk and the assumptions used in this guide.

'''Assumptions:'''

# Regressions are the biggest technical risk for LimeSurvey the last five years (2021)
# Automated tests are the best risk mitigation technique against regressions

'''Possible disagreement:'''

# A certain piece of code has very low ''probability'' of regressions (maybe we "know" no one else will every touch or change it?)
# Regression in a certain piece of code would have very low ''impact''

== Architectural Decision Records ==

todo

https://adr.github.io/

== Resources ==

todo

Books, links, videos

Code quality guide

2021-05-19T10:14:35Z

Olle: /* Risk */

DRAFT

== Prologue ==

# '''Be risk aware'''. Too good code can be a business risk (slow to write, maybe over-designed). Too sloppy code can also be a business risk (hard to maintain and understand). You have to find a balance that is adapted to the current situation and risk analysis, in which code quality becomes a '''risk mitigation''' technique among others.
# '''Be humble'''. LimeSurvey was made by developers from all over the world, with different age, education and experience. Your code might be read by a completely different team ten years from now, in the same way you are now reading code by developers that no longer work with us, but which work pays our rent.
# '''Performance matters sometimes''', and shouldn't be disregarded completely. In particular, database queries using the ORM and ActiveRecord can be problematic. Some surveys have thousands of questions and hundreds of thousands of responses. Fast response time is also important for a fluid user experience.
# '''It's harder to read code than to write code'''. Don't choose patterns that are easy or fast to write, but that are easy to read.
# Make your code '''communicate intent'''.
# It's easy to forget '''cross-cutting concerns''' like translation and security. Keep a mental note.
# '''Stress affects code quality''' and your risk behaviour. If your stress level is too high to write code with proper quality, take a step back and discuss it with your boss, or you'll push problems to the future.

== Quality ==

The purpose of this guide is to increase the quality of the LimeSurvey code-base. What is quality? Which aspects of quality can be measured? Which kind of company culture gives rise to appropriate code quality?

It's usually easier to get along what is "bad" code than what's "best" code. Blacklist instead of whitelist?

Quality attributes related to code quality:

* Readability
* Testability
* Maintainability
* Performance
* Security
* Reliability

Can not increase all at the same time - performance vs readability.

It's better to avoid emotional language when describing code quality, like "clean" or "dirty". Be precise, objective and suggest solutions.

Idiomatic code is more readable than non-idiomatic code. What's idiomatic depends on which context or domain you work in. We work in PHP and web application development, and have other idioms than in, say, functional or hardware-close programming.

Some code are "hot spots" - changed often. Those parts should require higher quality than other code.

== Risk ==

todo

Couple of different definition of risk:

* Tuple of probability and severity
* Triple of consequence, uncertainty and knowledge base

Possible risks related to LimeSurvey (technical or business):

* Data loss
* Regressions
* Bad UI (higher churn-rate for users)
* Hard to maintain (reduced sprint velocity)
*

How know which is the biggest risk? How many risks can be approached at once?

Connection to architecture. Risk --> quality attributes --> architectural decisions.

usability a business risk - hard to use or understand, people will choose another tool

risks relevant when fixing bugs

risks relevant when adding new features (lack of testing, wrong requirements, scope creep)

risks relevant when refactoring (regressions)

unit tests and QA as risk mitigation

partial deployment, alpha/beta/rc, risk communication

software rot, design pattern rot/grime, software evolution

rot = non-pattern related code

testing by community, bug fixing by community

risk based on knowledge, evidence, P(A|K)

== Modules ==

There's no inherit module functionality in PHP, but Yii has a module system. Libraries can be seen as a module system.

Examples of implicit modules in LimeSurvey:

* Front-end (survey taking)
* Back-end (survey design)
* Survey theme editing
* Expression manager
* Plugin system

In the future, they need to be separated and implemented more clearly as whatever Yii 3 module system is in use.

Some data models are common for all modules, e.g. surveys and users. Can have a "Common" module for such data.

todo, relation to Yii config system

== Classes ==

* Avoid empty OOP ceremony, like defining getters and setters for all properties. Might as well make them public, ''unless'' they have invariants that need to be upheld, e.g. "this number is always between 1 and 10" or "this string is maximum length 20".
* Almost always avoid static methods. They cannot be mocked. One exception is (possibly) factory methods (Foo::make(...)).
* Inject all dependencies. This will make sure the class can be unit-tested (unit-tests have several benefits over integrity tests - they can be run in parallel and don't require any setup and teardown)
* A second way to achieve testability is to factor out the methods that access the dependencies

todo, state vs behaviour, state vs dependencies

=== OOP design ===

Start from top-down, with domain, behaviour, interaction between objects, database design, pseudo-code if needed. Can also include scenarios, use-cases and UML diagrams.

Object reification - not only domain models, but also domain actions, relations and activities can be objects, e.g. a class ActivateSurvey or ExportSurvey.

Hierarchy depth should be kept reasonable shallow to avoid conflicts between methods, spooky action at a distance. Compare with Yii 3, where controllers no longer inherit anything.

Some people advocate for composition instead of inheritance. Lots of blog posts available for more info.

Multiple inheritance is done with traits in PHP. Use-case: ActiveRecords where some but not all models support encryption.

==== Shape design problem ====

Imagine you have three shapes: Point, rectangle and circle, with the following properties:

* Point: int x, int y
* Rectangle: Point bottomLeft, Point topRight
* Circle: Point center, int radius

Add two behaviours: area(), draw(surface).

* Cohesion: A class (or module) should be responsible for one thing only
* Coupling: You should be able to ''isolate change'' in the system
* Encapsulation: Classes shouldn’t share internal representation
* Polymorphism: The design should be based on interfaces

Questions to consider:

* How easy would it be to move to a 3D representation?
* How easy would it be to add a new shape, say, triangle?
* How easy would it be to add a new behaviour to all shapes, like save/load from a SQL database?
* Which classes ''change together''?

Keep polymorphism and encapsulation - all properties are private.

Example pseudo-code:

forall shapes as shape, do shape.draw(surface)

forall shapes as shape, do surface.draw(shape) (where shape.getDrawData(), or shape.getPath())

=== Software evolution ===

Design rot after time - how to keep it tight? (Grime.)

Architecture design roundtrip, based on risk.

todo

==== Grime and rot ====

design pattern rot --> lose behaviour relevant for pattern (active record without db connection)

design patter grime --> add behaviour irrelevant for pattern (active record that's also a singleton)

==== Class cohesion ====

[[File:cohesion.png]]

==== Modular coupling ====

[[File:coupling.png]]

Clearer boundaries between classes and modules make it easier to isolate change.

=== State ===

Heuristics to consider but not follow slavishly.

Keep a clear separation between classes with state and classes with no state.

Classes with state should not have dependencies with IO (it's OK to depend on classes in the same application layer, e.g. other DTO classes), and vice versa. ActiveRecord is an example which violates this principle.

class Survey
// Confusion - first params are domain state, last a resource
__construct(id, language, dbConnection)

If a method does not call "this", should it instead be outside the class? A separate class or function, maybe.

todo, elaborate

=== Types of classes ===

Different categories of classes:

* Entity (domain class; has state and validation behaviour)
* Resource (database connection, file, curl, logger; state is in the resource (open, closed))
* Repository classes (database interaction, like splitting ActiveRecord in two parts: Entity class and database interaction)
* DAO, data access object (similar to resource)
* Builders (e.g. query builder, HTML message builder)
* Data-transfer object (no behaviour; pass to views to have better documentation and intent than associative arrays)
* Value classes (e.g. Email address to wrap email string around)
* Command object (e.g. SurveyActivator)
* Helper (no state; e.g. QuestionAttributeHelper to bake attributes into different formats used by the views)
* Wrapper

todo, immutability, possible with private properties that are set in the constructor,

todo: command-query separation for classes?

todo: dependencies between layers, dependencies to the framework

todo, pure vs effectful classes

=== Types of classes in LimeSurvey ===

* ActiveRecord, used to communicate with the database, and should not do ''anything'' else
* Controllers, used for glue code; should not contain business-logic (also CLI controllers)
* Helper functions (not classes, yet...), should be short and obey command-query separation (TODO: Long functions should be separated into command objects or service classes); todo: should not have any dependencies?
* Helper classes, similar to helper functions but have dependencies that need to be mocked during tests; should not have any state
* Service classes, contains logic related to a clear and separate task, like create or import survey
* Question render classes, contains logic related to how questions are rendered (TODO: Need better separation between state and logic and more clear design); similar to widgets
* Plugin classes, using the plugin event system
* Widgets, containing HTML logic for custom HTML widgets
* HTML helpers (Yii)
* Customizations to the Yii framework by inheritance
* Unit and functional test classes

A couple of classes contain only data, like LsDefaultDataSet.

todo, no difference between state property and dependency property in OOP

=== What is "glue code"? ===

todo

Putting the pieces together, e.g. service class A need data from model B, fetch it and run.

todo, add example

=== "Where do I cut?" ===

Separation of concerns, but which concerns and which type of separation? Command-query (function core, imperative shell) is one type of separation. Other separation between layers, e.g. logic layer and data persistency layer (similar in thought).

Other separation, that one class should have a clear purpose. A design pattern should only implement ''one'' pattern, not multiple, and not half a pattern.

There's a problem with "helper" or "manager" classes that they can grow indefinitely, but might be better than nothing. Example when moving business logic out of ActiveRecord class to a helper class it can sometimes hard to be more specific than "helper".

=== Size ===

A class should have a single and clear purpose; compare with [https://en.wikipedia.org/wiki/SOLID SOLID].

=== Class name ===

* ActiveRecord classes are named after the database table they are bound to, but with singular instead of plural. E.g. table "lime_users" have model "User".
* Command classes are named after what they ''do'' and imperatively, e.g. CreateSurvey
* Helper classes should probably be named as specific as possible when possible, to avoid them from growing too big
* Follow the naming tradition of the framework with regard to controllers, e.g. UserController or UserAdministrationController.
* Class properties of ActiveRecord classes will follow the naming of the database, using underscore instead of camel case (and ActiveRecord classes should have ''no'' other properties than those (excluding the database connection injected by the framework))

== Functions ==

Functions are one of the fundamental building blocks of programming, so it's important to get it right.

Functions that are part of a class are called "methods", if you want to be formal.

Different types of functions in PHP:

* Functions (not attached to a class)
* Methods (attached to class)
* Anonymous functions (does not capture scope automatically)
* Short functions (does capture scope automatically)

I'm using "function" as a word for all types of functions in PHP below.

<hr>

=== Size ===

* A function should be short enough to be completely readable on one screen, approx 60 lines at most
* A function should not have too many arguments; if you have five or more, consider making it a class instead
* If a function is growing too big, it might be better to create a class instead or split it into several functions (if both functions have '''common state''', a class might be better, unless you want to pass around '''explicit state''')

=== Contract ===

* A function has a contract with its surrounding environment:
** Pre-condition: What needs to be true before the function is executed
** Post-condition: What will be true after the function has returned
* The function contract can be checked with assertions (internal invariants) or exceptions (outside world); see below
* Another good way is to use unit-tests to make sure the function's contract remains stable through changes
* The first line in the docblock should be one sentence describing the relation between function arguments and its output<br>Example<br><syntaxhighlight lang="php">
/**
* Creates a random password of length $length (defaults to 12)
* @param int $length
* @return string
*/
function createPassword($lenght = 12)

/**
* Creates an HTML language drop down for survey with id $surveyId, marking $selectedLanguage as selected
* @param int $surveyId
* @param string $selectedLanguage
* @return string <select> HTML
*/
function createLanguageDropdown($surveyId, $selectedLanguage)

</syntaxhighlight>

=== Push side-effects up in the stack trace ===

This one is a bit abstract.

First, what is a '''side-effect'''? In short, it's anything that happens in a function that ''is not'' described by the ''relation'' between function arguments and output.

Another way to phrase it is, that a side-effect is anything that is not always the same for the given input to a function; a function without any side-effects will always return the same result if it gets the same input.

'''Examples:'''

<syntaxhighlight lang="php">
// gT accesses the file system and will return different result depending on what's in the translation files
function gT($sToTranslate, $sEscapeMode = 'html', $sLanguage = null);

// If $sText and $sEscapeMode is always the same, quoteText() will always return the same string.
function quoteText($sText, $sEscapeMode = 'html');
</syntaxhighlight>

A function with no side-effects is called '''pure'''. A function that is guaranteed to always return (no exceptions, no errors, no warnings, no division by zero) is called '''total'''.

It's a good thing if functions in a code-base ''either'' have side-effects, ''or'' return a result. Not both. This is called [https://en.wikipedia.org/wiki/Command%E2%80%93query_separation command-query separation].

Examples of side-effects:

* Database or file access
* Echo, or write to stdout or stderr
* Randomization

Why does this matter? Because side-effects make testing harder! '''If you have side-effects, you cannot create unit tests''', ''unless'' those side-effects can be mocked. If not, you need integrity tests with database setup or more. The more side-effects you have in a function, the more mocking is required to unit test it.

So, one solution to this is to move side-effects higher up in the stack trace, that is, move them to the calling code.

'''Example:'''

<syntaxhighlight lang="php">
function getSurveyInfo(int $surveyid, string $languagecode = '', boolean $force = false): array;
</syntaxhighlight>

Since this function takes $surveyid, we know it will probably query the database. Quering the database is a side-effect, and thus it requires a database scaffold for the test (or mocking, but the database connection is not injected, so there's no way to do it). One simple solution is to lift the side-effect out and pass in a Survey object instead:

<syntaxhighlight lang="php">
function getSurveyInfo(Survey $survey, string $languagecode = '', boolean $force = false): array;
</syntaxhighlight>

Much better! The side-effect of calling the database now happens ''before'' the function call. Now we can either mock a Survey object, or make an imitating stub for our test.

Reading the function body, there is in fact another database access, but since this is a relation to the Survey model, it could easily be moved out too. We've just made a function testable! Hooray!

This principle is rephrased in an architectural settings as [https://github.com/kbilsted/Functional-core-imperative-shell/blob/master/README.md functional core, imperative shell]. This architecture helps you get a good ratio between fast unit tests and slower integrity tests.

Moving side-effects up makes sure we can have a healthy ratio between integrity tests with scripted browser, and unit-tests; maybe around 20-80.

=== Function name ===

* The function name should tell you '''what''' it does; docs should tell you '''why''' (if this information is not obvious). '''How''' is described by the code itself (hopefully, but can in some cases be relevant to document).
* Function name can often be '''verb [+ adjective] + noun''', like "createFieldmap", "quoteText", "getRelativePath"
* Prefix with "is" for boolean functions

todo: difference between create, get, fetch, generate, ...

'''Good examples:'''

* createPassword() - One verb, one noun - clear
* isCaptchaEnabled() - Using "is" signifies it returns boolean; clear purpose
* getFullResponseTable() - Verb, adjective, noun - but is "full" needed here? Is there a non-full version of the same function?
* replaceExpressionCodes() - Pretty good, but it's obvious that more information is needed in the docblock to describe what "replace" means, and what an "expression code" is
* fixCKeditorText() - "fix" is a bit vague, but maybe best there is? Pray that docblock contains information!

'''Bad examples:'''

* languageDropdown() - No verb, doesn't tell you what it does
* rmdirr() - Two r's, looks like a typo, but the last "r" actually means "recursive"! Better: rmdir($recursive = false), rmdir or removeFolder.
* CSVUnquote() - Is CSV really the namespace? Why is the verb the second word?
* incompleteAnsFilterState() - One verb, but in the middle, or is "filter state" a noun?; why abbreviate "answer" to "ans"?
* reverseTranslateFieldNames() - Two verbs - did author mean "reverseTranslatedFieldNames"? Or "reverse and translate"? If so, it should be two functions, one for reverse and one for translate
* checkUploadedFileSizeAndRenderJson() - If you have an "and" in the function name, you should consider splitting it into two functions

'''Controversial'''

* gT() - An exception to descriptive function names; since this is used everywhere, the minimal name is motivated; maybe even name it "t()"? Still hard to read for someone who just started? But Yii uses t() too? Other frameworks use double underscore (Wordpress, Laravel) as function name.

<hr>

=== Function filename and namespace ===

If your function has dependencies or side-effects, it should be put into a class instead, in which the dependencies can be injected. Another alternative is to put the dependencies as argument in the function, although this muffles the relationship between input and output. Again, this is to increase testability.

Keep in mind that functions outside classes cannot be mocked, so only use them when you ''know'' you won't need to mock them.

todo, autoloading of functions and folder location

=== Assertions ===

NB: This is not assertions as used in unit-tests, but assertions as used to check invariants in production code.

Assertions can be used for mental checks. They are only used for internal logic - failed assertions are not supposed to be seen by the end user. For interaction with the outside world, like database or browser, exceptions should be used instead.

Assertions can be disabled in production mode and have then no runtime cost (since PHP 7).

'''Example:'''

<syntaxhighlight lang="php">
/**
* Translation helper function
*
* @param string $sToTranslate
* @param string $sEscapeMode Valid values are html (this is the default, js and unescaped)
* @param string $sLanguage
* @return string
*/
function gT($sToTranslate, $sEscapeMode = 'html', $sLanguage = null)
{
assert(is_string($sToTranslate));
assert(strlen($sToTranslate) > 0);
assert($sEscapeMode === 'html' || $sEscapeMode === 'js' || $sEscapeMode === 'unescaped');
return quoteText(Yii::t('', $sToTranslate, array(), null, $sLanguage), $sEscapeMode);
}
</syntaxhighlight>

<hr>

=== Exceptions ===

* Exceptions are used to check inputs from the outside world (browser, database, file system)
* Don't use exceptions for control flow, only when fatal errors happen that make further execution impossible
* Exceptions should have clear error messages that make them ''actionable'' - there should be a clear "next step" for the user or developer
* Never, ever, do an empty catch-block
* At the moment, we do not have an exception hierarchy in LimeSurvey

==== Alternatives to exceptions ====

Some people consider exceptions being a hidden form of "goto" which confuses the control flow of the program. They propose different other solutions:

* Return a tuple, like <code>[$result, $errorMessage]</code> where $errorMessage is null at success
* Return <code>null</code> at failure
* Tagged union result type (not yet possible in latest PHP)
* Result object

The con being that you have to manually propagate the error, where an exception can happen from anywhere in the stack trace without any other function knowing about it.

=== If-statements ===

If-statements should not be too long or hard to understand. If they are, consider factor out the checks into separate functions.

<syntaxhighlight lang="php">
if ((empty($instance->oOptions->{$attribute}))
|| (
!empty($instance->oOptions->{$attribute})
&& (
$instance->oOptions->{$attribute} === 'inherit'
|| $instance->oOptions->{$attribute} === 'I'
// NB: Do NOT use === here, it won't work with Postgresql.
|| $instance->oOptions->{$attribute} == '-1'
)
)
) {
</syntaxhighlight>

Can be shortened by factoring out method <code>isInherit</code>:

<syntaxhighlight lang="php">
if (empty($instance->options->{$attribute})
|| $this->isInherit($instance-options->{$attribute})) {
}
/**
* Returns true if $value is set to inherit
* @param mixed|null $value
* @return boolean
*/
public function isInherit($value) {
return !empty($value)
&& (
$value === 'inherit'
|| $value === 'I'
// NB: Do NOT use === here, it won't work with Postgresql.
|| $value == '-1'
);
}
</syntaxhighlight>

And one more time by using a variable for the value:

<syntaxhighlight lang="php">
$value = $instance->options->{$attribute};
if (empty($value) || $this->isInherit($value)) {
}
</syntaxhighlight>

More clear, right? "If it's empty or set to inherit, do this and that."

=== Variables ===

Descriptive naming.

* Follow PSR-12 - no underscore, use camelCaseLikeThis
* Variables of ActiveRecord classes can have same name as the class, like "$survey" or "$question"
* Add -s for plural when it's a list of items: "$surveys", "$questions"
* Never include "array" or "list" in variable names - using plural is enough (for lists, not for associative arrays - see below)
* The ''context'' of the function helps with variable naming, e..g "$name" might be fine in a function about questions; this is extra helpful when functions are short!
* When a function is short, it's much easier to figure out variable meaning based on context
* $qid, $gid, and $sid are so established in the code-base that they could be considered OK
* The -data suffix means "blob of stuff", only use it when needed, like with $viewData
* Use $result when baking a return value; add its exact type as @var annotation (worst possible name, acceptable but anything with more meaning is better)

Not so good:

<syntaxhighlight lang="php">
$result = LabelSet::model()->findAll();
</syntaxhighlight>

Better with model name and -s for plural:

<syntaxhighlight lang="php">
$labelSets = LabelSet::model()->findAll();
</syntaxhighlight>

* Do not use Hungarian notation (prefix with "type"), but instead <code>/** @var */</code> annotations - these can be checked automatically and will then be enforced to be correct, unlike Hungarian notation which can "rot"

<syntaxhighlight lang="php">
/** string[] An array of strings with 0-n elements */
$allFields = [];
</syntaxhighlight>

Psalm can infer types if the function documentation is enough. The strictness can be adjusted. Not all variables will need @var annotation, the tool will warn you when it's confused.

* Data that is sent to views as associative arrays will be:

<syntaxhighlight lang="php">
/** @var array Can be basically anything :( Better would be data-transfer objects or more precise notation */
$data = [];
// Maybe more clear as $viewData? Discuss.
</syntaxhighlight>

You can be more precise when you specify which type of array you're writing:

<syntaxhighlight lang="php">
/** @var array<string, string> This means the array key is string, and the array value is also string */
$data = [];
$data['name'] = 'Olle';
$data['occupation'] = 'Developer';
$data['age'] = 38; // ERROR! Value must be string.
</syntaxhighlight>

For more info about array type notation, see the [https://psalm.dev/docs/annotating_code/type_syntax/array_types/ Psalm documentation].

Some smaller examples:

<syntaxhighlight lang="php">
$theme = App()->request->getPost('theme'); // Should be $themeType - $theme looks like a model/AR
$gridid === 'questionthemes-grid'; // Should be $gridId with capital "I", since it's two words in English
$delete = Yii::app()->request->getParam('delete'); // Tuff one - $delete is ok? Thoughts?
$files = json_decode(stripslashes($sJSON), true); // $file is a resource, $files an array of resources, this is $fileData perhaps?
$valid_extensions_array = explode(",", $aAttributes['allowed_filetypes']); // Should be $validExtensionTypes
$language = Yii::app()->session['survey_' . $surveyid]['s_lang']; // TODO: Should this be a value class? Then Language::make(...);
$surveyInfo = getSurveyInfo($surveyId, $language); // OK, BUT should be a separate DTO!
$fieldMap = createFieldMap($survey, 'short', false, false, $language); // Same, make a DTO
$cquestions = array(); // What's "c"? Method name is getChildQuestions and $questions is an argument - better with $childQuestions?
</syntaxhighlight>

Links:

[https://www.approxion.com/capital-offenses-how-to-handle-abbreviations-in-camelcase/ How to Handle Abbreviations in CamelCase]

[https://stackoverflow.com/questions/15526107/acronyms-in-camelcase Acronyms in CamelCase]

=== Looping ===

* The bodies of foreach-loops are often a good candidate to factor out into separate functions.

'''Example:'''

<syntaxhighlight lang="php">
foreach ($questions as $question) {
processQuestion($question);
}
</syntaxhighlight>

Note the variable naming from plural to singular.

* Loop indexing should be named i, j, k etc.

'''Example:'''

<syntaxhighlight lang="php">
for ($i = 0; $i < $length; $i++) {
for ($j = 0; $j < $otherLength; $j++) {
// ...
}
}
</syntaxhighlight>

<hr>

=== Function composition ===

todo, "doThisAndThat" --> "doThis(doThat())"

=== Cases ===

<syntaxhighlight lang="php">
/**
* This function generates an array containing the fieldcode, and matching data in the same order as the activate script
*
* @param Survey $survey Survey ActiveRecord model
* @param string $style 'short' (default) or 'full' - full creates extra information like default values
* @param boolean $force_refresh - Forces to really refresh the array, not just take the session copy
* @param bool|int $questionid Limit to a certain qid only (for question preview) - default is false
* @param string $sLanguage The language to use
* @param array $aDuplicateQIDs
* @return array
*/
function createFieldMap($survey, $style = 'short', $force_refresh = false, $questionid = false, $sLanguage = '', &$aDuplicateQIDs = array())
</syntaxhighlight>

'''Good:'''

* Name is verb and noun
* Each argument is documented (almost)

'''Bad:'''

* Returns "array", which can be anything. A separate class for "Fieldmap" would be better.
* Not clear if it should be "createFieldMap" or "createFieldmap" - is "fieldmap" one word or two?
* Very many boolean arguments. Should probably be a class with methods like <code>$fieldmapCreator->setForceRefresh(true);</code> instead.
* Too long.
* Doesn't elaborate on what "fieldmap" really is, and does not link to any documentation about it.
* Access super-global, which makes it hard to test. Should instead return a data-transfer object, like:<br><syntaxhighlight lang="php">
$_SESSION['fieldmap'] = createFieldMap(...);
</syntaxhighlight>
* Has no test
* Mixes Hungarian notation with non-Hungarian notation in the argument list

== Defensive programming and error handling ==

* '''Fail hard, fail early'''. The earlier the program crashes when something is wrong, the lower is the probability that you'll end up with corrupt data in the database that will later require manual labor to correct.
* Fail with '''actionable information'''
* Check input to functions and throw <code>InvalidArgumentException</code> if it violates the function's pre-conditions
* Use assert for class-internal invariants
* Use assert to make assumptions explicit for the reader

== Documentation ==

=== PHPDoc ===

* All functions must have a proper docblock
* The first line of the docblock should describe the relation between ''all'' the input arguments and the output of the function in a single sentence
* Each parameter must have the correct type
* Don't use <code>array</code> as type if it's a list of object - instead, use <code>[]</code> like so: <code>Survey[]</code> for a list of surveys

=== Technical documentation ===

todo, UML, scenarios, use-cases

== The PHP of yesterday ==

Old idioms and habits that should be abandoned.

* Don't use associative arrays, almost never. Data-transfer objects have multiple benefits: they are clearly structured, can be documented, can enforce invariants. There's ''no'' performance overhead of objects compared to arrays in modern PHP.
* Objects are already passed by reference; arrays are value types
* Use <code>[]</code> instead of <code>array()</code>
* Hungarian notation was useful before static analysis existed for PHP. These days it's better to use something that can be checked automatically: docblock @param and inline @var annotations.

== The PHP of tomorrow ==

todo

Union tags

Short functions

Match expressions

Partial application, pipe

== Security ==

todo

XSS

Database injection

Permissions and roles

== Performance ==

todo

Loading too many rows into PHP models

== Testing ==

todo

QA

PHPUnit

TDD

Mocks, can't mock functions, static methods, mocking as a DSL, PHPUnit mocking tools

Pure functions, referential transparency, side-effects

Unit, functional, integration

Don't test the framework; don't test PHP

Makes sure the function or class lives up to its specification; make sure it will ''always'' live up to its specification, even in the future, to avoid regressions.

== Static analysis ==

<code>php -l</code>, CodeSniffer, Mess Detector, Psalm

== Database design ==

todo

== JavaScript ==

todo

classes, functions, components, tests

== CSS ==

todo

== HTML ==

todo

== Feedback ==

=== "Why do I have to refactor code that works?" ===

todo, Sadly, it's not enough for the code to live up to the current specification and requirements, it must also be protected against future changes, regressions. Adding tests is the best way for this. Lots of people might read and change the LimeSurvey code the next 5-10 years. The test suite creates a security layer to make sure the specification is fulfilled even as the code changes.

Tests are not a magical solution, however. It does not protect us against other degradation of the code quality, like classes gaining too much responsibility (too many methods, unrelated methods, too many properties).

=== "What's the correct ratio between integrity tests and unit tests?" ===

todo, Don't know. Different pros and cons.

* Unit-test can be run in parallel and are faster
* Unit-tests don't need setup and teardown

Cons of unit-tests is that they need a bigger effort on the side of the developer to make them possible, for example injecting the dependencies properly to enable mocking, or lifting side-effects up in the stack trace.

=== How to disagree ===

All rules can be broken. To break a rule, you should reason in terms of risk and the assumptions used in this guide.

'''Assumptions:'''

# Regressions are the biggest technical risk for LimeSurvey the last five years (2021)
# Automated tests are the best risk mitigation technique against regressions

'''Possible disagreement:'''

# A certain piece of code has very low ''probability'' of regressions (maybe we "know" no one else will every touch or change it?)
# Regression in a certain piece of code would have very low ''impact''

== Architectural Decision Records ==

todo

https://adr.github.io/

== Resources ==

todo

Books, links, videos

Code quality guide

2021-05-19T10:13:57Z

Olle: /* The PHP of tomorrow */

DRAFT

== Prologue ==

# '''Be risk aware'''. Too good code can be a business risk (slow to write, maybe over-designed). Too sloppy code can also be a business risk (hard to maintain and understand). You have to find a balance that is adapted to the current situation and risk analysis, in which code quality becomes a '''risk mitigation''' technique among others.
# '''Be humble'''. LimeSurvey was made by developers from all over the world, with different age, education and experience. Your code might be read by a completely different team ten years from now, in the same way you are now reading code by developers that no longer work with us, but which work pays our rent.
# '''Performance matters sometimes''', and shouldn't be disregarded completely. In particular, database queries using the ORM and ActiveRecord can be problematic. Some surveys have thousands of questions and hundreds of thousands of responses. Fast response time is also important for a fluid user experience.
# '''It's harder to read code than to write code'''. Don't choose patterns that are easy or fast to write, but that are easy to read.
# Make your code '''communicate intent'''.
# It's easy to forget '''cross-cutting concerns''' like translation and security. Keep a mental note.
# '''Stress affects code quality''' and your risk behaviour. If your stress level is too high to write code with proper quality, take a step back and discuss it with your boss, or you'll push problems to the future.

== Quality ==

The purpose of this guide is to increase the quality of the LimeSurvey code-base. What is quality? Which aspects of quality can be measured? Which kind of company culture gives rise to appropriate code quality?

It's usually easier to get along what is "bad" code than what's "best" code. Blacklist instead of whitelist?

Quality attributes related to code quality:

* Readability
* Testability
* Maintainability
* Performance
* Security
* Reliability

Can not increase all at the same time - performance vs readability.

It's better to avoid emotional language when describing code quality, like "clean" or "dirty". Be precise, objective and suggest solutions.

Idiomatic code is more readable than non-idiomatic code. What's idiomatic depends on which context or domain you work in. We work in PHP and web application development, and have other idioms than in, say, functional or hardware-close programming.

Some code are "hot spots" - changed often. Those parts should require higher quality than other code.

== Risk ==

todo

Couple of different definition of risk:

* Tuple of probability and severity
* Triple of consequence, uncertainty and knowledge base

Possible risks related to LimeSurvey (technical or business):

* Data loss
* Regressions
* Bad UI (higher churn-rate for users)
* Hard to maintain (reduced sprint velocity)
*

How know which is the biggest risk? How many risks can be approached at once?

Connection to architecture. Risk --> quality attributes --> architectural decisions.

usability a business risk - hard to use or understand, people will choose another tool

risks relevant when fixing bugs

risks relevant when adding new features (lack of testing, wrong requirements, scope creep)

risks relevant when refactoring (regressions)

unit tests and QA as risk mitigation

partial deployment, alpha/beta/rc, risk communication

software rot, design pattern rot/grime, software evolution

rot = non-pattern related code

testing by community, bug fixing by community

== Modules ==

There's no inherit module functionality in PHP, but Yii has a module system. Libraries can be seen as a module system.

Examples of implicit modules in LimeSurvey:

* Front-end (survey taking)
* Back-end (survey design)
* Survey theme editing
* Expression manager
* Plugin system

In the future, they need to be separated and implemented more clearly as whatever Yii 3 module system is in use.

Some data models are common for all modules, e.g. surveys and users. Can have a "Common" module for such data.

todo, relation to Yii config system

== Classes ==

* Avoid empty OOP ceremony, like defining getters and setters for all properties. Might as well make them public, ''unless'' they have invariants that need to be upheld, e.g. "this number is always between 1 and 10" or "this string is maximum length 20".
* Almost always avoid static methods. They cannot be mocked. One exception is (possibly) factory methods (Foo::make(...)).
* Inject all dependencies. This will make sure the class can be unit-tested (unit-tests have several benefits over integrity tests - they can be run in parallel and don't require any setup and teardown)
* A second way to achieve testability is to factor out the methods that access the dependencies

todo, state vs behaviour, state vs dependencies

=== OOP design ===

Start from top-down, with domain, behaviour, interaction between objects, database design, pseudo-code if needed. Can also include scenarios, use-cases and UML diagrams.

Object reification - not only domain models, but also domain actions, relations and activities can be objects, e.g. a class ActivateSurvey or ExportSurvey.

Hierarchy depth should be kept reasonable shallow to avoid conflicts between methods, spooky action at a distance. Compare with Yii 3, where controllers no longer inherit anything.

Some people advocate for composition instead of inheritance. Lots of blog posts available for more info.

Multiple inheritance is done with traits in PHP. Use-case: ActiveRecords where some but not all models support encryption.

==== Shape design problem ====

Imagine you have three shapes: Point, rectangle and circle, with the following properties:

* Point: int x, int y
* Rectangle: Point bottomLeft, Point topRight
* Circle: Point center, int radius

Add two behaviours: area(), draw(surface).

* Cohesion: A class (or module) should be responsible for one thing only
* Coupling: You should be able to ''isolate change'' in the system
* Encapsulation: Classes shouldn’t share internal representation
* Polymorphism: The design should be based on interfaces

Questions to consider:

* How easy would it be to move to a 3D representation?
* How easy would it be to add a new shape, say, triangle?
* How easy would it be to add a new behaviour to all shapes, like save/load from a SQL database?
* Which classes ''change together''?

Keep polymorphism and encapsulation - all properties are private.

Example pseudo-code:

forall shapes as shape, do shape.draw(surface)

forall shapes as shape, do surface.draw(shape) (where shape.getDrawData(), or shape.getPath())

=== Software evolution ===

Design rot after time - how to keep it tight? (Grime.)

Architecture design roundtrip, based on risk.

todo

==== Grime and rot ====

design pattern rot --> lose behaviour relevant for pattern (active record without db connection)

design patter grime --> add behaviour irrelevant for pattern (active record that's also a singleton)

==== Class cohesion ====

[[File:cohesion.png]]

==== Modular coupling ====

[[File:coupling.png]]

Clearer boundaries between classes and modules make it easier to isolate change.

=== State ===

Heuristics to consider but not follow slavishly.

Keep a clear separation between classes with state and classes with no state.

Classes with state should not have dependencies with IO (it's OK to depend on classes in the same application layer, e.g. other DTO classes), and vice versa. ActiveRecord is an example which violates this principle.

class Survey
// Confusion - first params are domain state, last a resource
__construct(id, language, dbConnection)

If a method does not call "this", should it instead be outside the class? A separate class or function, maybe.

todo, elaborate

=== Types of classes ===

Different categories of classes:

* Entity (domain class; has state and validation behaviour)
* Resource (database connection, file, curl, logger; state is in the resource (open, closed))
* Repository classes (database interaction, like splitting ActiveRecord in two parts: Entity class and database interaction)
* DAO, data access object (similar to resource)
* Builders (e.g. query builder, HTML message builder)
* Data-transfer object (no behaviour; pass to views to have better documentation and intent than associative arrays)
* Value classes (e.g. Email address to wrap email string around)
* Command object (e.g. SurveyActivator)
* Helper (no state; e.g. QuestionAttributeHelper to bake attributes into different formats used by the views)
* Wrapper

todo, immutability, possible with private properties that are set in the constructor,

todo: command-query separation for classes?

todo: dependencies between layers, dependencies to the framework

todo, pure vs effectful classes

=== Types of classes in LimeSurvey ===

* ActiveRecord, used to communicate with the database, and should not do ''anything'' else
* Controllers, used for glue code; should not contain business-logic (also CLI controllers)
* Helper functions (not classes, yet...), should be short and obey command-query separation (TODO: Long functions should be separated into command objects or service classes); todo: should not have any dependencies?
* Helper classes, similar to helper functions but have dependencies that need to be mocked during tests; should not have any state
* Service classes, contains logic related to a clear and separate task, like create or import survey
* Question render classes, contains logic related to how questions are rendered (TODO: Need better separation between state and logic and more clear design); similar to widgets
* Plugin classes, using the plugin event system
* Widgets, containing HTML logic for custom HTML widgets
* HTML helpers (Yii)
* Customizations to the Yii framework by inheritance
* Unit and functional test classes

A couple of classes contain only data, like LsDefaultDataSet.

todo, no difference between state property and dependency property in OOP

=== What is "glue code"? ===

todo

Putting the pieces together, e.g. service class A need data from model B, fetch it and run.

todo, add example

=== "Where do I cut?" ===

Separation of concerns, but which concerns and which type of separation? Command-query (function core, imperative shell) is one type of separation. Other separation between layers, e.g. logic layer and data persistency layer (similar in thought).

Other separation, that one class should have a clear purpose. A design pattern should only implement ''one'' pattern, not multiple, and not half a pattern.

There's a problem with "helper" or "manager" classes that they can grow indefinitely, but might be better than nothing. Example when moving business logic out of ActiveRecord class to a helper class it can sometimes hard to be more specific than "helper".

=== Size ===

A class should have a single and clear purpose; compare with [https://en.wikipedia.org/wiki/SOLID SOLID].

=== Class name ===

* ActiveRecord classes are named after the database table they are bound to, but with singular instead of plural. E.g. table "lime_users" have model "User".
* Command classes are named after what they ''do'' and imperatively, e.g. CreateSurvey
* Helper classes should probably be named as specific as possible when possible, to avoid them from growing too big
* Follow the naming tradition of the framework with regard to controllers, e.g. UserController or UserAdministrationController.
* Class properties of ActiveRecord classes will follow the naming of the database, using underscore instead of camel case (and ActiveRecord classes should have ''no'' other properties than those (excluding the database connection injected by the framework))

== Functions ==

Functions are one of the fundamental building blocks of programming, so it's important to get it right.

Functions that are part of a class are called "methods", if you want to be formal.

Different types of functions in PHP:

* Functions (not attached to a class)
* Methods (attached to class)
* Anonymous functions (does not capture scope automatically)
* Short functions (does capture scope automatically)

I'm using "function" as a word for all types of functions in PHP below.

<hr>

=== Size ===

* A function should be short enough to be completely readable on one screen, approx 60 lines at most
* A function should not have too many arguments; if you have five or more, consider making it a class instead
* If a function is growing too big, it might be better to create a class instead or split it into several functions (if both functions have '''common state''', a class might be better, unless you want to pass around '''explicit state''')

=== Contract ===

* A function has a contract with its surrounding environment:
** Pre-condition: What needs to be true before the function is executed
** Post-condition: What will be true after the function has returned
* The function contract can be checked with assertions (internal invariants) or exceptions (outside world); see below
* Another good way is to use unit-tests to make sure the function's contract remains stable through changes
* The first line in the docblock should be one sentence describing the relation between function arguments and its output<br>Example<br><syntaxhighlight lang="php">
/**
* Creates a random password of length $length (defaults to 12)
* @param int $length
* @return string
*/
function createPassword($lenght = 12)

/**
* Creates an HTML language drop down for survey with id $surveyId, marking $selectedLanguage as selected
* @param int $surveyId
* @param string $selectedLanguage
* @return string <select> HTML
*/
function createLanguageDropdown($surveyId, $selectedLanguage)

</syntaxhighlight>

=== Push side-effects up in the stack trace ===

This one is a bit abstract.

First, what is a '''side-effect'''? In short, it's anything that happens in a function that ''is not'' described by the ''relation'' between function arguments and output.

Another way to phrase it is, that a side-effect is anything that is not always the same for the given input to a function; a function without any side-effects will always return the same result if it gets the same input.

'''Examples:'''

<syntaxhighlight lang="php">
// gT accesses the file system and will return different result depending on what's in the translation files
function gT($sToTranslate, $sEscapeMode = 'html', $sLanguage = null);

// If $sText and $sEscapeMode is always the same, quoteText() will always return the same string.
function quoteText($sText, $sEscapeMode = 'html');
</syntaxhighlight>

A function with no side-effects is called '''pure'''. A function that is guaranteed to always return (no exceptions, no errors, no warnings, no division by zero) is called '''total'''.

It's a good thing if functions in a code-base ''either'' have side-effects, ''or'' return a result. Not both. This is called [https://en.wikipedia.org/wiki/Command%E2%80%93query_separation command-query separation].

Examples of side-effects:

* Database or file access
* Echo, or write to stdout or stderr
* Randomization

Why does this matter? Because side-effects make testing harder! '''If you have side-effects, you cannot create unit tests''', ''unless'' those side-effects can be mocked. If not, you need integrity tests with database setup or more. The more side-effects you have in a function, the more mocking is required to unit test it.

So, one solution to this is to move side-effects higher up in the stack trace, that is, move them to the calling code.

'''Example:'''

<syntaxhighlight lang="php">
function getSurveyInfo(int $surveyid, string $languagecode = '', boolean $force = false): array;
</syntaxhighlight>

Since this function takes $surveyid, we know it will probably query the database. Quering the database is a side-effect, and thus it requires a database scaffold for the test (or mocking, but the database connection is not injected, so there's no way to do it). One simple solution is to lift the side-effect out and pass in a Survey object instead:

<syntaxhighlight lang="php">
function getSurveyInfo(Survey $survey, string $languagecode = '', boolean $force = false): array;
</syntaxhighlight>

Much better! The side-effect of calling the database now happens ''before'' the function call. Now we can either mock a Survey object, or make an imitating stub for our test.

Reading the function body, there is in fact another database access, but since this is a relation to the Survey model, it could easily be moved out too. We've just made a function testable! Hooray!

This principle is rephrased in an architectural settings as [https://github.com/kbilsted/Functional-core-imperative-shell/blob/master/README.md functional core, imperative shell]. This architecture helps you get a good ratio between fast unit tests and slower integrity tests.

Moving side-effects up makes sure we can have a healthy ratio between integrity tests with scripted browser, and unit-tests; maybe around 20-80.

=== Function name ===

* The function name should tell you '''what''' it does; docs should tell you '''why''' (if this information is not obvious). '''How''' is described by the code itself (hopefully, but can in some cases be relevant to document).
* Function name can often be '''verb [+ adjective] + noun''', like "createFieldmap", "quoteText", "getRelativePath"
* Prefix with "is" for boolean functions

todo: difference between create, get, fetch, generate, ...

'''Good examples:'''

* createPassword() - One verb, one noun - clear
* isCaptchaEnabled() - Using "is" signifies it returns boolean; clear purpose
* getFullResponseTable() - Verb, adjective, noun - but is "full" needed here? Is there a non-full version of the same function?
* replaceExpressionCodes() - Pretty good, but it's obvious that more information is needed in the docblock to describe what "replace" means, and what an "expression code" is
* fixCKeditorText() - "fix" is a bit vague, but maybe best there is? Pray that docblock contains information!

'''Bad examples:'''

* languageDropdown() - No verb, doesn't tell you what it does
* rmdirr() - Two r's, looks like a typo, but the last "r" actually means "recursive"! Better: rmdir($recursive = false), rmdir or removeFolder.
* CSVUnquote() - Is CSV really the namespace? Why is the verb the second word?
* incompleteAnsFilterState() - One verb, but in the middle, or is "filter state" a noun?; why abbreviate "answer" to "ans"?
* reverseTranslateFieldNames() - Two verbs - did author mean "reverseTranslatedFieldNames"? Or "reverse and translate"? If so, it should be two functions, one for reverse and one for translate
* checkUploadedFileSizeAndRenderJson() - If you have an "and" in the function name, you should consider splitting it into two functions

'''Controversial'''

* gT() - An exception to descriptive function names; since this is used everywhere, the minimal name is motivated; maybe even name it "t()"? Still hard to read for someone who just started? But Yii uses t() too? Other frameworks use double underscore (Wordpress, Laravel) as function name.

<hr>

=== Function filename and namespace ===

If your function has dependencies or side-effects, it should be put into a class instead, in which the dependencies can be injected. Another alternative is to put the dependencies as argument in the function, although this muffles the relationship between input and output. Again, this is to increase testability.

Keep in mind that functions outside classes cannot be mocked, so only use them when you ''know'' you won't need to mock them.

todo, autoloading of functions and folder location

=== Assertions ===

NB: This is not assertions as used in unit-tests, but assertions as used to check invariants in production code.

Assertions can be used for mental checks. They are only used for internal logic - failed assertions are not supposed to be seen by the end user. For interaction with the outside world, like database or browser, exceptions should be used instead.

Assertions can be disabled in production mode and have then no runtime cost (since PHP 7).

'''Example:'''

<syntaxhighlight lang="php">
/**
* Translation helper function
*
* @param string $sToTranslate
* @param string $sEscapeMode Valid values are html (this is the default, js and unescaped)
* @param string $sLanguage
* @return string
*/
function gT($sToTranslate, $sEscapeMode = 'html', $sLanguage = null)
{
assert(is_string($sToTranslate));
assert(strlen($sToTranslate) > 0);
assert($sEscapeMode === 'html' || $sEscapeMode === 'js' || $sEscapeMode === 'unescaped');
return quoteText(Yii::t('', $sToTranslate, array(), null, $sLanguage), $sEscapeMode);
}
</syntaxhighlight>

<hr>

=== Exceptions ===

* Exceptions are used to check inputs from the outside world (browser, database, file system)
* Don't use exceptions for control flow, only when fatal errors happen that make further execution impossible
* Exceptions should have clear error messages that make them ''actionable'' - there should be a clear "next step" for the user or developer
* Never, ever, do an empty catch-block
* At the moment, we do not have an exception hierarchy in LimeSurvey

==== Alternatives to exceptions ====

Some people consider exceptions being a hidden form of "goto" which confuses the control flow of the program. They propose different other solutions:

* Return a tuple, like <code>[$result, $errorMessage]</code> where $errorMessage is null at success
* Return <code>null</code> at failure
* Tagged union result type (not yet possible in latest PHP)
* Result object

The con being that you have to manually propagate the error, where an exception can happen from anywhere in the stack trace without any other function knowing about it.

=== If-statements ===

If-statements should not be too long or hard to understand. If they are, consider factor out the checks into separate functions.

<syntaxhighlight lang="php">
if ((empty($instance->oOptions->{$attribute}))
|| (
!empty($instance->oOptions->{$attribute})
&& (
$instance->oOptions->{$attribute} === 'inherit'
|| $instance->oOptions->{$attribute} === 'I'
// NB: Do NOT use === here, it won't work with Postgresql.
|| $instance->oOptions->{$attribute} == '-1'
)
)
) {
</syntaxhighlight>

Can be shortened by factoring out method <code>isInherit</code>:

<syntaxhighlight lang="php">
if (empty($instance->options->{$attribute})
|| $this->isInherit($instance-options->{$attribute})) {
}
/**
* Returns true if $value is set to inherit
* @param mixed|null $value
* @return boolean
*/
public function isInherit($value) {
return !empty($value)
&& (
$value === 'inherit'
|| $value === 'I'
// NB: Do NOT use === here, it won't work with Postgresql.
|| $value == '-1'
);
}
</syntaxhighlight>

And one more time by using a variable for the value:

<syntaxhighlight lang="php">
$value = $instance->options->{$attribute};
if (empty($value) || $this->isInherit($value)) {
}
</syntaxhighlight>

More clear, right? "If it's empty or set to inherit, do this and that."

=== Variables ===

Descriptive naming.

* Follow PSR-12 - no underscore, use camelCaseLikeThis
* Variables of ActiveRecord classes can have same name as the class, like "$survey" or "$question"
* Add -s for plural when it's a list of items: "$surveys", "$questions"
* Never include "array" or "list" in variable names - using plural is enough (for lists, not for associative arrays - see below)
* The ''context'' of the function helps with variable naming, e..g "$name" might be fine in a function about questions; this is extra helpful when functions are short!
* When a function is short, it's much easier to figure out variable meaning based on context
* $qid, $gid, and $sid are so established in the code-base that they could be considered OK
* The -data suffix means "blob of stuff", only use it when needed, like with $viewData
* Use $result when baking a return value; add its exact type as @var annotation (worst possible name, acceptable but anything with more meaning is better)

Not so good:

<syntaxhighlight lang="php">
$result = LabelSet::model()->findAll();
</syntaxhighlight>

Better with model name and -s for plural:

<syntaxhighlight lang="php">
$labelSets = LabelSet::model()->findAll();
</syntaxhighlight>

* Do not use Hungarian notation (prefix with "type"), but instead <code>/** @var */</code> annotations - these can be checked automatically and will then be enforced to be correct, unlike Hungarian notation which can "rot"

<syntaxhighlight lang="php">
/** string[] An array of strings with 0-n elements */
$allFields = [];
</syntaxhighlight>

Psalm can infer types if the function documentation is enough. The strictness can be adjusted. Not all variables will need @var annotation, the tool will warn you when it's confused.

* Data that is sent to views as associative arrays will be:

<syntaxhighlight lang="php">
/** @var array Can be basically anything :( Better would be data-transfer objects or more precise notation */
$data = [];
// Maybe more clear as $viewData? Discuss.
</syntaxhighlight>

You can be more precise when you specify which type of array you're writing:

<syntaxhighlight lang="php">
/** @var array<string, string> This means the array key is string, and the array value is also string */
$data = [];
$data['name'] = 'Olle';
$data['occupation'] = 'Developer';
$data['age'] = 38; // ERROR! Value must be string.
</syntaxhighlight>

For more info about array type notation, see the [https://psalm.dev/docs/annotating_code/type_syntax/array_types/ Psalm documentation].

Some smaller examples:

<syntaxhighlight lang="php">
$theme = App()->request->getPost('theme'); // Should be $themeType - $theme looks like a model/AR
$gridid === 'questionthemes-grid'; // Should be $gridId with capital "I", since it's two words in English
$delete = Yii::app()->request->getParam('delete'); // Tuff one - $delete is ok? Thoughts?
$files = json_decode(stripslashes($sJSON), true); // $file is a resource, $files an array of resources, this is $fileData perhaps?
$valid_extensions_array = explode(",", $aAttributes['allowed_filetypes']); // Should be $validExtensionTypes
$language = Yii::app()->session['survey_' . $surveyid]['s_lang']; // TODO: Should this be a value class? Then Language::make(...);
$surveyInfo = getSurveyInfo($surveyId, $language); // OK, BUT should be a separate DTO!
$fieldMap = createFieldMap($survey, 'short', false, false, $language); // Same, make a DTO
$cquestions = array(); // What's "c"? Method name is getChildQuestions and $questions is an argument - better with $childQuestions?
</syntaxhighlight>

Links:

[https://www.approxion.com/capital-offenses-how-to-handle-abbreviations-in-camelcase/ How to Handle Abbreviations in CamelCase]

[https://stackoverflow.com/questions/15526107/acronyms-in-camelcase Acronyms in CamelCase]

=== Looping ===

* The bodies of foreach-loops are often a good candidate to factor out into separate functions.

'''Example:'''

<syntaxhighlight lang="php">
foreach ($questions as $question) {
processQuestion($question);
}
</syntaxhighlight>

Note the variable naming from plural to singular.

* Loop indexing should be named i, j, k etc.

'''Example:'''

<syntaxhighlight lang="php">
for ($i = 0; $i < $length; $i++) {
for ($j = 0; $j < $otherLength; $j++) {
// ...
}
}
</syntaxhighlight>

<hr>

=== Function composition ===

todo, "doThisAndThat" --> "doThis(doThat())"

=== Cases ===

<syntaxhighlight lang="php">
/**
* This function generates an array containing the fieldcode, and matching data in the same order as the activate script
*
* @param Survey $survey Survey ActiveRecord model
* @param string $style 'short' (default) or 'full' - full creates extra information like default values
* @param boolean $force_refresh - Forces to really refresh the array, not just take the session copy
* @param bool|int $questionid Limit to a certain qid only (for question preview) - default is false
* @param string $sLanguage The language to use
* @param array $aDuplicateQIDs
* @return array
*/
function createFieldMap($survey, $style = 'short', $force_refresh = false, $questionid = false, $sLanguage = '', &$aDuplicateQIDs = array())
</syntaxhighlight>

'''Good:'''

* Name is verb and noun
* Each argument is documented (almost)

'''Bad:'''

* Returns "array", which can be anything. A separate class for "Fieldmap" would be better.
* Not clear if it should be "createFieldMap" or "createFieldmap" - is "fieldmap" one word or two?
* Very many boolean arguments. Should probably be a class with methods like <code>$fieldmapCreator->setForceRefresh(true);</code> instead.
* Too long.
* Doesn't elaborate on what "fieldmap" really is, and does not link to any documentation about it.
* Access super-global, which makes it hard to test. Should instead return a data-transfer object, like:<br><syntaxhighlight lang="php">
$_SESSION['fieldmap'] = createFieldMap(...);
</syntaxhighlight>
* Has no test
* Mixes Hungarian notation with non-Hungarian notation in the argument list

== Defensive programming and error handling ==

* '''Fail hard, fail early'''. The earlier the program crashes when something is wrong, the lower is the probability that you'll end up with corrupt data in the database that will later require manual labor to correct.
* Fail with '''actionable information'''
* Check input to functions and throw <code>InvalidArgumentException</code> if it violates the function's pre-conditions
* Use assert for class-internal invariants
* Use assert to make assumptions explicit for the reader

== Documentation ==

=== PHPDoc ===

* All functions must have a proper docblock
* The first line of the docblock should describe the relation between ''all'' the input arguments and the output of the function in a single sentence
* Each parameter must have the correct type
* Don't use <code>array</code> as type if it's a list of object - instead, use <code>[]</code> like so: <code>Survey[]</code> for a list of surveys

=== Technical documentation ===

todo, UML, scenarios, use-cases

== The PHP of yesterday ==

Old idioms and habits that should be abandoned.

* Don't use associative arrays, almost never. Data-transfer objects have multiple benefits: they are clearly structured, can be documented, can enforce invariants. There's ''no'' performance overhead of objects compared to arrays in modern PHP.
* Objects are already passed by reference; arrays are value types
* Use <code>[]</code> instead of <code>array()</code>
* Hungarian notation was useful before static analysis existed for PHP. These days it's better to use something that can be checked automatically: docblock @param and inline @var annotations.

== The PHP of tomorrow ==

todo

Union tags

Short functions

Match expressions

Partial application, pipe

== Security ==

todo

XSS

Database injection

Permissions and roles

== Performance ==

todo

Loading too many rows into PHP models

== Testing ==

todo

QA

PHPUnit

TDD

Mocks, can't mock functions, static methods, mocking as a DSL, PHPUnit mocking tools

Pure functions, referential transparency, side-effects

Unit, functional, integration

Don't test the framework; don't test PHP

Makes sure the function or class lives up to its specification; make sure it will ''always'' live up to its specification, even in the future, to avoid regressions.

== Static analysis ==

<code>php -l</code>, CodeSniffer, Mess Detector, Psalm

== Database design ==

todo

== JavaScript ==

todo

classes, functions, components, tests

== CSS ==

todo

== HTML ==

todo

== Feedback ==

=== "Why do I have to refactor code that works?" ===

todo, Sadly, it's not enough for the code to live up to the current specification and requirements, it must also be protected against future changes, regressions. Adding tests is the best way for this. Lots of people might read and change the LimeSurvey code the next 5-10 years. The test suite creates a security layer to make sure the specification is fulfilled even as the code changes.

Tests are not a magical solution, however. It does not protect us against other degradation of the code quality, like classes gaining too much responsibility (too many methods, unrelated methods, too many properties).

=== "What's the correct ratio between integrity tests and unit tests?" ===

todo, Don't know. Different pros and cons.

* Unit-test can be run in parallel and are faster
* Unit-tests don't need setup and teardown

Cons of unit-tests is that they need a bigger effort on the side of the developer to make them possible, for example injecting the dependencies properly to enable mocking, or lifting side-effects up in the stack trace.

=== How to disagree ===

All rules can be broken. To break a rule, you should reason in terms of risk and the assumptions used in this guide.

'''Assumptions:'''

# Regressions are the biggest technical risk for LimeSurvey the last five years (2021)
# Automated tests are the best risk mitigation technique against regressions

'''Possible disagreement:'''

# A certain piece of code has very low ''probability'' of regressions (maybe we "know" no one else will every touch or change it?)
# Regression in a certain piece of code would have very low ''impact''

== Architectural Decision Records ==

todo

https://adr.github.io/

== Resources ==

todo

Books, links, videos

Code quality guide

2021-05-19T10:13:43Z

Olle: /* Defensive programming and error handling */

DRAFT

== Prologue ==

# '''Be risk aware'''. Too good code can be a business risk (slow to write, maybe over-designed). Too sloppy code can also be a business risk (hard to maintain and understand). You have to find a balance that is adapted to the current situation and risk analysis, in which code quality becomes a '''risk mitigation''' technique among others.
# '''Be humble'''. LimeSurvey was made by developers from all over the world, with different age, education and experience. Your code might be read by a completely different team ten years from now, in the same way you are now reading code by developers that no longer work with us, but which work pays our rent.
# '''Performance matters sometimes''', and shouldn't be disregarded completely. In particular, database queries using the ORM and ActiveRecord can be problematic. Some surveys have thousands of questions and hundreds of thousands of responses. Fast response time is also important for a fluid user experience.
# '''It's harder to read code than to write code'''. Don't choose patterns that are easy or fast to write, but that are easy to read.
# Make your code '''communicate intent'''.
# It's easy to forget '''cross-cutting concerns''' like translation and security. Keep a mental note.
# '''Stress affects code quality''' and your risk behaviour. If your stress level is too high to write code with proper quality, take a step back and discuss it with your boss, or you'll push problems to the future.

== Quality ==

The purpose of this guide is to increase the quality of the LimeSurvey code-base. What is quality? Which aspects of quality can be measured? Which kind of company culture gives rise to appropriate code quality?

It's usually easier to get along what is "bad" code than what's "best" code. Blacklist instead of whitelist?

Quality attributes related to code quality:

* Readability
* Testability
* Maintainability
* Performance
* Security
* Reliability

Can not increase all at the same time - performance vs readability.

It's better to avoid emotional language when describing code quality, like "clean" or "dirty". Be precise, objective and suggest solutions.

Idiomatic code is more readable than non-idiomatic code. What's idiomatic depends on which context or domain you work in. We work in PHP and web application development, and have other idioms than in, say, functional or hardware-close programming.

Some code are "hot spots" - changed often. Those parts should require higher quality than other code.

== Risk ==

todo

Couple of different definition of risk:

* Tuple of probability and severity
* Triple of consequence, uncertainty and knowledge base

Possible risks related to LimeSurvey (technical or business):

* Data loss
* Regressions
* Bad UI (higher churn-rate for users)
* Hard to maintain (reduced sprint velocity)
*

How know which is the biggest risk? How many risks can be approached at once?

Connection to architecture. Risk --> quality attributes --> architectural decisions.

usability a business risk - hard to use or understand, people will choose another tool

risks relevant when fixing bugs

risks relevant when adding new features (lack of testing, wrong requirements, scope creep)

risks relevant when refactoring (regressions)

unit tests and QA as risk mitigation

partial deployment, alpha/beta/rc, risk communication

software rot, design pattern rot/grime, software evolution

rot = non-pattern related code

testing by community, bug fixing by community

== Modules ==

There's no inherit module functionality in PHP, but Yii has a module system. Libraries can be seen as a module system.

Examples of implicit modules in LimeSurvey:

* Front-end (survey taking)
* Back-end (survey design)
* Survey theme editing
* Expression manager
* Plugin system

In the future, they need to be separated and implemented more clearly as whatever Yii 3 module system is in use.

Some data models are common for all modules, e.g. surveys and users. Can have a "Common" module for such data.

todo, relation to Yii config system

== Classes ==

* Avoid empty OOP ceremony, like defining getters and setters for all properties. Might as well make them public, ''unless'' they have invariants that need to be upheld, e.g. "this number is always between 1 and 10" or "this string is maximum length 20".
* Almost always avoid static methods. They cannot be mocked. One exception is (possibly) factory methods (Foo::make(...)).
* Inject all dependencies. This will make sure the class can be unit-tested (unit-tests have several benefits over integrity tests - they can be run in parallel and don't require any setup and teardown)
* A second way to achieve testability is to factor out the methods that access the dependencies

todo, state vs behaviour, state vs dependencies

=== OOP design ===

Start from top-down, with domain, behaviour, interaction between objects, database design, pseudo-code if needed. Can also include scenarios, use-cases and UML diagrams.

Object reification - not only domain models, but also domain actions, relations and activities can be objects, e.g. a class ActivateSurvey or ExportSurvey.

Hierarchy depth should be kept reasonable shallow to avoid conflicts between methods, spooky action at a distance. Compare with Yii 3, where controllers no longer inherit anything.

Some people advocate for composition instead of inheritance. Lots of blog posts available for more info.

Multiple inheritance is done with traits in PHP. Use-case: ActiveRecords where some but not all models support encryption.

==== Shape design problem ====

Imagine you have three shapes: Point, rectangle and circle, with the following properties:

* Point: int x, int y
* Rectangle: Point bottomLeft, Point topRight
* Circle: Point center, int radius

Add two behaviours: area(), draw(surface).

* Cohesion: A class (or module) should be responsible for one thing only
* Coupling: You should be able to ''isolate change'' in the system
* Encapsulation: Classes shouldn’t share internal representation
* Polymorphism: The design should be based on interfaces

Questions to consider:

* How easy would it be to move to a 3D representation?
* How easy would it be to add a new shape, say, triangle?
* How easy would it be to add a new behaviour to all shapes, like save/load from a SQL database?
* Which classes ''change together''?

Keep polymorphism and encapsulation - all properties are private.

Example pseudo-code:

forall shapes as shape, do shape.draw(surface)

forall shapes as shape, do surface.draw(shape) (where shape.getDrawData(), or shape.getPath())

=== Software evolution ===

Design rot after time - how to keep it tight? (Grime.)

Architecture design roundtrip, based on risk.

todo

==== Grime and rot ====

design pattern rot --> lose behaviour relevant for pattern (active record without db connection)

design patter grime --> add behaviour irrelevant for pattern (active record that's also a singleton)

==== Class cohesion ====

[[File:cohesion.png]]

==== Modular coupling ====

[[File:coupling.png]]

Clearer boundaries between classes and modules make it easier to isolate change.

=== State ===

Heuristics to consider but not follow slavishly.

Keep a clear separation between classes with state and classes with no state.

Classes with state should not have dependencies with IO (it's OK to depend on classes in the same application layer, e.g. other DTO classes), and vice versa. ActiveRecord is an example which violates this principle.

class Survey
// Confusion - first params are domain state, last a resource
__construct(id, language, dbConnection)

If a method does not call "this", should it instead be outside the class? A separate class or function, maybe.

todo, elaborate

=== Types of classes ===

Different categories of classes:

* Entity (domain class; has state and validation behaviour)
* Resource (database connection, file, curl, logger; state is in the resource (open, closed))
* Repository classes (database interaction, like splitting ActiveRecord in two parts: Entity class and database interaction)
* DAO, data access object (similar to resource)
* Builders (e.g. query builder, HTML message builder)
* Data-transfer object (no behaviour; pass to views to have better documentation and intent than associative arrays)
* Value classes (e.g. Email address to wrap email string around)
* Command object (e.g. SurveyActivator)
* Helper (no state; e.g. QuestionAttributeHelper to bake attributes into different formats used by the views)
* Wrapper

todo, immutability, possible with private properties that are set in the constructor,

todo: command-query separation for classes?

todo: dependencies between layers, dependencies to the framework

todo, pure vs effectful classes

=== Types of classes in LimeSurvey ===

* ActiveRecord, used to communicate with the database, and should not do ''anything'' else
* Controllers, used for glue code; should not contain business-logic (also CLI controllers)
* Helper functions (not classes, yet...), should be short and obey command-query separation (TODO: Long functions should be separated into command objects or service classes); todo: should not have any dependencies?
* Helper classes, similar to helper functions but have dependencies that need to be mocked during tests; should not have any state
* Service classes, contains logic related to a clear and separate task, like create or import survey
* Question render classes, contains logic related to how questions are rendered (TODO: Need better separation between state and logic and more clear design); similar to widgets
* Plugin classes, using the plugin event system
* Widgets, containing HTML logic for custom HTML widgets
* HTML helpers (Yii)
* Customizations to the Yii framework by inheritance
* Unit and functional test classes

A couple of classes contain only data, like LsDefaultDataSet.

todo, no difference between state property and dependency property in OOP

=== What is "glue code"? ===

todo

Putting the pieces together, e.g. service class A need data from model B, fetch it and run.

todo, add example

=== "Where do I cut?" ===

Separation of concerns, but which concerns and which type of separation? Command-query (function core, imperative shell) is one type of separation. Other separation between layers, e.g. logic layer and data persistency layer (similar in thought).

Other separation, that one class should have a clear purpose. A design pattern should only implement ''one'' pattern, not multiple, and not half a pattern.

There's a problem with "helper" or "manager" classes that they can grow indefinitely, but might be better than nothing. Example when moving business logic out of ActiveRecord class to a helper class it can sometimes hard to be more specific than "helper".

=== Size ===

A class should have a single and clear purpose; compare with [https://en.wikipedia.org/wiki/SOLID SOLID].

=== Class name ===

* ActiveRecord classes are named after the database table they are bound to, but with singular instead of plural. E.g. table "lime_users" have model "User".
* Command classes are named after what they ''do'' and imperatively, e.g. CreateSurvey
* Helper classes should probably be named as specific as possible when possible, to avoid them from growing too big
* Follow the naming tradition of the framework with regard to controllers, e.g. UserController or UserAdministrationController.
* Class properties of ActiveRecord classes will follow the naming of the database, using underscore instead of camel case (and ActiveRecord classes should have ''no'' other properties than those (excluding the database connection injected by the framework))

== Functions ==

Functions are one of the fundamental building blocks of programming, so it's important to get it right.

Functions that are part of a class are called "methods", if you want to be formal.

Different types of functions in PHP:

* Functions (not attached to a class)
* Methods (attached to class)
* Anonymous functions (does not capture scope automatically)
* Short functions (does capture scope automatically)

I'm using "function" as a word for all types of functions in PHP below.

<hr>

=== Size ===

* A function should be short enough to be completely readable on one screen, approx 60 lines at most
* A function should not have too many arguments; if you have five or more, consider making it a class instead
* If a function is growing too big, it might be better to create a class instead or split it into several functions (if both functions have '''common state''', a class might be better, unless you want to pass around '''explicit state''')

=== Contract ===

* A function has a contract with its surrounding environment:
** Pre-condition: What needs to be true before the function is executed
** Post-condition: What will be true after the function has returned
* The function contract can be checked with assertions (internal invariants) or exceptions (outside world); see below
* Another good way is to use unit-tests to make sure the function's contract remains stable through changes
* The first line in the docblock should be one sentence describing the relation between function arguments and its output<br>Example<br><syntaxhighlight lang="php">
/**
* Creates a random password of length $length (defaults to 12)
* @param int $length
* @return string
*/
function createPassword($lenght = 12)

/**
* Creates an HTML language drop down for survey with id $surveyId, marking $selectedLanguage as selected
* @param int $surveyId
* @param string $selectedLanguage
* @return string <select> HTML
*/
function createLanguageDropdown($surveyId, $selectedLanguage)

</syntaxhighlight>

=== Push side-effects up in the stack trace ===

This one is a bit abstract.

First, what is a '''side-effect'''? In short, it's anything that happens in a function that ''is not'' described by the ''relation'' between function arguments and output.

Another way to phrase it is, that a side-effect is anything that is not always the same for the given input to a function; a function without any side-effects will always return the same result if it gets the same input.

'''Examples:'''

<syntaxhighlight lang="php">
// gT accesses the file system and will return different result depending on what's in the translation files
function gT($sToTranslate, $sEscapeMode = 'html', $sLanguage = null);

// If $sText and $sEscapeMode is always the same, quoteText() will always return the same string.
function quoteText($sText, $sEscapeMode = 'html');
</syntaxhighlight>

A function with no side-effects is called '''pure'''. A function that is guaranteed to always return (no exceptions, no errors, no warnings, no division by zero) is called '''total'''.

It's a good thing if functions in a code-base ''either'' have side-effects, ''or'' return a result. Not both. This is called [https://en.wikipedia.org/wiki/Command%E2%80%93query_separation command-query separation].

Examples of side-effects:

* Database or file access
* Echo, or write to stdout or stderr
* Randomization

Why does this matter? Because side-effects make testing harder! '''If you have side-effects, you cannot create unit tests''', ''unless'' those side-effects can be mocked. If not, you need integrity tests with database setup or more. The more side-effects you have in a function, the more mocking is required to unit test it.

So, one solution to this is to move side-effects higher up in the stack trace, that is, move them to the calling code.

'''Example:'''

<syntaxhighlight lang="php">
function getSurveyInfo(int $surveyid, string $languagecode = '', boolean $force = false): array;
</syntaxhighlight>

Since this function takes $surveyid, we know it will probably query the database. Quering the database is a side-effect, and thus it requires a database scaffold for the test (or mocking, but the database connection is not injected, so there's no way to do it). One simple solution is to lift the side-effect out and pass in a Survey object instead:

<syntaxhighlight lang="php">
function getSurveyInfo(Survey $survey, string $languagecode = '', boolean $force = false): array;
</syntaxhighlight>

Much better! The side-effect of calling the database now happens ''before'' the function call. Now we can either mock a Survey object, or make an imitating stub for our test.

Reading the function body, there is in fact another database access, but since this is a relation to the Survey model, it could easily be moved out too. We've just made a function testable! Hooray!

This principle is rephrased in an architectural settings as [https://github.com/kbilsted/Functional-core-imperative-shell/blob/master/README.md functional core, imperative shell]. This architecture helps you get a good ratio between fast unit tests and slower integrity tests.

Moving side-effects up makes sure we can have a healthy ratio between integrity tests with scripted browser, and unit-tests; maybe around 20-80.

=== Function name ===

* The function name should tell you '''what''' it does; docs should tell you '''why''' (if this information is not obvious). '''How''' is described by the code itself (hopefully, but can in some cases be relevant to document).
* Function name can often be '''verb [+ adjective] + noun''', like "createFieldmap", "quoteText", "getRelativePath"
* Prefix with "is" for boolean functions

todo: difference between create, get, fetch, generate, ...

'''Good examples:'''

* createPassword() - One verb, one noun - clear
* isCaptchaEnabled() - Using "is" signifies it returns boolean; clear purpose
* getFullResponseTable() - Verb, adjective, noun - but is "full" needed here? Is there a non-full version of the same function?
* replaceExpressionCodes() - Pretty good, but it's obvious that more information is needed in the docblock to describe what "replace" means, and what an "expression code" is
* fixCKeditorText() - "fix" is a bit vague, but maybe best there is? Pray that docblock contains information!

'''Bad examples:'''

* languageDropdown() - No verb, doesn't tell you what it does
* rmdirr() - Two r's, looks like a typo, but the last "r" actually means "recursive"! Better: rmdir($recursive = false), rmdir or removeFolder.
* CSVUnquote() - Is CSV really the namespace? Why is the verb the second word?
* incompleteAnsFilterState() - One verb, but in the middle, or is "filter state" a noun?; why abbreviate "answer" to "ans"?
* reverseTranslateFieldNames() - Two verbs - did author mean "reverseTranslatedFieldNames"? Or "reverse and translate"? If so, it should be two functions, one for reverse and one for translate
* checkUploadedFileSizeAndRenderJson() - If you have an "and" in the function name, you should consider splitting it into two functions

'''Controversial'''

* gT() - An exception to descriptive function names; since this is used everywhere, the minimal name is motivated; maybe even name it "t()"? Still hard to read for someone who just started? But Yii uses t() too? Other frameworks use double underscore (Wordpress, Laravel) as function name.

<hr>

=== Function filename and namespace ===

If your function has dependencies or side-effects, it should be put into a class instead, in which the dependencies can be injected. Another alternative is to put the dependencies as argument in the function, although this muffles the relationship between input and output. Again, this is to increase testability.

Keep in mind that functions outside classes cannot be mocked, so only use them when you ''know'' you won't need to mock them.

todo, autoloading of functions and folder location

=== Assertions ===

NB: This is not assertions as used in unit-tests, but assertions as used to check invariants in production code.

Assertions can be used for mental checks. They are only used for internal logic - failed assertions are not supposed to be seen by the end user. For interaction with the outside world, like database or browser, exceptions should be used instead.

Assertions can be disabled in production mode and have then no runtime cost (since PHP 7).

'''Example:'''

<syntaxhighlight lang="php">
/**
* Translation helper function
*
* @param string $sToTranslate
* @param string $sEscapeMode Valid values are html (this is the default, js and unescaped)
* @param string $sLanguage
* @return string
*/
function gT($sToTranslate, $sEscapeMode = 'html', $sLanguage = null)
{
assert(is_string($sToTranslate));
assert(strlen($sToTranslate) > 0);
assert($sEscapeMode === 'html' || $sEscapeMode === 'js' || $sEscapeMode === 'unescaped');
return quoteText(Yii::t('', $sToTranslate, array(), null, $sLanguage), $sEscapeMode);
}
</syntaxhighlight>

<hr>

=== Exceptions ===

* Exceptions are used to check inputs from the outside world (browser, database, file system)
* Don't use exceptions for control flow, only when fatal errors happen that make further execution impossible
* Exceptions should have clear error messages that make them ''actionable'' - there should be a clear "next step" for the user or developer
* Never, ever, do an empty catch-block
* At the moment, we do not have an exception hierarchy in LimeSurvey

==== Alternatives to exceptions ====

Some people consider exceptions being a hidden form of "goto" which confuses the control flow of the program. They propose different other solutions:

* Return a tuple, like <code>[$result, $errorMessage]</code> where $errorMessage is null at success
* Return <code>null</code> at failure
* Tagged union result type (not yet possible in latest PHP)
* Result object

The con being that you have to manually propagate the error, where an exception can happen from anywhere in the stack trace without any other function knowing about it.

=== If-statements ===

If-statements should not be too long or hard to understand. If they are, consider factor out the checks into separate functions.

<syntaxhighlight lang="php">
if ((empty($instance->oOptions->{$attribute}))
|| (
!empty($instance->oOptions->{$attribute})
&& (
$instance->oOptions->{$attribute} === 'inherit'
|| $instance->oOptions->{$attribute} === 'I'
// NB: Do NOT use === here, it won't work with Postgresql.
|| $instance->oOptions->{$attribute} == '-1'
)
)
) {
</syntaxhighlight>

Can be shortened by factoring out method <code>isInherit</code>:

<syntaxhighlight lang="php">
if (empty($instance->options->{$attribute})
|| $this->isInherit($instance-options->{$attribute})) {
}
/**
* Returns true if $value is set to inherit
* @param mixed|null $value
* @return boolean
*/
public function isInherit($value) {
return !empty($value)
&& (
$value === 'inherit'
|| $value === 'I'
// NB: Do NOT use === here, it won't work with Postgresql.
|| $value == '-1'
);
}
</syntaxhighlight>

And one more time by using a variable for the value:

<syntaxhighlight lang="php">
$value = $instance->options->{$attribute};
if (empty($value) || $this->isInherit($value)) {
}
</syntaxhighlight>

More clear, right? "If it's empty or set to inherit, do this and that."

=== Variables ===

Descriptive naming.

* Follow PSR-12 - no underscore, use camelCaseLikeThis
* Variables of ActiveRecord classes can have same name as the class, like "$survey" or "$question"
* Add -s for plural when it's a list of items: "$surveys", "$questions"
* Never include "array" or "list" in variable names - using plural is enough (for lists, not for associative arrays - see below)
* The ''context'' of the function helps with variable naming, e..g "$name" might be fine in a function about questions; this is extra helpful when functions are short!
* When a function is short, it's much easier to figure out variable meaning based on context
* $qid, $gid, and $sid are so established in the code-base that they could be considered OK
* The -data suffix means "blob of stuff", only use it when needed, like with $viewData
* Use $result when baking a return value; add its exact type as @var annotation (worst possible name, acceptable but anything with more meaning is better)

Not so good:

<syntaxhighlight lang="php">
$result = LabelSet::model()->findAll();
</syntaxhighlight>

Better with model name and -s for plural:

<syntaxhighlight lang="php">
$labelSets = LabelSet::model()->findAll();
</syntaxhighlight>

* Do not use Hungarian notation (prefix with "type"), but instead <code>/** @var */</code> annotations - these can be checked automatically and will then be enforced to be correct, unlike Hungarian notation which can "rot"

<syntaxhighlight lang="php">
/** string[] An array of strings with 0-n elements */
$allFields = [];
</syntaxhighlight>

Psalm can infer types if the function documentation is enough. The strictness can be adjusted. Not all variables will need @var annotation, the tool will warn you when it's confused.

* Data that is sent to views as associative arrays will be:

<syntaxhighlight lang="php">
/** @var array Can be basically anything :( Better would be data-transfer objects or more precise notation */
$data = [];
// Maybe more clear as $viewData? Discuss.
</syntaxhighlight>

You can be more precise when you specify which type of array you're writing:

<syntaxhighlight lang="php">
/** @var array<string, string> This means the array key is string, and the array value is also string */
$data = [];
$data['name'] = 'Olle';
$data['occupation'] = 'Developer';
$data['age'] = 38; // ERROR! Value must be string.
</syntaxhighlight>

For more info about array type notation, see the [https://psalm.dev/docs/annotating_code/type_syntax/array_types/ Psalm documentation].

Some smaller examples:

<syntaxhighlight lang="php">
$theme = App()->request->getPost('theme'); // Should be $themeType - $theme looks like a model/AR
$gridid === 'questionthemes-grid'; // Should be $gridId with capital "I", since it's two words in English
$delete = Yii::app()->request->getParam('delete'); // Tuff one - $delete is ok? Thoughts?
$files = json_decode(stripslashes($sJSON), true); // $file is a resource, $files an array of resources, this is $fileData perhaps?
$valid_extensions_array = explode(",", $aAttributes['allowed_filetypes']); // Should be $validExtensionTypes
$language = Yii::app()->session['survey_' . $surveyid]['s_lang']; // TODO: Should this be a value class? Then Language::make(...);
$surveyInfo = getSurveyInfo($surveyId, $language); // OK, BUT should be a separate DTO!
$fieldMap = createFieldMap($survey, 'short', false, false, $language); // Same, make a DTO
$cquestions = array(); // What's "c"? Method name is getChildQuestions and $questions is an argument - better with $childQuestions?
</syntaxhighlight>

Links:

[https://www.approxion.com/capital-offenses-how-to-handle-abbreviations-in-camelcase/ How to Handle Abbreviations in CamelCase]

[https://stackoverflow.com/questions/15526107/acronyms-in-camelcase Acronyms in CamelCase]

=== Looping ===

* The bodies of foreach-loops are often a good candidate to factor out into separate functions.

'''Example:'''

<syntaxhighlight lang="php">
foreach ($questions as $question) {
processQuestion($question);
}
</syntaxhighlight>

Note the variable naming from plural to singular.

* Loop indexing should be named i, j, k etc.

'''Example:'''

<syntaxhighlight lang="php">
for ($i = 0; $i < $length; $i++) {
for ($j = 0; $j < $otherLength; $j++) {
// ...
}
}
</syntaxhighlight>

<hr>

=== Function composition ===

todo, "doThisAndThat" --> "doThis(doThat())"

=== Cases ===

<syntaxhighlight lang="php">
/**
* This function generates an array containing the fieldcode, and matching data in the same order as the activate script
*
* @param Survey $survey Survey ActiveRecord model
* @param string $style 'short' (default) or 'full' - full creates extra information like default values
* @param boolean $force_refresh - Forces to really refresh the array, not just take the session copy
* @param bool|int $questionid Limit to a certain qid only (for question preview) - default is false
* @param string $sLanguage The language to use
* @param array $aDuplicateQIDs
* @return array
*/
function createFieldMap($survey, $style = 'short', $force_refresh = false, $questionid = false, $sLanguage = '', &$aDuplicateQIDs = array())
</syntaxhighlight>

'''Good:'''

* Name is verb and noun
* Each argument is documented (almost)

'''Bad:'''

* Returns "array", which can be anything. A separate class for "Fieldmap" would be better.
* Not clear if it should be "createFieldMap" or "createFieldmap" - is "fieldmap" one word or two?
* Very many boolean arguments. Should probably be a class with methods like <code>$fieldmapCreator->setForceRefresh(true);</code> instead.
* Too long.
* Doesn't elaborate on what "fieldmap" really is, and does not link to any documentation about it.
* Access super-global, which makes it hard to test. Should instead return a data-transfer object, like:<br><syntaxhighlight lang="php">
$_SESSION['fieldmap'] = createFieldMap(...);
</syntaxhighlight>
* Has no test
* Mixes Hungarian notation with non-Hungarian notation in the argument list

== Defensive programming and error handling ==

* '''Fail hard, fail early'''. The earlier the program crashes when something is wrong, the lower is the probability that you'll end up with corrupt data in the database that will later require manual labor to correct.
* Fail with '''actionable information'''
* Check input to functions and throw <code>InvalidArgumentException</code> if it violates the function's pre-conditions
* Use assert for class-internal invariants
* Use assert to make assumptions explicit for the reader

== Documentation ==

=== PHPDoc ===

* All functions must have a proper docblock
* The first line of the docblock should describe the relation between ''all'' the input arguments and the output of the function in a single sentence
* Each parameter must have the correct type
* Don't use <code>array</code> as type if it's a list of object - instead, use <code>[]</code> like so: <code>Survey[]</code> for a list of surveys

=== Technical documentation ===

todo, UML, scenarios, use-cases

== The PHP of yesterday ==

Old idioms and habits that should be abandoned.

* Don't use associative arrays, almost never. Data-transfer objects have multiple benefits: they are clearly structured, can be documented, can enforce invariants. There's ''no'' performance overhead of objects compared to arrays in modern PHP.
* Objects are already passed by reference; arrays are value types
* Use <code>[]</code> instead of <code>array()</code>
* Hungarian notation was useful before static analysis existed for PHP. These days it's better to use something that can be checked automatically: docblock @param and inline @var annotations.

== The PHP of tomorrow ==

todo

Union tags

Short functions

Match expressions

== Security ==

todo

XSS

Database injection

Permissions and roles

== Performance ==

todo

Loading too many rows into PHP models

== Testing ==

todo

QA

PHPUnit

TDD

Mocks, can't mock functions, static methods, mocking as a DSL, PHPUnit mocking tools

Pure functions, referential transparency, side-effects

Unit, functional, integration

Don't test the framework; don't test PHP

Makes sure the function or class lives up to its specification; make sure it will ''always'' live up to its specification, even in the future, to avoid regressions.

== Static analysis ==

<code>php -l</code>, CodeSniffer, Mess Detector, Psalm

== Database design ==

todo

== JavaScript ==

todo

classes, functions, components, tests

== CSS ==

todo

== HTML ==

todo

== Feedback ==

=== "Why do I have to refactor code that works?" ===

todo, Sadly, it's not enough for the code to live up to the current specification and requirements, it must also be protected against future changes, regressions. Adding tests is the best way for this. Lots of people might read and change the LimeSurvey code the next 5-10 years. The test suite creates a security layer to make sure the specification is fulfilled even as the code changes.

Tests are not a magical solution, however. It does not protect us against other degradation of the code quality, like classes gaining too much responsibility (too many methods, unrelated methods, too many properties).

=== "What's the correct ratio between integrity tests and unit tests?" ===

todo, Don't know. Different pros and cons.

* Unit-test can be run in parallel and are faster
* Unit-tests don't need setup and teardown

Cons of unit-tests is that they need a bigger effort on the side of the developer to make them possible, for example injecting the dependencies properly to enable mocking, or lifting side-effects up in the stack trace.

=== How to disagree ===

All rules can be broken. To break a rule, you should reason in terms of risk and the assumptions used in this guide.

'''Assumptions:'''

# Regressions are the biggest technical risk for LimeSurvey the last five years (2021)
# Automated tests are the best risk mitigation technique against regressions

'''Possible disagreement:'''

# A certain piece of code has very low ''probability'' of regressions (maybe we "know" no one else will every touch or change it?)
# Regression in a certain piece of code would have very low ''impact''

== Architectural Decision Records ==

todo

https://adr.github.io/

== Resources ==

todo

Books, links, videos

Code quality guide

2021-05-19T10:12:48Z

Olle: /* Exceptions */

DRAFT

== Prologue ==

# '''Be risk aware'''. Too good code can be a business risk (slow to write, maybe over-designed). Too sloppy code can also be a business risk (hard to maintain and understand). You have to find a balance that is adapted to the current situation and risk analysis, in which code quality becomes a '''risk mitigation''' technique among others.
# '''Be humble'''. LimeSurvey was made by developers from all over the world, with different age, education and experience. Your code might be read by a completely different team ten years from now, in the same way you are now reading code by developers that no longer work with us, but which work pays our rent.
# '''Performance matters sometimes''', and shouldn't be disregarded completely. In particular, database queries using the ORM and ActiveRecord can be problematic. Some surveys have thousands of questions and hundreds of thousands of responses. Fast response time is also important for a fluid user experience.
# '''It's harder to read code than to write code'''. Don't choose patterns that are easy or fast to write, but that are easy to read.
# Make your code '''communicate intent'''.
# It's easy to forget '''cross-cutting concerns''' like translation and security. Keep a mental note.
# '''Stress affects code quality''' and your risk behaviour. If your stress level is too high to write code with proper quality, take a step back and discuss it with your boss, or you'll push problems to the future.

== Quality ==

The purpose of this guide is to increase the quality of the LimeSurvey code-base. What is quality? Which aspects of quality can be measured? Which kind of company culture gives rise to appropriate code quality?

It's usually easier to get along what is "bad" code than what's "best" code. Blacklist instead of whitelist?

Quality attributes related to code quality:

* Readability
* Testability
* Maintainability
* Performance
* Security
* Reliability

Can not increase all at the same time - performance vs readability.

It's better to avoid emotional language when describing code quality, like "clean" or "dirty". Be precise, objective and suggest solutions.

Idiomatic code is more readable than non-idiomatic code. What's idiomatic depends on which context or domain you work in. We work in PHP and web application development, and have other idioms than in, say, functional or hardware-close programming.

Some code are "hot spots" - changed often. Those parts should require higher quality than other code.

== Risk ==

todo

Couple of different definition of risk:

* Tuple of probability and severity
* Triple of consequence, uncertainty and knowledge base

Possible risks related to LimeSurvey (technical or business):

* Data loss
* Regressions
* Bad UI (higher churn-rate for users)
* Hard to maintain (reduced sprint velocity)
*

How know which is the biggest risk? How many risks can be approached at once?

Connection to architecture. Risk --> quality attributes --> architectural decisions.

usability a business risk - hard to use or understand, people will choose another tool

risks relevant when fixing bugs

risks relevant when adding new features (lack of testing, wrong requirements, scope creep)

risks relevant when refactoring (regressions)

unit tests and QA as risk mitigation

partial deployment, alpha/beta/rc, risk communication

software rot, design pattern rot/grime, software evolution

rot = non-pattern related code

testing by community, bug fixing by community

== Modules ==

There's no inherit module functionality in PHP, but Yii has a module system. Libraries can be seen as a module system.

Examples of implicit modules in LimeSurvey:

* Front-end (survey taking)
* Back-end (survey design)
* Survey theme editing
* Expression manager
* Plugin system

In the future, they need to be separated and implemented more clearly as whatever Yii 3 module system is in use.

Some data models are common for all modules, e.g. surveys and users. Can have a "Common" module for such data.

todo, relation to Yii config system

== Classes ==

* Avoid empty OOP ceremony, like defining getters and setters for all properties. Might as well make them public, ''unless'' they have invariants that need to be upheld, e.g. "this number is always between 1 and 10" or "this string is maximum length 20".
* Almost always avoid static methods. They cannot be mocked. One exception is (possibly) factory methods (Foo::make(...)).
* Inject all dependencies. This will make sure the class can be unit-tested (unit-tests have several benefits over integrity tests - they can be run in parallel and don't require any setup and teardown)
* A second way to achieve testability is to factor out the methods that access the dependencies

todo, state vs behaviour, state vs dependencies

=== OOP design ===

Start from top-down, with domain, behaviour, interaction between objects, database design, pseudo-code if needed. Can also include scenarios, use-cases and UML diagrams.

Object reification - not only domain models, but also domain actions, relations and activities can be objects, e.g. a class ActivateSurvey or ExportSurvey.

Hierarchy depth should be kept reasonable shallow to avoid conflicts between methods, spooky action at a distance. Compare with Yii 3, where controllers no longer inherit anything.

Some people advocate for composition instead of inheritance. Lots of blog posts available for more info.

Multiple inheritance is done with traits in PHP. Use-case: ActiveRecords where some but not all models support encryption.

==== Shape design problem ====

Imagine you have three shapes: Point, rectangle and circle, with the following properties:

* Point: int x, int y
* Rectangle: Point bottomLeft, Point topRight
* Circle: Point center, int radius

Add two behaviours: area(), draw(surface).

* Cohesion: A class (or module) should be responsible for one thing only
* Coupling: You should be able to ''isolate change'' in the system
* Encapsulation: Classes shouldn’t share internal representation
* Polymorphism: The design should be based on interfaces

Questions to consider:

* How easy would it be to move to a 3D representation?
* How easy would it be to add a new shape, say, triangle?
* How easy would it be to add a new behaviour to all shapes, like save/load from a SQL database?
* Which classes ''change together''?

Keep polymorphism and encapsulation - all properties are private.

Example pseudo-code:

forall shapes as shape, do shape.draw(surface)

forall shapes as shape, do surface.draw(shape) (where shape.getDrawData(), or shape.getPath())

=== Software evolution ===

Design rot after time - how to keep it tight? (Grime.)

Architecture design roundtrip, based on risk.

todo

==== Grime and rot ====

design pattern rot --> lose behaviour relevant for pattern (active record without db connection)

design patter grime --> add behaviour irrelevant for pattern (active record that's also a singleton)

==== Class cohesion ====

[[File:cohesion.png]]

==== Modular coupling ====

[[File:coupling.png]]

Clearer boundaries between classes and modules make it easier to isolate change.

=== State ===

Heuristics to consider but not follow slavishly.

Keep a clear separation between classes with state and classes with no state.

Classes with state should not have dependencies with IO (it's OK to depend on classes in the same application layer, e.g. other DTO classes), and vice versa. ActiveRecord is an example which violates this principle.

class Survey
// Confusion - first params are domain state, last a resource
__construct(id, language, dbConnection)

If a method does not call "this", should it instead be outside the class? A separate class or function, maybe.

todo, elaborate

=== Types of classes ===

Different categories of classes:

* Entity (domain class; has state and validation behaviour)
* Resource (database connection, file, curl, logger; state is in the resource (open, closed))
* Repository classes (database interaction, like splitting ActiveRecord in two parts: Entity class and database interaction)
* DAO, data access object (similar to resource)
* Builders (e.g. query builder, HTML message builder)
* Data-transfer object (no behaviour; pass to views to have better documentation and intent than associative arrays)
* Value classes (e.g. Email address to wrap email string around)
* Command object (e.g. SurveyActivator)
* Helper (no state; e.g. QuestionAttributeHelper to bake attributes into different formats used by the views)
* Wrapper

todo, immutability, possible with private properties that are set in the constructor,

todo: command-query separation for classes?

todo: dependencies between layers, dependencies to the framework

todo, pure vs effectful classes

=== Types of classes in LimeSurvey ===

* ActiveRecord, used to communicate with the database, and should not do ''anything'' else
* Controllers, used for glue code; should not contain business-logic (also CLI controllers)
* Helper functions (not classes, yet...), should be short and obey command-query separation (TODO: Long functions should be separated into command objects or service classes); todo: should not have any dependencies?
* Helper classes, similar to helper functions but have dependencies that need to be mocked during tests; should not have any state
* Service classes, contains logic related to a clear and separate task, like create or import survey
* Question render classes, contains logic related to how questions are rendered (TODO: Need better separation between state and logic and more clear design); similar to widgets
* Plugin classes, using the plugin event system
* Widgets, containing HTML logic for custom HTML widgets
* HTML helpers (Yii)
* Customizations to the Yii framework by inheritance
* Unit and functional test classes

A couple of classes contain only data, like LsDefaultDataSet.

todo, no difference between state property and dependency property in OOP

=== What is "glue code"? ===

todo

Putting the pieces together, e.g. service class A need data from model B, fetch it and run.

todo, add example

=== "Where do I cut?" ===

Separation of concerns, but which concerns and which type of separation? Command-query (function core, imperative shell) is one type of separation. Other separation between layers, e.g. logic layer and data persistency layer (similar in thought).

Other separation, that one class should have a clear purpose. A design pattern should only implement ''one'' pattern, not multiple, and not half a pattern.

There's a problem with "helper" or "manager" classes that they can grow indefinitely, but might be better than nothing. Example when moving business logic out of ActiveRecord class to a helper class it can sometimes hard to be more specific than "helper".

=== Size ===

A class should have a single and clear purpose; compare with [https://en.wikipedia.org/wiki/SOLID SOLID].

=== Class name ===

* ActiveRecord classes are named after the database table they are bound to, but with singular instead of plural. E.g. table "lime_users" have model "User".
* Command classes are named after what they ''do'' and imperatively, e.g. CreateSurvey
* Helper classes should probably be named as specific as possible when possible, to avoid them from growing too big
* Follow the naming tradition of the framework with regard to controllers, e.g. UserController or UserAdministrationController.
* Class properties of ActiveRecord classes will follow the naming of the database, using underscore instead of camel case (and ActiveRecord classes should have ''no'' other properties than those (excluding the database connection injected by the framework))

== Functions ==

Functions are one of the fundamental building blocks of programming, so it's important to get it right.

Functions that are part of a class are called "methods", if you want to be formal.

Different types of functions in PHP:

* Functions (not attached to a class)
* Methods (attached to class)
* Anonymous functions (does not capture scope automatically)
* Short functions (does capture scope automatically)

I'm using "function" as a word for all types of functions in PHP below.

<hr>

=== Size ===

* A function should be short enough to be completely readable on one screen, approx 60 lines at most
* A function should not have too many arguments; if you have five or more, consider making it a class instead
* If a function is growing too big, it might be better to create a class instead or split it into several functions (if both functions have '''common state''', a class might be better, unless you want to pass around '''explicit state''')

=== Contract ===

* A function has a contract with its surrounding environment:
** Pre-condition: What needs to be true before the function is executed
** Post-condition: What will be true after the function has returned
* The function contract can be checked with assertions (internal invariants) or exceptions (outside world); see below
* Another good way is to use unit-tests to make sure the function's contract remains stable through changes
* The first line in the docblock should be one sentence describing the relation between function arguments and its output<br>Example<br><syntaxhighlight lang="php">
/**
* Creates a random password of length $length (defaults to 12)
* @param int $length
* @return string
*/
function createPassword($lenght = 12)

/**
* Creates an HTML language drop down for survey with id $surveyId, marking $selectedLanguage as selected
* @param int $surveyId
* @param string $selectedLanguage
* @return string <select> HTML
*/
function createLanguageDropdown($surveyId, $selectedLanguage)

</syntaxhighlight>

=== Push side-effects up in the stack trace ===

This one is a bit abstract.

First, what is a '''side-effect'''? In short, it's anything that happens in a function that ''is not'' described by the ''relation'' between function arguments and output.

Another way to phrase it is, that a side-effect is anything that is not always the same for the given input to a function; a function without any side-effects will always return the same result if it gets the same input.

'''Examples:'''

<syntaxhighlight lang="php">
// gT accesses the file system and will return different result depending on what's in the translation files
function gT($sToTranslate, $sEscapeMode = 'html', $sLanguage = null);

// If $sText and $sEscapeMode is always the same, quoteText() will always return the same string.
function quoteText($sText, $sEscapeMode = 'html');
</syntaxhighlight>

A function with no side-effects is called '''pure'''. A function that is guaranteed to always return (no exceptions, no errors, no warnings, no division by zero) is called '''total'''.

It's a good thing if functions in a code-base ''either'' have side-effects, ''or'' return a result. Not both. This is called [https://en.wikipedia.org/wiki/Command%E2%80%93query_separation command-query separation].

Examples of side-effects:

* Database or file access
* Echo, or write to stdout or stderr
* Randomization

Why does this matter? Because side-effects make testing harder! '''If you have side-effects, you cannot create unit tests''', ''unless'' those side-effects can be mocked. If not, you need integrity tests with database setup or more. The more side-effects you have in a function, the more mocking is required to unit test it.

So, one solution to this is to move side-effects higher up in the stack trace, that is, move them to the calling code.

'''Example:'''

<syntaxhighlight lang="php">
function getSurveyInfo(int $surveyid, string $languagecode = '', boolean $force = false): array;
</syntaxhighlight>

Since this function takes $surveyid, we know it will probably query the database. Quering the database is a side-effect, and thus it requires a database scaffold for the test (or mocking, but the database connection is not injected, so there's no way to do it). One simple solution is to lift the side-effect out and pass in a Survey object instead:

<syntaxhighlight lang="php">
function getSurveyInfo(Survey $survey, string $languagecode = '', boolean $force = false): array;
</syntaxhighlight>

Much better! The side-effect of calling the database now happens ''before'' the function call. Now we can either mock a Survey object, or make an imitating stub for our test.

Reading the function body, there is in fact another database access, but since this is a relation to the Survey model, it could easily be moved out too. We've just made a function testable! Hooray!

This principle is rephrased in an architectural settings as [https://github.com/kbilsted/Functional-core-imperative-shell/blob/master/README.md functional core, imperative shell]. This architecture helps you get a good ratio between fast unit tests and slower integrity tests.

Moving side-effects up makes sure we can have a healthy ratio between integrity tests with scripted browser, and unit-tests; maybe around 20-80.

=== Function name ===

* The function name should tell you '''what''' it does; docs should tell you '''why''' (if this information is not obvious). '''How''' is described by the code itself (hopefully, but can in some cases be relevant to document).
* Function name can often be '''verb [+ adjective] + noun''', like "createFieldmap", "quoteText", "getRelativePath"
* Prefix with "is" for boolean functions

todo: difference between create, get, fetch, generate, ...

'''Good examples:'''

* createPassword() - One verb, one noun - clear
* isCaptchaEnabled() - Using "is" signifies it returns boolean; clear purpose
* getFullResponseTable() - Verb, adjective, noun - but is "full" needed here? Is there a non-full version of the same function?
* replaceExpressionCodes() - Pretty good, but it's obvious that more information is needed in the docblock to describe what "replace" means, and what an "expression code" is
* fixCKeditorText() - "fix" is a bit vague, but maybe best there is? Pray that docblock contains information!

'''Bad examples:'''

* languageDropdown() - No verb, doesn't tell you what it does
* rmdirr() - Two r's, looks like a typo, but the last "r" actually means "recursive"! Better: rmdir($recursive = false), rmdir or removeFolder.
* CSVUnquote() - Is CSV really the namespace? Why is the verb the second word?
* incompleteAnsFilterState() - One verb, but in the middle, or is "filter state" a noun?; why abbreviate "answer" to "ans"?
* reverseTranslateFieldNames() - Two verbs - did author mean "reverseTranslatedFieldNames"? Or "reverse and translate"? If so, it should be two functions, one for reverse and one for translate
* checkUploadedFileSizeAndRenderJson() - If you have an "and" in the function name, you should consider splitting it into two functions

'''Controversial'''

* gT() - An exception to descriptive function names; since this is used everywhere, the minimal name is motivated; maybe even name it "t()"? Still hard to read for someone who just started? But Yii uses t() too? Other frameworks use double underscore (Wordpress, Laravel) as function name.

<hr>

=== Function filename and namespace ===

If your function has dependencies or side-effects, it should be put into a class instead, in which the dependencies can be injected. Another alternative is to put the dependencies as argument in the function, although this muffles the relationship between input and output. Again, this is to increase testability.

Keep in mind that functions outside classes cannot be mocked, so only use them when you ''know'' you won't need to mock them.

todo, autoloading of functions and folder location

=== Assertions ===

NB: This is not assertions as used in unit-tests, but assertions as used to check invariants in production code.

Assertions can be used for mental checks. They are only used for internal logic - failed assertions are not supposed to be seen by the end user. For interaction with the outside world, like database or browser, exceptions should be used instead.

Assertions can be disabled in production mode and have then no runtime cost (since PHP 7).

'''Example:'''

<syntaxhighlight lang="php">
/**
* Translation helper function
*
* @param string $sToTranslate
* @param string $sEscapeMode Valid values are html (this is the default, js and unescaped)
* @param string $sLanguage
* @return string
*/
function gT($sToTranslate, $sEscapeMode = 'html', $sLanguage = null)
{
assert(is_string($sToTranslate));
assert(strlen($sToTranslate) > 0);
assert($sEscapeMode === 'html' || $sEscapeMode === 'js' || $sEscapeMode === 'unescaped');
return quoteText(Yii::t('', $sToTranslate, array(), null, $sLanguage), $sEscapeMode);
}
</syntaxhighlight>

<hr>

=== Exceptions ===

* Exceptions are used to check inputs from the outside world (browser, database, file system)
* Don't use exceptions for control flow, only when fatal errors happen that make further execution impossible
* Exceptions should have clear error messages that make them ''actionable'' - there should be a clear "next step" for the user or developer
* Never, ever, do an empty catch-block
* At the moment, we do not have an exception hierarchy in LimeSurvey

==== Alternatives to exceptions ====

Some people consider exceptions being a hidden form of "goto" which confuses the control flow of the program. They propose different other solutions:

* Return a tuple, like <code>[$result, $errorMessage]</code> where $errorMessage is null at success
* Return <code>null</code> at failure
* Tagged union result type (not yet possible in latest PHP)
* Result object

The con being that you have to manually propagate the error, where an exception can happen from anywhere in the stack trace without any other function knowing about it.

=== If-statements ===

If-statements should not be too long or hard to understand. If they are, consider factor out the checks into separate functions.

<syntaxhighlight lang="php">
if ((empty($instance->oOptions->{$attribute}))
|| (
!empty($instance->oOptions->{$attribute})
&& (
$instance->oOptions->{$attribute} === 'inherit'
|| $instance->oOptions->{$attribute} === 'I'
// NB: Do NOT use === here, it won't work with Postgresql.
|| $instance->oOptions->{$attribute} == '-1'
)
)
) {
</syntaxhighlight>

Can be shortened by factoring out method <code>isInherit</code>:

<syntaxhighlight lang="php">
if (empty($instance->options->{$attribute})
|| $this->isInherit($instance-options->{$attribute})) {
}
/**
* Returns true if $value is set to inherit
* @param mixed|null $value
* @return boolean
*/
public function isInherit($value) {
return !empty($value)
&& (
$value === 'inherit'
|| $value === 'I'
// NB: Do NOT use === here, it won't work with Postgresql.
|| $value == '-1'
);
}
</syntaxhighlight>

And one more time by using a variable for the value:

<syntaxhighlight lang="php">
$value = $instance->options->{$attribute};
if (empty($value) || $this->isInherit($value)) {
}
</syntaxhighlight>

More clear, right? "If it's empty or set to inherit, do this and that."

=== Variables ===

Descriptive naming.

* Follow PSR-12 - no underscore, use camelCaseLikeThis
* Variables of ActiveRecord classes can have same name as the class, like "$survey" or "$question"
* Add -s for plural when it's a list of items: "$surveys", "$questions"
* Never include "array" or "list" in variable names - using plural is enough (for lists, not for associative arrays - see below)
* The ''context'' of the function helps with variable naming, e..g "$name" might be fine in a function about questions; this is extra helpful when functions are short!
* When a function is short, it's much easier to figure out variable meaning based on context
* $qid, $gid, and $sid are so established in the code-base that they could be considered OK
* The -data suffix means "blob of stuff", only use it when needed, like with $viewData
* Use $result when baking a return value; add its exact type as @var annotation (worst possible name, acceptable but anything with more meaning is better)

Not so good:

<syntaxhighlight lang="php">
$result = LabelSet::model()->findAll();
</syntaxhighlight>

Better with model name and -s for plural:

<syntaxhighlight lang="php">
$labelSets = LabelSet::model()->findAll();
</syntaxhighlight>

* Do not use Hungarian notation (prefix with "type"), but instead <code>/** @var */</code> annotations - these can be checked automatically and will then be enforced to be correct, unlike Hungarian notation which can "rot"

<syntaxhighlight lang="php">
/** string[] An array of strings with 0-n elements */
$allFields = [];
</syntaxhighlight>

Psalm can infer types if the function documentation is enough. The strictness can be adjusted. Not all variables will need @var annotation, the tool will warn you when it's confused.

* Data that is sent to views as associative arrays will be:

<syntaxhighlight lang="php">
/** @var array Can be basically anything :( Better would be data-transfer objects or more precise notation */
$data = [];
// Maybe more clear as $viewData? Discuss.
</syntaxhighlight>

You can be more precise when you specify which type of array you're writing:

<syntaxhighlight lang="php">
/** @var array<string, string> This means the array key is string, and the array value is also string */
$data = [];
$data['name'] = 'Olle';
$data['occupation'] = 'Developer';
$data['age'] = 38; // ERROR! Value must be string.
</syntaxhighlight>

For more info about array type notation, see the [https://psalm.dev/docs/annotating_code/type_syntax/array_types/ Psalm documentation].

Some smaller examples:

<syntaxhighlight lang="php">
$theme = App()->request->getPost('theme'); // Should be $themeType - $theme looks like a model/AR
$gridid === 'questionthemes-grid'; // Should be $gridId with capital "I", since it's two words in English
$delete = Yii::app()->request->getParam('delete'); // Tuff one - $delete is ok? Thoughts?
$files = json_decode(stripslashes($sJSON), true); // $file is a resource, $files an array of resources, this is $fileData perhaps?
$valid_extensions_array = explode(",", $aAttributes['allowed_filetypes']); // Should be $validExtensionTypes
$language = Yii::app()->session['survey_' . $surveyid]['s_lang']; // TODO: Should this be a value class? Then Language::make(...);
$surveyInfo = getSurveyInfo($surveyId, $language); // OK, BUT should be a separate DTO!
$fieldMap = createFieldMap($survey, 'short', false, false, $language); // Same, make a DTO
$cquestions = array(); // What's "c"? Method name is getChildQuestions and $questions is an argument - better with $childQuestions?
</syntaxhighlight>

Links:

[https://www.approxion.com/capital-offenses-how-to-handle-abbreviations-in-camelcase/ How to Handle Abbreviations in CamelCase]

[https://stackoverflow.com/questions/15526107/acronyms-in-camelcase Acronyms in CamelCase]

=== Looping ===

* The bodies of foreach-loops are often a good candidate to factor out into separate functions.

'''Example:'''

<syntaxhighlight lang="php">
foreach ($questions as $question) {
processQuestion($question);
}
</syntaxhighlight>

Note the variable naming from plural to singular.

* Loop indexing should be named i, j, k etc.

'''Example:'''

<syntaxhighlight lang="php">
for ($i = 0; $i < $length; $i++) {
for ($j = 0; $j < $otherLength; $j++) {
// ...
}
}
</syntaxhighlight>

<hr>

=== Function composition ===

todo, "doThisAndThat" --> "doThis(doThat())"

=== Cases ===

<syntaxhighlight lang="php">
/**
* This function generates an array containing the fieldcode, and matching data in the same order as the activate script
*
* @param Survey $survey Survey ActiveRecord model
* @param string $style 'short' (default) or 'full' - full creates extra information like default values
* @param boolean $force_refresh - Forces to really refresh the array, not just take the session copy
* @param bool|int $questionid Limit to a certain qid only (for question preview) - default is false
* @param string $sLanguage The language to use
* @param array $aDuplicateQIDs
* @return array
*/
function createFieldMap($survey, $style = 'short', $force_refresh = false, $questionid = false, $sLanguage = '', &$aDuplicateQIDs = array())
</syntaxhighlight>

'''Good:'''

* Name is verb and noun
* Each argument is documented (almost)

'''Bad:'''

* Returns "array", which can be anything. A separate class for "Fieldmap" would be better.
* Not clear if it should be "createFieldMap" or "createFieldmap" - is "fieldmap" one word or two?
* Very many boolean arguments. Should probably be a class with methods like <code>$fieldmapCreator->setForceRefresh(true);</code> instead.
* Too long.
* Doesn't elaborate on what "fieldmap" really is, and does not link to any documentation about it.
* Access super-global, which makes it hard to test. Should instead return a data-transfer object, like:<br><syntaxhighlight lang="php">
$_SESSION['fieldmap'] = createFieldMap(...);
</syntaxhighlight>
* Has no test
* Mixes Hungarian notation with non-Hungarian notation in the argument list

== Defensive programming and error handling ==

todo

* '''Fail hard, fail early'''. The earlier the program crashes when something is wrong, the lower is the probability that you'll end up with corrupt data in the database that will later require manual labor to correct.
* Fail with '''actionable information'''
* Check input to functions and throw <code>InvalidArgumentException</code> if it violates the function's pre-conditions
* Use assert for class-internal invariants
* Use assert to make assumptions explicit for the reader

== Documentation ==

=== PHPDoc ===

* All functions must have a proper docblock
* The first line of the docblock should describe the relation between ''all'' the input arguments and the output of the function in a single sentence
* Each parameter must have the correct type
* Don't use <code>array</code> as type if it's a list of object - instead, use <code>[]</code> like so: <code>Survey[]</code> for a list of surveys

=== Technical documentation ===

todo, UML, scenarios, use-cases

== The PHP of yesterday ==

Old idioms and habits that should be abandoned.

* Don't use associative arrays, almost never. Data-transfer objects have multiple benefits: they are clearly structured, can be documented, can enforce invariants. There's ''no'' performance overhead of objects compared to arrays in modern PHP.
* Objects are already passed by reference; arrays are value types
* Use <code>[]</code> instead of <code>array()</code>
* Hungarian notation was useful before static analysis existed for PHP. These days it's better to use something that can be checked automatically: docblock @param and inline @var annotations.

== The PHP of tomorrow ==

todo

Union tags

Short functions

Match expressions

== Security ==

todo

XSS

Database injection

Permissions and roles

== Performance ==

todo

Loading too many rows into PHP models

== Testing ==

todo

QA

PHPUnit

TDD

Mocks, can't mock functions, static methods, mocking as a DSL, PHPUnit mocking tools

Pure functions, referential transparency, side-effects

Unit, functional, integration

Don't test the framework; don't test PHP

Makes sure the function or class lives up to its specification; make sure it will ''always'' live up to its specification, even in the future, to avoid regressions.

== Static analysis ==

<code>php -l</code>, CodeSniffer, Mess Detector, Psalm

== Database design ==

todo

== JavaScript ==

todo

classes, functions, components, tests

== CSS ==

todo

== HTML ==

todo

== Feedback ==

=== "Why do I have to refactor code that works?" ===

todo, Sadly, it's not enough for the code to live up to the current specification and requirements, it must also be protected against future changes, regressions. Adding tests is the best way for this. Lots of people might read and change the LimeSurvey code the next 5-10 years. The test suite creates a security layer to make sure the specification is fulfilled even as the code changes.

Tests are not a magical solution, however. It does not protect us against other degradation of the code quality, like classes gaining too much responsibility (too many methods, unrelated methods, too many properties).

=== "What's the correct ratio between integrity tests and unit tests?" ===

todo, Don't know. Different pros and cons.

* Unit-test can be run in parallel and are faster
* Unit-tests don't need setup and teardown

Cons of unit-tests is that they need a bigger effort on the side of the developer to make them possible, for example injecting the dependencies properly to enable mocking, or lifting side-effects up in the stack trace.

=== How to disagree ===

All rules can be broken. To break a rule, you should reason in terms of risk and the assumptions used in this guide.

'''Assumptions:'''

# Regressions are the biggest technical risk for LimeSurvey the last five years (2021)
# Automated tests are the best risk mitigation technique against regressions

'''Possible disagreement:'''

# A certain piece of code has very low ''probability'' of regressions (maybe we "know" no one else will every touch or change it?)
# Regression in a certain piece of code would have very low ''impact''

== Architectural Decision Records ==

todo

https://adr.github.io/

== Resources ==

todo

Books, links, videos

Code quality guide

2021-05-19T10:11:55Z

Olle: /* Software evolution */

DRAFT

== Prologue ==

# '''Be risk aware'''. Too good code can be a business risk (slow to write, maybe over-designed). Too sloppy code can also be a business risk (hard to maintain and understand). You have to find a balance that is adapted to the current situation and risk analysis, in which code quality becomes a '''risk mitigation''' technique among others.
# '''Be humble'''. LimeSurvey was made by developers from all over the world, with different age, education and experience. Your code might be read by a completely different team ten years from now, in the same way you are now reading code by developers that no longer work with us, but which work pays our rent.
# '''Performance matters sometimes''', and shouldn't be disregarded completely. In particular, database queries using the ORM and ActiveRecord can be problematic. Some surveys have thousands of questions and hundreds of thousands of responses. Fast response time is also important for a fluid user experience.
# '''It's harder to read code than to write code'''. Don't choose patterns that are easy or fast to write, but that are easy to read.
# Make your code '''communicate intent'''.
# It's easy to forget '''cross-cutting concerns''' like translation and security. Keep a mental note.
# '''Stress affects code quality''' and your risk behaviour. If your stress level is too high to write code with proper quality, take a step back and discuss it with your boss, or you'll push problems to the future.

== Quality ==

The purpose of this guide is to increase the quality of the LimeSurvey code-base. What is quality? Which aspects of quality can be measured? Which kind of company culture gives rise to appropriate code quality?

It's usually easier to get along what is "bad" code than what's "best" code. Blacklist instead of whitelist?

Quality attributes related to code quality:

* Readability
* Testability
* Maintainability
* Performance
* Security
* Reliability

Can not increase all at the same time - performance vs readability.

It's better to avoid emotional language when describing code quality, like "clean" or "dirty". Be precise, objective and suggest solutions.

Idiomatic code is more readable than non-idiomatic code. What's idiomatic depends on which context or domain you work in. We work in PHP and web application development, and have other idioms than in, say, functional or hardware-close programming.

Some code are "hot spots" - changed often. Those parts should require higher quality than other code.

== Risk ==

todo

Couple of different definition of risk:

* Tuple of probability and severity
* Triple of consequence, uncertainty and knowledge base

Possible risks related to LimeSurvey (technical or business):

* Data loss
* Regressions
* Bad UI (higher churn-rate for users)
* Hard to maintain (reduced sprint velocity)
*

How know which is the biggest risk? How many risks can be approached at once?

Connection to architecture. Risk --> quality attributes --> architectural decisions.

usability a business risk - hard to use or understand, people will choose another tool

risks relevant when fixing bugs

risks relevant when adding new features (lack of testing, wrong requirements, scope creep)

risks relevant when refactoring (regressions)

unit tests and QA as risk mitigation

partial deployment, alpha/beta/rc, risk communication

software rot, design pattern rot/grime, software evolution

rot = non-pattern related code

testing by community, bug fixing by community

== Modules ==

There's no inherit module functionality in PHP, but Yii has a module system. Libraries can be seen as a module system.

Examples of implicit modules in LimeSurvey:

* Front-end (survey taking)
* Back-end (survey design)
* Survey theme editing
* Expression manager
* Plugin system

In the future, they need to be separated and implemented more clearly as whatever Yii 3 module system is in use.

Some data models are common for all modules, e.g. surveys and users. Can have a "Common" module for such data.

todo, relation to Yii config system

== Classes ==

* Avoid empty OOP ceremony, like defining getters and setters for all properties. Might as well make them public, ''unless'' they have invariants that need to be upheld, e.g. "this number is always between 1 and 10" or "this string is maximum length 20".
* Almost always avoid static methods. They cannot be mocked. One exception is (possibly) factory methods (Foo::make(...)).
* Inject all dependencies. This will make sure the class can be unit-tested (unit-tests have several benefits over integrity tests - they can be run in parallel and don't require any setup and teardown)
* A second way to achieve testability is to factor out the methods that access the dependencies

todo, state vs behaviour, state vs dependencies

=== OOP design ===

Start from top-down, with domain, behaviour, interaction between objects, database design, pseudo-code if needed. Can also include scenarios, use-cases and UML diagrams.

Object reification - not only domain models, but also domain actions, relations and activities can be objects, e.g. a class ActivateSurvey or ExportSurvey.

Hierarchy depth should be kept reasonable shallow to avoid conflicts between methods, spooky action at a distance. Compare with Yii 3, where controllers no longer inherit anything.

Some people advocate for composition instead of inheritance. Lots of blog posts available for more info.

Multiple inheritance is done with traits in PHP. Use-case: ActiveRecords where some but not all models support encryption.

==== Shape design problem ====

Imagine you have three shapes: Point, rectangle and circle, with the following properties:

* Point: int x, int y
* Rectangle: Point bottomLeft, Point topRight
* Circle: Point center, int radius

Add two behaviours: area(), draw(surface).

* Cohesion: A class (or module) should be responsible for one thing only
* Coupling: You should be able to ''isolate change'' in the system
* Encapsulation: Classes shouldn’t share internal representation
* Polymorphism: The design should be based on interfaces

Questions to consider:

* How easy would it be to move to a 3D representation?
* How easy would it be to add a new shape, say, triangle?
* How easy would it be to add a new behaviour to all shapes, like save/load from a SQL database?
* Which classes ''change together''?

Keep polymorphism and encapsulation - all properties are private.

Example pseudo-code:

forall shapes as shape, do shape.draw(surface)

forall shapes as shape, do surface.draw(shape) (where shape.getDrawData(), or shape.getPath())

=== Software evolution ===

Design rot after time - how to keep it tight? (Grime.)

Architecture design roundtrip, based on risk.

todo

==== Grime and rot ====

design pattern rot --> lose behaviour relevant for pattern (active record without db connection)

design patter grime --> add behaviour irrelevant for pattern (active record that's also a singleton)

==== Class cohesion ====

[[File:cohesion.png]]

==== Modular coupling ====

[[File:coupling.png]]

Clearer boundaries between classes and modules make it easier to isolate change.

=== State ===

Heuristics to consider but not follow slavishly.

Keep a clear separation between classes with state and classes with no state.

Classes with state should not have dependencies with IO (it's OK to depend on classes in the same application layer, e.g. other DTO classes), and vice versa. ActiveRecord is an example which violates this principle.

class Survey
// Confusion - first params are domain state, last a resource
__construct(id, language, dbConnection)

If a method does not call "this", should it instead be outside the class? A separate class or function, maybe.

todo, elaborate

=== Types of classes ===

Different categories of classes:

* Entity (domain class; has state and validation behaviour)
* Resource (database connection, file, curl, logger; state is in the resource (open, closed))
* Repository classes (database interaction, like splitting ActiveRecord in two parts: Entity class and database interaction)
* DAO, data access object (similar to resource)
* Builders (e.g. query builder, HTML message builder)
* Data-transfer object (no behaviour; pass to views to have better documentation and intent than associative arrays)
* Value classes (e.g. Email address to wrap email string around)
* Command object (e.g. SurveyActivator)
* Helper (no state; e.g. QuestionAttributeHelper to bake attributes into different formats used by the views)
* Wrapper

todo, immutability, possible with private properties that are set in the constructor,

todo: command-query separation for classes?

todo: dependencies between layers, dependencies to the framework

todo, pure vs effectful classes

=== Types of classes in LimeSurvey ===

* ActiveRecord, used to communicate with the database, and should not do ''anything'' else
* Controllers, used for glue code; should not contain business-logic (also CLI controllers)
* Helper functions (not classes, yet...), should be short and obey command-query separation (TODO: Long functions should be separated into command objects or service classes); todo: should not have any dependencies?
* Helper classes, similar to helper functions but have dependencies that need to be mocked during tests; should not have any state
* Service classes, contains logic related to a clear and separate task, like create or import survey
* Question render classes, contains logic related to how questions are rendered (TODO: Need better separation between state and logic and more clear design); similar to widgets
* Plugin classes, using the plugin event system
* Widgets, containing HTML logic for custom HTML widgets
* HTML helpers (Yii)
* Customizations to the Yii framework by inheritance
* Unit and functional test classes

A couple of classes contain only data, like LsDefaultDataSet.

todo, no difference between state property and dependency property in OOP

=== What is "glue code"? ===

todo

Putting the pieces together, e.g. service class A need data from model B, fetch it and run.

todo, add example

=== "Where do I cut?" ===

Separation of concerns, but which concerns and which type of separation? Command-query (function core, imperative shell) is one type of separation. Other separation between layers, e.g. logic layer and data persistency layer (similar in thought).

Other separation, that one class should have a clear purpose. A design pattern should only implement ''one'' pattern, not multiple, and not half a pattern.

There's a problem with "helper" or "manager" classes that they can grow indefinitely, but might be better than nothing. Example when moving business logic out of ActiveRecord class to a helper class it can sometimes hard to be more specific than "helper".

=== Size ===

A class should have a single and clear purpose; compare with [https://en.wikipedia.org/wiki/SOLID SOLID].

=== Class name ===

* ActiveRecord classes are named after the database table they are bound to, but with singular instead of plural. E.g. table "lime_users" have model "User".
* Command classes are named after what they ''do'' and imperatively, e.g. CreateSurvey
* Helper classes should probably be named as specific as possible when possible, to avoid them from growing too big
* Follow the naming tradition of the framework with regard to controllers, e.g. UserController or UserAdministrationController.
* Class properties of ActiveRecord classes will follow the naming of the database, using underscore instead of camel case (and ActiveRecord classes should have ''no'' other properties than those (excluding the database connection injected by the framework))

== Functions ==

Functions are one of the fundamental building blocks of programming, so it's important to get it right.

Functions that are part of a class are called "methods", if you want to be formal.

Different types of functions in PHP:

* Functions (not attached to a class)
* Methods (attached to class)
* Anonymous functions (does not capture scope automatically)
* Short functions (does capture scope automatically)

I'm using "function" as a word for all types of functions in PHP below.

<hr>

=== Size ===

* A function should be short enough to be completely readable on one screen, approx 60 lines at most
* A function should not have too many arguments; if you have five or more, consider making it a class instead
* If a function is growing too big, it might be better to create a class instead or split it into several functions (if both functions have '''common state''', a class might be better, unless you want to pass around '''explicit state''')

=== Contract ===

* A function has a contract with its surrounding environment:
** Pre-condition: What needs to be true before the function is executed
** Post-condition: What will be true after the function has returned
* The function contract can be checked with assertions (internal invariants) or exceptions (outside world); see below
* Another good way is to use unit-tests to make sure the function's contract remains stable through changes
* The first line in the docblock should be one sentence describing the relation between function arguments and its output<br>Example<br><syntaxhighlight lang="php">
/**
* Creates a random password of length $length (defaults to 12)
* @param int $length
* @return string
*/
function createPassword($lenght = 12)

/**
* Creates an HTML language drop down for survey with id $surveyId, marking $selectedLanguage as selected
* @param int $surveyId
* @param string $selectedLanguage
* @return string <select> HTML
*/
function createLanguageDropdown($surveyId, $selectedLanguage)

</syntaxhighlight>

=== Push side-effects up in the stack trace ===

This one is a bit abstract.

First, what is a '''side-effect'''? In short, it's anything that happens in a function that ''is not'' described by the ''relation'' between function arguments and output.

Another way to phrase it is, that a side-effect is anything that is not always the same for the given input to a function; a function without any side-effects will always return the same result if it gets the same input.

'''Examples:'''

<syntaxhighlight lang="php">
// gT accesses the file system and will return different result depending on what's in the translation files
function gT($sToTranslate, $sEscapeMode = 'html', $sLanguage = null);

// If $sText and $sEscapeMode is always the same, quoteText() will always return the same string.
function quoteText($sText, $sEscapeMode = 'html');
</syntaxhighlight>

A function with no side-effects is called '''pure'''. A function that is guaranteed to always return (no exceptions, no errors, no warnings, no division by zero) is called '''total'''.

It's a good thing if functions in a code-base ''either'' have side-effects, ''or'' return a result. Not both. This is called [https://en.wikipedia.org/wiki/Command%E2%80%93query_separation command-query separation].

Examples of side-effects:

* Database or file access
* Echo, or write to stdout or stderr
* Randomization

Why does this matter? Because side-effects make testing harder! '''If you have side-effects, you cannot create unit tests''', ''unless'' those side-effects can be mocked. If not, you need integrity tests with database setup or more. The more side-effects you have in a function, the more mocking is required to unit test it.

So, one solution to this is to move side-effects higher up in the stack trace, that is, move them to the calling code.

'''Example:'''

<syntaxhighlight lang="php">
function getSurveyInfo(int $surveyid, string $languagecode = '', boolean $force = false): array;
</syntaxhighlight>

Since this function takes $surveyid, we know it will probably query the database. Quering the database is a side-effect, and thus it requires a database scaffold for the test (or mocking, but the database connection is not injected, so there's no way to do it). One simple solution is to lift the side-effect out and pass in a Survey object instead:

<syntaxhighlight lang="php">
function getSurveyInfo(Survey $survey, string $languagecode = '', boolean $force = false): array;
</syntaxhighlight>

Much better! The side-effect of calling the database now happens ''before'' the function call. Now we can either mock a Survey object, or make an imitating stub for our test.

Reading the function body, there is in fact another database access, but since this is a relation to the Survey model, it could easily be moved out too. We've just made a function testable! Hooray!

This principle is rephrased in an architectural settings as [https://github.com/kbilsted/Functional-core-imperative-shell/blob/master/README.md functional core, imperative shell]. This architecture helps you get a good ratio between fast unit tests and slower integrity tests.

Moving side-effects up makes sure we can have a healthy ratio between integrity tests with scripted browser, and unit-tests; maybe around 20-80.

=== Function name ===

* The function name should tell you '''what''' it does; docs should tell you '''why''' (if this information is not obvious). '''How''' is described by the code itself (hopefully, but can in some cases be relevant to document).
* Function name can often be '''verb [+ adjective] + noun''', like "createFieldmap", "quoteText", "getRelativePath"
* Prefix with "is" for boolean functions

todo: difference between create, get, fetch, generate, ...

'''Good examples:'''

* createPassword() - One verb, one noun - clear
* isCaptchaEnabled() - Using "is" signifies it returns boolean; clear purpose
* getFullResponseTable() - Verb, adjective, noun - but is "full" needed here? Is there a non-full version of the same function?
* replaceExpressionCodes() - Pretty good, but it's obvious that more information is needed in the docblock to describe what "replace" means, and what an "expression code" is
* fixCKeditorText() - "fix" is a bit vague, but maybe best there is? Pray that docblock contains information!

'''Bad examples:'''

* languageDropdown() - No verb, doesn't tell you what it does
* rmdirr() - Two r's, looks like a typo, but the last "r" actually means "recursive"! Better: rmdir($recursive = false), rmdir or removeFolder.
* CSVUnquote() - Is CSV really the namespace? Why is the verb the second word?
* incompleteAnsFilterState() - One verb, but in the middle, or is "filter state" a noun?; why abbreviate "answer" to "ans"?
* reverseTranslateFieldNames() - Two verbs - did author mean "reverseTranslatedFieldNames"? Or "reverse and translate"? If so, it should be two functions, one for reverse and one for translate
* checkUploadedFileSizeAndRenderJson() - If you have an "and" in the function name, you should consider splitting it into two functions

'''Controversial'''

* gT() - An exception to descriptive function names; since this is used everywhere, the minimal name is motivated; maybe even name it "t()"? Still hard to read for someone who just started? But Yii uses t() too? Other frameworks use double underscore (Wordpress, Laravel) as function name.

<hr>

=== Function filename and namespace ===

If your function has dependencies or side-effects, it should be put into a class instead, in which the dependencies can be injected. Another alternative is to put the dependencies as argument in the function, although this muffles the relationship between input and output. Again, this is to increase testability.

Keep in mind that functions outside classes cannot be mocked, so only use them when you ''know'' you won't need to mock them.

todo, autoloading of functions and folder location

=== Assertions ===

NB: This is not assertions as used in unit-tests, but assertions as used to check invariants in production code.

Assertions can be used for mental checks. They are only used for internal logic - failed assertions are not supposed to be seen by the end user. For interaction with the outside world, like database or browser, exceptions should be used instead.

Assertions can be disabled in production mode and have then no runtime cost (since PHP 7).

'''Example:'''

<syntaxhighlight lang="php">
/**
* Translation helper function
*
* @param string $sToTranslate
* @param string $sEscapeMode Valid values are html (this is the default, js and unescaped)
* @param string $sLanguage
* @return string
*/
function gT($sToTranslate, $sEscapeMode = 'html', $sLanguage = null)
{
assert(is_string($sToTranslate));
assert(strlen($sToTranslate) > 0);
assert($sEscapeMode === 'html' || $sEscapeMode === 'js' || $sEscapeMode === 'unescaped');
return quoteText(Yii::t('', $sToTranslate, array(), null, $sLanguage), $sEscapeMode);
}
</syntaxhighlight>

<hr>

=== Exceptions ===

todo

todo: exception hierarchy

todo: what can be repaired after exception? transaction rollback

* Exceptions are used to check inputs from the outside world (browser, database, file system)
* Don't use exceptions for control flow, only when fatal errors happen that make further execution impossible
* Exceptions should have clear error messages that make them ''actionable'' - there should be a clear "next step" for the user or developer
* Never, ever, do an empty catch-block

==== Alternatives to exceptions ====

Some people consider exceptions being a hidden form of "goto" which confuses the control flow of the program. They propose different other solutions:

* Return a tuple, like <code>[$result, $errorMessage]</code> where $errorMessage is null at success
* Return <code>null</code> at failure
* Tagged union result type (not yet possible in latest PHP)
* Result object

The con being that you have to manually propagate the error, where an exception can happen from anywhere in the stack trace without any other function knowing about it.

=== If-statements ===

If-statements should not be too long or hard to understand. If they are, consider factor out the checks into separate functions.

<syntaxhighlight lang="php">
if ((empty($instance->oOptions->{$attribute}))
|| (
!empty($instance->oOptions->{$attribute})
&& (
$instance->oOptions->{$attribute} === 'inherit'
|| $instance->oOptions->{$attribute} === 'I'
// NB: Do NOT use === here, it won't work with Postgresql.
|| $instance->oOptions->{$attribute} == '-1'
)
)
) {
</syntaxhighlight>

Can be shortened by factoring out method <code>isInherit</code>:

<syntaxhighlight lang="php">
if (empty($instance->options->{$attribute})
|| $this->isInherit($instance-options->{$attribute})) {
}
/**
* Returns true if $value is set to inherit
* @param mixed|null $value
* @return boolean
*/
public function isInherit($value) {
return !empty($value)
&& (
$value === 'inherit'
|| $value === 'I'
// NB: Do NOT use === here, it won't work with Postgresql.
|| $value == '-1'
);
}
</syntaxhighlight>

And one more time by using a variable for the value:

<syntaxhighlight lang="php">
$value = $instance->options->{$attribute};
if (empty($value) || $this->isInherit($value)) {
}
</syntaxhighlight>

More clear, right? "If it's empty or set to inherit, do this and that."

=== Variables ===

Descriptive naming.

* Follow PSR-12 - no underscore, use camelCaseLikeThis
* Variables of ActiveRecord classes can have same name as the class, like "$survey" or "$question"
* Add -s for plural when it's a list of items: "$surveys", "$questions"
* Never include "array" or "list" in variable names - using plural is enough (for lists, not for associative arrays - see below)
* The ''context'' of the function helps with variable naming, e..g "$name" might be fine in a function about questions; this is extra helpful when functions are short!
* When a function is short, it's much easier to figure out variable meaning based on context
* $qid, $gid, and $sid are so established in the code-base that they could be considered OK
* The -data suffix means "blob of stuff", only use it when needed, like with $viewData
* Use $result when baking a return value; add its exact type as @var annotation (worst possible name, acceptable but anything with more meaning is better)

Not so good:

<syntaxhighlight lang="php">
$result = LabelSet::model()->findAll();
</syntaxhighlight>

Better with model name and -s for plural:

<syntaxhighlight lang="php">
$labelSets = LabelSet::model()->findAll();
</syntaxhighlight>

* Do not use Hungarian notation (prefix with "type"), but instead <code>/** @var */</code> annotations - these can be checked automatically and will then be enforced to be correct, unlike Hungarian notation which can "rot"

<syntaxhighlight lang="php">
/** string[] An array of strings with 0-n elements */
$allFields = [];
</syntaxhighlight>

Psalm can infer types if the function documentation is enough. The strictness can be adjusted. Not all variables will need @var annotation, the tool will warn you when it's confused.

* Data that is sent to views as associative arrays will be:

<syntaxhighlight lang="php">
/** @var array Can be basically anything :( Better would be data-transfer objects or more precise notation */
$data = [];
// Maybe more clear as $viewData? Discuss.
</syntaxhighlight>

You can be more precise when you specify which type of array you're writing:

<syntaxhighlight lang="php">
/** @var array<string, string> This means the array key is string, and the array value is also string */
$data = [];
$data['name'] = 'Olle';
$data['occupation'] = 'Developer';
$data['age'] = 38; // ERROR! Value must be string.
</syntaxhighlight>

For more info about array type notation, see the [https://psalm.dev/docs/annotating_code/type_syntax/array_types/ Psalm documentation].

Some smaller examples:

<syntaxhighlight lang="php">
$theme = App()->request->getPost('theme'); // Should be $themeType - $theme looks like a model/AR
$gridid === 'questionthemes-grid'; // Should be $gridId with capital "I", since it's two words in English
$delete = Yii::app()->request->getParam('delete'); // Tuff one - $delete is ok? Thoughts?
$files = json_decode(stripslashes($sJSON), true); // $file is a resource, $files an array of resources, this is $fileData perhaps?
$valid_extensions_array = explode(",", $aAttributes['allowed_filetypes']); // Should be $validExtensionTypes
$language = Yii::app()->session['survey_' . $surveyid]['s_lang']; // TODO: Should this be a value class? Then Language::make(...);
$surveyInfo = getSurveyInfo($surveyId, $language); // OK, BUT should be a separate DTO!
$fieldMap = createFieldMap($survey, 'short', false, false, $language); // Same, make a DTO
$cquestions = array(); // What's "c"? Method name is getChildQuestions and $questions is an argument - better with $childQuestions?
</syntaxhighlight>

Links:

[https://www.approxion.com/capital-offenses-how-to-handle-abbreviations-in-camelcase/ How to Handle Abbreviations in CamelCase]

[https://stackoverflow.com/questions/15526107/acronyms-in-camelcase Acronyms in CamelCase]

=== Looping ===

* The bodies of foreach-loops are often a good candidate to factor out into separate functions.

'''Example:'''

<syntaxhighlight lang="php">
foreach ($questions as $question) {
processQuestion($question);
}
</syntaxhighlight>

Note the variable naming from plural to singular.

* Loop indexing should be named i, j, k etc.

'''Example:'''

<syntaxhighlight lang="php">
for ($i = 0; $i < $length; $i++) {
for ($j = 0; $j < $otherLength; $j++) {
// ...
}
}
</syntaxhighlight>

<hr>

=== Function composition ===

todo, "doThisAndThat" --> "doThis(doThat())"

=== Cases ===

<syntaxhighlight lang="php">
/**
* This function generates an array containing the fieldcode, and matching data in the same order as the activate script
*
* @param Survey $survey Survey ActiveRecord model
* @param string $style 'short' (default) or 'full' - full creates extra information like default values
* @param boolean $force_refresh - Forces to really refresh the array, not just take the session copy
* @param bool|int $questionid Limit to a certain qid only (for question preview) - default is false
* @param string $sLanguage The language to use
* @param array $aDuplicateQIDs
* @return array
*/
function createFieldMap($survey, $style = 'short', $force_refresh = false, $questionid = false, $sLanguage = '', &$aDuplicateQIDs = array())
</syntaxhighlight>

'''Good:'''

* Name is verb and noun
* Each argument is documented (almost)

'''Bad:'''

* Returns "array", which can be anything. A separate class for "Fieldmap" would be better.
* Not clear if it should be "createFieldMap" or "createFieldmap" - is "fieldmap" one word or two?
* Very many boolean arguments. Should probably be a class with methods like <code>$fieldmapCreator->setForceRefresh(true);</code> instead.
* Too long.
* Doesn't elaborate on what "fieldmap" really is, and does not link to any documentation about it.
* Access super-global, which makes it hard to test. Should instead return a data-transfer object, like:<br><syntaxhighlight lang="php">
$_SESSION['fieldmap'] = createFieldMap(...);
</syntaxhighlight>
* Has no test
* Mixes Hungarian notation with non-Hungarian notation in the argument list

== Defensive programming and error handling ==

todo

* '''Fail hard, fail early'''. The earlier the program crashes when something is wrong, the lower is the probability that you'll end up with corrupt data in the database that will later require manual labor to correct.
* Fail with '''actionable information'''
* Check input to functions and throw <code>InvalidArgumentException</code> if it violates the function's pre-conditions
* Use assert for class-internal invariants
* Use assert to make assumptions explicit for the reader

== Documentation ==

=== PHPDoc ===

* All functions must have a proper docblock
* The first line of the docblock should describe the relation between ''all'' the input arguments and the output of the function in a single sentence
* Each parameter must have the correct type
* Don't use <code>array</code> as type if it's a list of object - instead, use <code>[]</code> like so: <code>Survey[]</code> for a list of surveys

=== Technical documentation ===

todo, UML, scenarios, use-cases

== The PHP of yesterday ==

Old idioms and habits that should be abandoned.

* Don't use associative arrays, almost never. Data-transfer objects have multiple benefits: they are clearly structured, can be documented, can enforce invariants. There's ''no'' performance overhead of objects compared to arrays in modern PHP.
* Objects are already passed by reference; arrays are value types
* Use <code>[]</code> instead of <code>array()</code>
* Hungarian notation was useful before static analysis existed for PHP. These days it's better to use something that can be checked automatically: docblock @param and inline @var annotations.

== The PHP of tomorrow ==

todo

Union tags

Short functions

Match expressions

== Security ==

todo

XSS

Database injection

Permissions and roles

== Performance ==

todo

Loading too many rows into PHP models

== Testing ==

todo

QA

PHPUnit

TDD

Mocks, can't mock functions, static methods, mocking as a DSL, PHPUnit mocking tools

Pure functions, referential transparency, side-effects

Unit, functional, integration

Don't test the framework; don't test PHP

Makes sure the function or class lives up to its specification; make sure it will ''always'' live up to its specification, even in the future, to avoid regressions.

== Static analysis ==

<code>php -l</code>, CodeSniffer, Mess Detector, Psalm

== Database design ==

todo

== JavaScript ==

todo

classes, functions, components, tests

== CSS ==

todo

== HTML ==

todo

== Feedback ==

=== "Why do I have to refactor code that works?" ===

todo, Sadly, it's not enough for the code to live up to the current specification and requirements, it must also be protected against future changes, regressions. Adding tests is the best way for this. Lots of people might read and change the LimeSurvey code the next 5-10 years. The test suite creates a security layer to make sure the specification is fulfilled even as the code changes.

Tests are not a magical solution, however. It does not protect us against other degradation of the code quality, like classes gaining too much responsibility (too many methods, unrelated methods, too many properties).

=== "What's the correct ratio between integrity tests and unit tests?" ===

todo, Don't know. Different pros and cons.

* Unit-test can be run in parallel and are faster
* Unit-tests don't need setup and teardown

Cons of unit-tests is that they need a bigger effort on the side of the developer to make them possible, for example injecting the dependencies properly to enable mocking, or lifting side-effects up in the stack trace.

=== How to disagree ===

All rules can be broken. To break a rule, you should reason in terms of risk and the assumptions used in this guide.

'''Assumptions:'''

# Regressions are the biggest technical risk for LimeSurvey the last five years (2021)
# Automated tests are the best risk mitigation technique against regressions

'''Possible disagreement:'''

# A certain piece of code has very low ''probability'' of regressions (maybe we "know" no one else will every touch or change it?)
# Regression in a certain piece of code would have very low ''impact''

== Architectural Decision Records ==

todo

https://adr.github.io/

== Resources ==

todo

Books, links, videos

Code quality guide

2021-05-19T10:10:00Z

Olle: /* Shape design problem */

DRAFT

== Prologue ==

# '''Be risk aware'''. Too good code can be a business risk (slow to write, maybe over-designed). Too sloppy code can also be a business risk (hard to maintain and understand). You have to find a balance that is adapted to the current situation and risk analysis, in which code quality becomes a '''risk mitigation''' technique among others.
# '''Be humble'''. LimeSurvey was made by developers from all over the world, with different age, education and experience. Your code might be read by a completely different team ten years from now, in the same way you are now reading code by developers that no longer work with us, but which work pays our rent.
# '''Performance matters sometimes''', and shouldn't be disregarded completely. In particular, database queries using the ORM and ActiveRecord can be problematic. Some surveys have thousands of questions and hundreds of thousands of responses. Fast response time is also important for a fluid user experience.
# '''It's harder to read code than to write code'''. Don't choose patterns that are easy or fast to write, but that are easy to read.
# Make your code '''communicate intent'''.
# It's easy to forget '''cross-cutting concerns''' like translation and security. Keep a mental note.
# '''Stress affects code quality''' and your risk behaviour. If your stress level is too high to write code with proper quality, take a step back and discuss it with your boss, or you'll push problems to the future.

== Quality ==

The purpose of this guide is to increase the quality of the LimeSurvey code-base. What is quality? Which aspects of quality can be measured? Which kind of company culture gives rise to appropriate code quality?

It's usually easier to get along what is "bad" code than what's "best" code. Blacklist instead of whitelist?

Quality attributes related to code quality:

* Readability
* Testability
* Maintainability
* Performance
* Security
* Reliability

Can not increase all at the same time - performance vs readability.

It's better to avoid emotional language when describing code quality, like "clean" or "dirty". Be precise, objective and suggest solutions.

Idiomatic code is more readable than non-idiomatic code. What's idiomatic depends on which context or domain you work in. We work in PHP and web application development, and have other idioms than in, say, functional or hardware-close programming.

Some code are "hot spots" - changed often. Those parts should require higher quality than other code.

== Risk ==

todo

Couple of different definition of risk:

* Tuple of probability and severity
* Triple of consequence, uncertainty and knowledge base

Possible risks related to LimeSurvey (technical or business):

* Data loss
* Regressions
* Bad UI (higher churn-rate for users)
* Hard to maintain (reduced sprint velocity)
*

How know which is the biggest risk? How many risks can be approached at once?

Connection to architecture. Risk --> quality attributes --> architectural decisions.

usability a business risk - hard to use or understand, people will choose another tool

risks relevant when fixing bugs

risks relevant when adding new features (lack of testing, wrong requirements, scope creep)

risks relevant when refactoring (regressions)

unit tests and QA as risk mitigation

partial deployment, alpha/beta/rc, risk communication

software rot, design pattern rot/grime, software evolution

rot = non-pattern related code

testing by community, bug fixing by community

== Modules ==

There's no inherit module functionality in PHP, but Yii has a module system. Libraries can be seen as a module system.

Examples of implicit modules in LimeSurvey:

* Front-end (survey taking)
* Back-end (survey design)
* Survey theme editing
* Expression manager
* Plugin system

In the future, they need to be separated and implemented more clearly as whatever Yii 3 module system is in use.

Some data models are common for all modules, e.g. surveys and users. Can have a "Common" module for such data.

todo, relation to Yii config system

== Classes ==

* Avoid empty OOP ceremony, like defining getters and setters for all properties. Might as well make them public, ''unless'' they have invariants that need to be upheld, e.g. "this number is always between 1 and 10" or "this string is maximum length 20".
* Almost always avoid static methods. They cannot be mocked. One exception is (possibly) factory methods (Foo::make(...)).
* Inject all dependencies. This will make sure the class can be unit-tested (unit-tests have several benefits over integrity tests - they can be run in parallel and don't require any setup and teardown)
* A second way to achieve testability is to factor out the methods that access the dependencies

todo, state vs behaviour, state vs dependencies

=== OOP design ===

Start from top-down, with domain, behaviour, interaction between objects, database design, pseudo-code if needed. Can also include scenarios, use-cases and UML diagrams.

Object reification - not only domain models, but also domain actions, relations and activities can be objects, e.g. a class ActivateSurvey or ExportSurvey.

Hierarchy depth should be kept reasonable shallow to avoid conflicts between methods, spooky action at a distance. Compare with Yii 3, where controllers no longer inherit anything.

Some people advocate for composition instead of inheritance. Lots of blog posts available for more info.

Multiple inheritance is done with traits in PHP. Use-case: ActiveRecords where some but not all models support encryption.

==== Shape design problem ====

Imagine you have three shapes: Point, rectangle and circle, with the following properties:

* Point: int x, int y
* Rectangle: Point bottomLeft, Point topRight
* Circle: Point center, int radius

Add two behaviours: area(), draw(surface).

* Cohesion: A class (or module) should be responsible for one thing only
* Coupling: You should be able to ''isolate change'' in the system
* Encapsulation: Classes shouldn’t share internal representation
* Polymorphism: The design should be based on interfaces

Questions to consider:

* How easy would it be to move to a 3D representation?
* How easy would it be to add a new shape, say, triangle?
* How easy would it be to add a new behaviour to all shapes, like save/load from a SQL database?
* Which classes ''change together''?

Keep polymorphism and encapsulation - all properties are private.

Example pseudo-code:

forall shapes as shape, do shape.draw(surface)

forall shapes as shape, do surface.draw(shape) (where shape.getDrawData(), or shape.getPath())

=== Software evolution ===

Design rot after time - how to keep it tight? (Grime.)

todo

==== Grime and rot ====

design pattern rot --> lose behaviour relevant for pattern (active record without db connection)

design patter grime --> add behaviour irrelevant for pattern (active record that's also a singleton)

==== Class cohesion ====

[[File:cohesion.png]]

==== Modular coupling ====

[[File:coupling.png]]

Clearer boundaries between classes and modules make it easier to isolate change.

=== State ===

Heuristics to consider but not follow slavishly.

Keep a clear separation between classes with state and classes with no state.

Classes with state should not have dependencies with IO (it's OK to depend on classes in the same application layer, e.g. other DTO classes), and vice versa. ActiveRecord is an example which violates this principle.

class Survey
// Confusion - first params are domain state, last a resource
__construct(id, language, dbConnection)

If a method does not call "this", should it instead be outside the class? A separate class or function, maybe.

todo, elaborate

=== Types of classes ===

Different categories of classes:

* Entity (domain class; has state and validation behaviour)
* Resource (database connection, file, curl, logger; state is in the resource (open, closed))
* Repository classes (database interaction, like splitting ActiveRecord in two parts: Entity class and database interaction)
* DAO, data access object (similar to resource)
* Builders (e.g. query builder, HTML message builder)
* Data-transfer object (no behaviour; pass to views to have better documentation and intent than associative arrays)
* Value classes (e.g. Email address to wrap email string around)
* Command object (e.g. SurveyActivator)
* Helper (no state; e.g. QuestionAttributeHelper to bake attributes into different formats used by the views)
* Wrapper

todo, immutability, possible with private properties that are set in the constructor,

todo: command-query separation for classes?

todo: dependencies between layers, dependencies to the framework

todo, pure vs effectful classes

=== Types of classes in LimeSurvey ===

* ActiveRecord, used to communicate with the database, and should not do ''anything'' else
* Controllers, used for glue code; should not contain business-logic (also CLI controllers)
* Helper functions (not classes, yet...), should be short and obey command-query separation (TODO: Long functions should be separated into command objects or service classes); todo: should not have any dependencies?
* Helper classes, similar to helper functions but have dependencies that need to be mocked during tests; should not have any state
* Service classes, contains logic related to a clear and separate task, like create or import survey
* Question render classes, contains logic related to how questions are rendered (TODO: Need better separation between state and logic and more clear design); similar to widgets
* Plugin classes, using the plugin event system
* Widgets, containing HTML logic for custom HTML widgets
* HTML helpers (Yii)
* Customizations to the Yii framework by inheritance
* Unit and functional test classes

A couple of classes contain only data, like LsDefaultDataSet.

todo, no difference between state property and dependency property in OOP

=== What is "glue code"? ===

todo

Putting the pieces together, e.g. service class A need data from model B, fetch it and run.

todo, add example

=== "Where do I cut?" ===

Separation of concerns, but which concerns and which type of separation? Command-query (function core, imperative shell) is one type of separation. Other separation between layers, e.g. logic layer and data persistency layer (similar in thought).

Other separation, that one class should have a clear purpose. A design pattern should only implement ''one'' pattern, not multiple, and not half a pattern.

There's a problem with "helper" or "manager" classes that they can grow indefinitely, but might be better than nothing. Example when moving business logic out of ActiveRecord class to a helper class it can sometimes hard to be more specific than "helper".

=== Size ===

A class should have a single and clear purpose; compare with [https://en.wikipedia.org/wiki/SOLID SOLID].

=== Class name ===

* ActiveRecord classes are named after the database table they are bound to, but with singular instead of plural. E.g. table "lime_users" have model "User".
* Command classes are named after what they ''do'' and imperatively, e.g. CreateSurvey
* Helper classes should probably be named as specific as possible when possible, to avoid them from growing too big
* Follow the naming tradition of the framework with regard to controllers, e.g. UserController or UserAdministrationController.
* Class properties of ActiveRecord classes will follow the naming of the database, using underscore instead of camel case (and ActiveRecord classes should have ''no'' other properties than those (excluding the database connection injected by the framework))

== Functions ==

Functions are one of the fundamental building blocks of programming, so it's important to get it right.

Functions that are part of a class are called "methods", if you want to be formal.

Different types of functions in PHP:

* Functions (not attached to a class)
* Methods (attached to class)
* Anonymous functions (does not capture scope automatically)
* Short functions (does capture scope automatically)

I'm using "function" as a word for all types of functions in PHP below.

<hr>

=== Size ===

* A function should be short enough to be completely readable on one screen, approx 60 lines at most
* A function should not have too many arguments; if you have five or more, consider making it a class instead
* If a function is growing too big, it might be better to create a class instead or split it into several functions (if both functions have '''common state''', a class might be better, unless you want to pass around '''explicit state''')

=== Contract ===

* A function has a contract with its surrounding environment:
** Pre-condition: What needs to be true before the function is executed
** Post-condition: What will be true after the function has returned
* The function contract can be checked with assertions (internal invariants) or exceptions (outside world); see below
* Another good way is to use unit-tests to make sure the function's contract remains stable through changes
* The first line in the docblock should be one sentence describing the relation between function arguments and its output<br>Example<br><syntaxhighlight lang="php">
/**
* Creates a random password of length $length (defaults to 12)
* @param int $length
* @return string
*/
function createPassword($lenght = 12)

/**
* Creates an HTML language drop down for survey with id $surveyId, marking $selectedLanguage as selected
* @param int $surveyId
* @param string $selectedLanguage
* @return string <select> HTML
*/
function createLanguageDropdown($surveyId, $selectedLanguage)

</syntaxhighlight>

=== Push side-effects up in the stack trace ===

This one is a bit abstract.

First, what is a '''side-effect'''? In short, it's anything that happens in a function that ''is not'' described by the ''relation'' between function arguments and output.

Another way to phrase it is, that a side-effect is anything that is not always the same for the given input to a function; a function without any side-effects will always return the same result if it gets the same input.

'''Examples:'''

<syntaxhighlight lang="php">
// gT accesses the file system and will return different result depending on what's in the translation files
function gT($sToTranslate, $sEscapeMode = 'html', $sLanguage = null);

// If $sText and $sEscapeMode is always the same, quoteText() will always return the same string.
function quoteText($sText, $sEscapeMode = 'html');
</syntaxhighlight>

A function with no side-effects is called '''pure'''. A function that is guaranteed to always return (no exceptions, no errors, no warnings, no division by zero) is called '''total'''.

It's a good thing if functions in a code-base ''either'' have side-effects, ''or'' return a result. Not both. This is called [https://en.wikipedia.org/wiki/Command%E2%80%93query_separation command-query separation].

Examples of side-effects:

* Database or file access
* Echo, or write to stdout or stderr
* Randomization

Why does this matter? Because side-effects make testing harder! '''If you have side-effects, you cannot create unit tests''', ''unless'' those side-effects can be mocked. If not, you need integrity tests with database setup or more. The more side-effects you have in a function, the more mocking is required to unit test it.

So, one solution to this is to move side-effects higher up in the stack trace, that is, move them to the calling code.

'''Example:'''

<syntaxhighlight lang="php">
function getSurveyInfo(int $surveyid, string $languagecode = '', boolean $force = false): array;
</syntaxhighlight>

Since this function takes $surveyid, we know it will probably query the database. Quering the database is a side-effect, and thus it requires a database scaffold for the test (or mocking, but the database connection is not injected, so there's no way to do it). One simple solution is to lift the side-effect out and pass in a Survey object instead:

<syntaxhighlight lang="php">
function getSurveyInfo(Survey $survey, string $languagecode = '', boolean $force = false): array;
</syntaxhighlight>

Much better! The side-effect of calling the database now happens ''before'' the function call. Now we can either mock a Survey object, or make an imitating stub for our test.

Reading the function body, there is in fact another database access, but since this is a relation to the Survey model, it could easily be moved out too. We've just made a function testable! Hooray!

This principle is rephrased in an architectural settings as [https://github.com/kbilsted/Functional-core-imperative-shell/blob/master/README.md functional core, imperative shell]. This architecture helps you get a good ratio between fast unit tests and slower integrity tests.

Moving side-effects up makes sure we can have a healthy ratio between integrity tests with scripted browser, and unit-tests; maybe around 20-80.

=== Function name ===

* The function name should tell you '''what''' it does; docs should tell you '''why''' (if this information is not obvious). '''How''' is described by the code itself (hopefully, but can in some cases be relevant to document).
* Function name can often be '''verb [+ adjective] + noun''', like "createFieldmap", "quoteText", "getRelativePath"
* Prefix with "is" for boolean functions

todo: difference between create, get, fetch, generate, ...

'''Good examples:'''

* createPassword() - One verb, one noun - clear
* isCaptchaEnabled() - Using "is" signifies it returns boolean; clear purpose
* getFullResponseTable() - Verb, adjective, noun - but is "full" needed here? Is there a non-full version of the same function?
* replaceExpressionCodes() - Pretty good, but it's obvious that more information is needed in the docblock to describe what "replace" means, and what an "expression code" is
* fixCKeditorText() - "fix" is a bit vague, but maybe best there is? Pray that docblock contains information!

'''Bad examples:'''

* languageDropdown() - No verb, doesn't tell you what it does
* rmdirr() - Two r's, looks like a typo, but the last "r" actually means "recursive"! Better: rmdir($recursive = false), rmdir or removeFolder.
* CSVUnquote() - Is CSV really the namespace? Why is the verb the second word?
* incompleteAnsFilterState() - One verb, but in the middle, or is "filter state" a noun?; why abbreviate "answer" to "ans"?
* reverseTranslateFieldNames() - Two verbs - did author mean "reverseTranslatedFieldNames"? Or "reverse and translate"? If so, it should be two functions, one for reverse and one for translate
* checkUploadedFileSizeAndRenderJson() - If you have an "and" in the function name, you should consider splitting it into two functions

'''Controversial'''

* gT() - An exception to descriptive function names; since this is used everywhere, the minimal name is motivated; maybe even name it "t()"? Still hard to read for someone who just started? But Yii uses t() too? Other frameworks use double underscore (Wordpress, Laravel) as function name.

<hr>

=== Function filename and namespace ===

If your function has dependencies or side-effects, it should be put into a class instead, in which the dependencies can be injected. Another alternative is to put the dependencies as argument in the function, although this muffles the relationship between input and output. Again, this is to increase testability.

Keep in mind that functions outside classes cannot be mocked, so only use them when you ''know'' you won't need to mock them.

todo, autoloading of functions and folder location

=== Assertions ===

NB: This is not assertions as used in unit-tests, but assertions as used to check invariants in production code.

Assertions can be used for mental checks. They are only used for internal logic - failed assertions are not supposed to be seen by the end user. For interaction with the outside world, like database or browser, exceptions should be used instead.

Assertions can be disabled in production mode and have then no runtime cost (since PHP 7).

'''Example:'''

<syntaxhighlight lang="php">
/**
* Translation helper function
*
* @param string $sToTranslate
* @param string $sEscapeMode Valid values are html (this is the default, js and unescaped)
* @param string $sLanguage
* @return string
*/
function gT($sToTranslate, $sEscapeMode = 'html', $sLanguage = null)
{
assert(is_string($sToTranslate));
assert(strlen($sToTranslate) > 0);
assert($sEscapeMode === 'html' || $sEscapeMode === 'js' || $sEscapeMode === 'unescaped');
return quoteText(Yii::t('', $sToTranslate, array(), null, $sLanguage), $sEscapeMode);
}
</syntaxhighlight>

<hr>

=== Exceptions ===

todo

todo: exception hierarchy

todo: what can be repaired after exception? transaction rollback

* Exceptions are used to check inputs from the outside world (browser, database, file system)
* Don't use exceptions for control flow, only when fatal errors happen that make further execution impossible
* Exceptions should have clear error messages that make them ''actionable'' - there should be a clear "next step" for the user or developer
* Never, ever, do an empty catch-block

==== Alternatives to exceptions ====

Some people consider exceptions being a hidden form of "goto" which confuses the control flow of the program. They propose different other solutions:

* Return a tuple, like <code>[$result, $errorMessage]</code> where $errorMessage is null at success
* Return <code>null</code> at failure
* Tagged union result type (not yet possible in latest PHP)
* Result object

The con being that you have to manually propagate the error, where an exception can happen from anywhere in the stack trace without any other function knowing about it.

=== If-statements ===

If-statements should not be too long or hard to understand. If they are, consider factor out the checks into separate functions.

<syntaxhighlight lang="php">
if ((empty($instance->oOptions->{$attribute}))
|| (
!empty($instance->oOptions->{$attribute})
&& (
$instance->oOptions->{$attribute} === 'inherit'
|| $instance->oOptions->{$attribute} === 'I'
// NB: Do NOT use === here, it won't work with Postgresql.
|| $instance->oOptions->{$attribute} == '-1'
)
)
) {
</syntaxhighlight>

Can be shortened by factoring out method <code>isInherit</code>:

<syntaxhighlight lang="php">
if (empty($instance->options->{$attribute})
|| $this->isInherit($instance-options->{$attribute})) {
}
/**
* Returns true if $value is set to inherit
* @param mixed|null $value
* @return boolean
*/
public function isInherit($value) {
return !empty($value)
&& (
$value === 'inherit'
|| $value === 'I'
// NB: Do NOT use === here, it won't work with Postgresql.
|| $value == '-1'
);
}
</syntaxhighlight>

And one more time by using a variable for the value:

<syntaxhighlight lang="php">
$value = $instance->options->{$attribute};
if (empty($value) || $this->isInherit($value)) {
}
</syntaxhighlight>

More clear, right? "If it's empty or set to inherit, do this and that."

=== Variables ===

Descriptive naming.

* Follow PSR-12 - no underscore, use camelCaseLikeThis
* Variables of ActiveRecord classes can have same name as the class, like "$survey" or "$question"
* Add -s for plural when it's a list of items: "$surveys", "$questions"
* Never include "array" or "list" in variable names - using plural is enough (for lists, not for associative arrays - see below)
* The ''context'' of the function helps with variable naming, e..g "$name" might be fine in a function about questions; this is extra helpful when functions are short!
* When a function is short, it's much easier to figure out variable meaning based on context
* $qid, $gid, and $sid are so established in the code-base that they could be considered OK
* The -data suffix means "blob of stuff", only use it when needed, like with $viewData
* Use $result when baking a return value; add its exact type as @var annotation (worst possible name, acceptable but anything with more meaning is better)

Not so good:

<syntaxhighlight lang="php">
$result = LabelSet::model()->findAll();
</syntaxhighlight>

Better with model name and -s for plural:

<syntaxhighlight lang="php">
$labelSets = LabelSet::model()->findAll();
</syntaxhighlight>

* Do not use Hungarian notation (prefix with "type"), but instead <code>/** @var */</code> annotations - these can be checked automatically and will then be enforced to be correct, unlike Hungarian notation which can "rot"

<syntaxhighlight lang="php">
/** string[] An array of strings with 0-n elements */
$allFields = [];
</syntaxhighlight>

Psalm can infer types if the function documentation is enough. The strictness can be adjusted. Not all variables will need @var annotation, the tool will warn you when it's confused.

* Data that is sent to views as associative arrays will be:

<syntaxhighlight lang="php">
/** @var array Can be basically anything :( Better would be data-transfer objects or more precise notation */
$data = [];
// Maybe more clear as $viewData? Discuss.
</syntaxhighlight>

You can be more precise when you specify which type of array you're writing:

<syntaxhighlight lang="php">
/** @var array<string, string> This means the array key is string, and the array value is also string */
$data = [];
$data['name'] = 'Olle';
$data['occupation'] = 'Developer';
$data['age'] = 38; // ERROR! Value must be string.
</syntaxhighlight>

For more info about array type notation, see the [https://psalm.dev/docs/annotating_code/type_syntax/array_types/ Psalm documentation].

Some smaller examples:

<syntaxhighlight lang="php">
$theme = App()->request->getPost('theme'); // Should be $themeType - $theme looks like a model/AR
$gridid === 'questionthemes-grid'; // Should be $gridId with capital "I", since it's two words in English
$delete = Yii::app()->request->getParam('delete'); // Tuff one - $delete is ok? Thoughts?
$files = json_decode(stripslashes($sJSON), true); // $file is a resource, $files an array of resources, this is $fileData perhaps?
$valid_extensions_array = explode(",", $aAttributes['allowed_filetypes']); // Should be $validExtensionTypes
$language = Yii::app()->session['survey_' . $surveyid]['s_lang']; // TODO: Should this be a value class? Then Language::make(...);
$surveyInfo = getSurveyInfo($surveyId, $language); // OK, BUT should be a separate DTO!
$fieldMap = createFieldMap($survey, 'short', false, false, $language); // Same, make a DTO
$cquestions = array(); // What's "c"? Method name is getChildQuestions and $questions is an argument - better with $childQuestions?
</syntaxhighlight>

Links:

[https://www.approxion.com/capital-offenses-how-to-handle-abbreviations-in-camelcase/ How to Handle Abbreviations in CamelCase]

[https://stackoverflow.com/questions/15526107/acronyms-in-camelcase Acronyms in CamelCase]

=== Looping ===

* The bodies of foreach-loops are often a good candidate to factor out into separate functions.

'''Example:'''

<syntaxhighlight lang="php">
foreach ($questions as $question) {
processQuestion($question);
}
</syntaxhighlight>

Note the variable naming from plural to singular.

* Loop indexing should be named i, j, k etc.

'''Example:'''

<syntaxhighlight lang="php">
for ($i = 0; $i < $length; $i++) {
for ($j = 0; $j < $otherLength; $j++) {
// ...
}
}
</syntaxhighlight>

<hr>

=== Function composition ===

todo, "doThisAndThat" --> "doThis(doThat())"

=== Cases ===

<syntaxhighlight lang="php">
/**
* This function generates an array containing the fieldcode, and matching data in the same order as the activate script
*
* @param Survey $survey Survey ActiveRecord model
* @param string $style 'short' (default) or 'full' - full creates extra information like default values
* @param boolean $force_refresh - Forces to really refresh the array, not just take the session copy
* @param bool|int $questionid Limit to a certain qid only (for question preview) - default is false
* @param string $sLanguage The language to use
* @param array $aDuplicateQIDs
* @return array
*/
function createFieldMap($survey, $style = 'short', $force_refresh = false, $questionid = false, $sLanguage = '', &$aDuplicateQIDs = array())
</syntaxhighlight>

'''Good:'''

* Name is verb and noun
* Each argument is documented (almost)

'''Bad:'''

* Returns "array", which can be anything. A separate class for "Fieldmap" would be better.
* Not clear if it should be "createFieldMap" or "createFieldmap" - is "fieldmap" one word or two?
* Very many boolean arguments. Should probably be a class with methods like <code>$fieldmapCreator->setForceRefresh(true);</code> instead.
* Too long.
* Doesn't elaborate on what "fieldmap" really is, and does not link to any documentation about it.
* Access super-global, which makes it hard to test. Should instead return a data-transfer object, like:<br><syntaxhighlight lang="php">
$_SESSION['fieldmap'] = createFieldMap(...);
</syntaxhighlight>
* Has no test
* Mixes Hungarian notation with non-Hungarian notation in the argument list

== Defensive programming and error handling ==

todo

* '''Fail hard, fail early'''. The earlier the program crashes when something is wrong, the lower is the probability that you'll end up with corrupt data in the database that will later require manual labor to correct.
* Fail with '''actionable information'''
* Check input to functions and throw <code>InvalidArgumentException</code> if it violates the function's pre-conditions
* Use assert for class-internal invariants
* Use assert to make assumptions explicit for the reader

== Documentation ==

=== PHPDoc ===

* All functions must have a proper docblock
* The first line of the docblock should describe the relation between ''all'' the input arguments and the output of the function in a single sentence
* Each parameter must have the correct type
* Don't use <code>array</code> as type if it's a list of object - instead, use <code>[]</code> like so: <code>Survey[]</code> for a list of surveys

=== Technical documentation ===

todo, UML, scenarios, use-cases

== The PHP of yesterday ==

Old idioms and habits that should be abandoned.

* Don't use associative arrays, almost never. Data-transfer objects have multiple benefits: they are clearly structured, can be documented, can enforce invariants. There's ''no'' performance overhead of objects compared to arrays in modern PHP.
* Objects are already passed by reference; arrays are value types
* Use <code>[]</code> instead of <code>array()</code>
* Hungarian notation was useful before static analysis existed for PHP. These days it's better to use something that can be checked automatically: docblock @param and inline @var annotations.

== The PHP of tomorrow ==

todo

Union tags

Short functions

Match expressions

== Security ==

todo

XSS

Database injection

Permissions and roles

== Performance ==

todo

Loading too many rows into PHP models

== Testing ==

todo

QA

PHPUnit

TDD

Mocks, can't mock functions, static methods, mocking as a DSL, PHPUnit mocking tools

Pure functions, referential transparency, side-effects

Unit, functional, integration

Don't test the framework; don't test PHP

Makes sure the function or class lives up to its specification; make sure it will ''always'' live up to its specification, even in the future, to avoid regressions.

== Static analysis ==

<code>php -l</code>, CodeSniffer, Mess Detector, Psalm

== Database design ==

todo

== JavaScript ==

todo

classes, functions, components, tests

== CSS ==

todo

== HTML ==

todo

== Feedback ==

=== "Why do I have to refactor code that works?" ===

todo, Sadly, it's not enough for the code to live up to the current specification and requirements, it must also be protected against future changes, regressions. Adding tests is the best way for this. Lots of people might read and change the LimeSurvey code the next 5-10 years. The test suite creates a security layer to make sure the specification is fulfilled even as the code changes.

Tests are not a magical solution, however. It does not protect us against other degradation of the code quality, like classes gaining too much responsibility (too many methods, unrelated methods, too many properties).

=== "What's the correct ratio between integrity tests and unit tests?" ===

todo, Don't know. Different pros and cons.

* Unit-test can be run in parallel and are faster
* Unit-tests don't need setup and teardown

Cons of unit-tests is that they need a bigger effort on the side of the developer to make them possible, for example injecting the dependencies properly to enable mocking, or lifting side-effects up in the stack trace.

=== How to disagree ===

All rules can be broken. To break a rule, you should reason in terms of risk and the assumptions used in this guide.

'''Assumptions:'''

# Regressions are the biggest technical risk for LimeSurvey the last five years (2021)
# Automated tests are the best risk mitigation technique against regressions

'''Possible disagreement:'''

# A certain piece of code has very low ''probability'' of regressions (maybe we "know" no one else will every touch or change it?)
# Regression in a certain piece of code would have very low ''impact''

== Architectural Decision Records ==

todo

https://adr.github.io/

== Resources ==

todo

Books, links, videos

Code quality guide

2021-05-19T10:07:59Z

Olle: /* Modular coupling */

DRAFT

== Prologue ==

# '''Be risk aware'''. Too good code can be a business risk (slow to write, maybe over-designed). Too sloppy code can also be a business risk (hard to maintain and understand). You have to find a balance that is adapted to the current situation and risk analysis, in which code quality becomes a '''risk mitigation''' technique among others.
# '''Be humble'''. LimeSurvey was made by developers from all over the world, with different age, education and experience. Your code might be read by a completely different team ten years from now, in the same way you are now reading code by developers that no longer work with us, but which work pays our rent.
# '''Performance matters sometimes''', and shouldn't be disregarded completely. In particular, database queries using the ORM and ActiveRecord can be problematic. Some surveys have thousands of questions and hundreds of thousands of responses. Fast response time is also important for a fluid user experience.
# '''It's harder to read code than to write code'''. Don't choose patterns that are easy or fast to write, but that are easy to read.
# Make your code '''communicate intent'''.
# It's easy to forget '''cross-cutting concerns''' like translation and security. Keep a mental note.
# '''Stress affects code quality''' and your risk behaviour. If your stress level is too high to write code with proper quality, take a step back and discuss it with your boss, or you'll push problems to the future.

== Quality ==

The purpose of this guide is to increase the quality of the LimeSurvey code-base. What is quality? Which aspects of quality can be measured? Which kind of company culture gives rise to appropriate code quality?

It's usually easier to get along what is "bad" code than what's "best" code. Blacklist instead of whitelist?

Quality attributes related to code quality:

* Readability
* Testability
* Maintainability
* Performance
* Security
* Reliability

Can not increase all at the same time - performance vs readability.

It's better to avoid emotional language when describing code quality, like "clean" or "dirty". Be precise, objective and suggest solutions.

Idiomatic code is more readable than non-idiomatic code. What's idiomatic depends on which context or domain you work in. We work in PHP and web application development, and have other idioms than in, say, functional or hardware-close programming.

Some code are "hot spots" - changed often. Those parts should require higher quality than other code.

== Risk ==

todo

Couple of different definition of risk:

* Tuple of probability and severity
* Triple of consequence, uncertainty and knowledge base

Possible risks related to LimeSurvey (technical or business):

* Data loss
* Regressions
* Bad UI (higher churn-rate for users)
* Hard to maintain (reduced sprint velocity)
*

How know which is the biggest risk? How many risks can be approached at once?

Connection to architecture. Risk --> quality attributes --> architectural decisions.

usability a business risk - hard to use or understand, people will choose another tool

risks relevant when fixing bugs

risks relevant when adding new features (lack of testing, wrong requirements, scope creep)

risks relevant when refactoring (regressions)

unit tests and QA as risk mitigation

partial deployment, alpha/beta/rc, risk communication

software rot, design pattern rot/grime, software evolution

rot = non-pattern related code

testing by community, bug fixing by community

== Modules ==

There's no inherit module functionality in PHP, but Yii has a module system. Libraries can be seen as a module system.

Examples of implicit modules in LimeSurvey:

* Front-end (survey taking)
* Back-end (survey design)
* Survey theme editing
* Expression manager
* Plugin system

In the future, they need to be separated and implemented more clearly as whatever Yii 3 module system is in use.

Some data models are common for all modules, e.g. surveys and users. Can have a "Common" module for such data.

todo, relation to Yii config system

== Classes ==

* Avoid empty OOP ceremony, like defining getters and setters for all properties. Might as well make them public, ''unless'' they have invariants that need to be upheld, e.g. "this number is always between 1 and 10" or "this string is maximum length 20".
* Almost always avoid static methods. They cannot be mocked. One exception is (possibly) factory methods (Foo::make(...)).
* Inject all dependencies. This will make sure the class can be unit-tested (unit-tests have several benefits over integrity tests - they can be run in parallel and don't require any setup and teardown)
* A second way to achieve testability is to factor out the methods that access the dependencies

todo, state vs behaviour, state vs dependencies

=== OOP design ===

Start from top-down, with domain, behaviour, interaction between objects, database design, pseudo-code if needed. Can also include scenarios, use-cases and UML diagrams.

Object reification - not only domain models, but also domain actions, relations and activities can be objects, e.g. a class ActivateSurvey or ExportSurvey.

Hierarchy depth should be kept reasonable shallow to avoid conflicts between methods, spooky action at a distance. Compare with Yii 3, where controllers no longer inherit anything.

Some people advocate for composition instead of inheritance. Lots of blog posts available for more info.

Multiple inheritance is done with traits in PHP. Use-case: ActiveRecords where some but not all models support encryption.

==== Shape design problem ====

Point (x, y), rectangle (bottomLeft, topRight), circle (point, radius (int))

Area, draw

* Cohesion: A class (or module) should be responsible for one thing only
* Coupling: You should be able to ''isolate change'' in the system
* Encapsulation: Classes shouldn’t share internal representation
* Polymorphism: The design should be based on interfaces

Questions to consider:

* How easy would it be to move to a 3D representation?
* How easy would it be to add a new shape, say, triangle?
* How easy would it be to add a new behaviour to all shapes, like save/load from a SQL database?
* Which classes ''change together''?

Keep polymorphism and encapsulation - all properties are private.

forall shapes as shape, do shape.draw(surface)

forall shapes as shape, do surface.draw(shape) (where shape.getDrawData(), or shape.getPath())

=== Software evolution ===

Design rot after time - how to keep it tight? (Grime.)

todo

==== Grime and rot ====

design pattern rot --> lose behaviour relevant for pattern (active record without db connection)

design patter grime --> add behaviour irrelevant for pattern (active record that's also a singleton)

==== Class cohesion ====

[[File:cohesion.png]]

==== Modular coupling ====

[[File:coupling.png]]

Clearer boundaries between classes and modules make it easier to isolate change.

=== State ===

Heuristics to consider but not follow slavishly.

Keep a clear separation between classes with state and classes with no state.

Classes with state should not have dependencies with IO (it's OK to depend on classes in the same application layer, e.g. other DTO classes), and vice versa. ActiveRecord is an example which violates this principle.

class Survey
// Confusion - first params are domain state, last a resource
__construct(id, language, dbConnection)

If a method does not call "this", should it instead be outside the class? A separate class or function, maybe.

todo, elaborate

=== Types of classes ===

Different categories of classes:

* Entity (domain class; has state and validation behaviour)
* Resource (database connection, file, curl, logger; state is in the resource (open, closed))
* Repository classes (database interaction, like splitting ActiveRecord in two parts: Entity class and database interaction)
* DAO, data access object (similar to resource)
* Builders (e.g. query builder, HTML message builder)
* Data-transfer object (no behaviour; pass to views to have better documentation and intent than associative arrays)
* Value classes (e.g. Email address to wrap email string around)
* Command object (e.g. SurveyActivator)
* Helper (no state; e.g. QuestionAttributeHelper to bake attributes into different formats used by the views)
* Wrapper

todo, immutability, possible with private properties that are set in the constructor,

todo: command-query separation for classes?

todo: dependencies between layers, dependencies to the framework

todo, pure vs effectful classes

=== Types of classes in LimeSurvey ===

* ActiveRecord, used to communicate with the database, and should not do ''anything'' else
* Controllers, used for glue code; should not contain business-logic (also CLI controllers)
* Helper functions (not classes, yet...), should be short and obey command-query separation (TODO: Long functions should be separated into command objects or service classes); todo: should not have any dependencies?
* Helper classes, similar to helper functions but have dependencies that need to be mocked during tests; should not have any state
* Service classes, contains logic related to a clear and separate task, like create or import survey
* Question render classes, contains logic related to how questions are rendered (TODO: Need better separation between state and logic and more clear design); similar to widgets
* Plugin classes, using the plugin event system
* Widgets, containing HTML logic for custom HTML widgets
* HTML helpers (Yii)
* Customizations to the Yii framework by inheritance
* Unit and functional test classes

A couple of classes contain only data, like LsDefaultDataSet.

todo, no difference between state property and dependency property in OOP

=== What is "glue code"? ===

todo

Putting the pieces together, e.g. service class A need data from model B, fetch it and run.

todo, add example

=== "Where do I cut?" ===

Separation of concerns, but which concerns and which type of separation? Command-query (function core, imperative shell) is one type of separation. Other separation between layers, e.g. logic layer and data persistency layer (similar in thought).

Other separation, that one class should have a clear purpose. A design pattern should only implement ''one'' pattern, not multiple, and not half a pattern.

There's a problem with "helper" or "manager" classes that they can grow indefinitely, but might be better than nothing. Example when moving business logic out of ActiveRecord class to a helper class it can sometimes hard to be more specific than "helper".

=== Size ===

A class should have a single and clear purpose; compare with [https://en.wikipedia.org/wiki/SOLID SOLID].

=== Class name ===

* ActiveRecord classes are named after the database table they are bound to, but with singular instead of plural. E.g. table "lime_users" have model "User".
* Command classes are named after what they ''do'' and imperatively, e.g. CreateSurvey
* Helper classes should probably be named as specific as possible when possible, to avoid them from growing too big
* Follow the naming tradition of the framework with regard to controllers, e.g. UserController or UserAdministrationController.
* Class properties of ActiveRecord classes will follow the naming of the database, using underscore instead of camel case (and ActiveRecord classes should have ''no'' other properties than those (excluding the database connection injected by the framework))

== Functions ==

Functions are one of the fundamental building blocks of programming, so it's important to get it right.

Functions that are part of a class are called "methods", if you want to be formal.

Different types of functions in PHP:

* Functions (not attached to a class)
* Methods (attached to class)
* Anonymous functions (does not capture scope automatically)
* Short functions (does capture scope automatically)

I'm using "function" as a word for all types of functions in PHP below.

<hr>

=== Size ===

* A function should be short enough to be completely readable on one screen, approx 60 lines at most
* A function should not have too many arguments; if you have five or more, consider making it a class instead
* If a function is growing too big, it might be better to create a class instead or split it into several functions (if both functions have '''common state''', a class might be better, unless you want to pass around '''explicit state''')

=== Contract ===

* A function has a contract with its surrounding environment:
** Pre-condition: What needs to be true before the function is executed
** Post-condition: What will be true after the function has returned
* The function contract can be checked with assertions (internal invariants) or exceptions (outside world); see below
* Another good way is to use unit-tests to make sure the function's contract remains stable through changes
* The first line in the docblock should be one sentence describing the relation between function arguments and its output<br>Example<br><syntaxhighlight lang="php">
/**
* Creates a random password of length $length (defaults to 12)
* @param int $length
* @return string
*/
function createPassword($lenght = 12)

/**
* Creates an HTML language drop down for survey with id $surveyId, marking $selectedLanguage as selected
* @param int $surveyId
* @param string $selectedLanguage
* @return string <select> HTML
*/
function createLanguageDropdown($surveyId, $selectedLanguage)

</syntaxhighlight>

=== Push side-effects up in the stack trace ===

This one is a bit abstract.

First, what is a '''side-effect'''? In short, it's anything that happens in a function that ''is not'' described by the ''relation'' between function arguments and output.

Another way to phrase it is, that a side-effect is anything that is not always the same for the given input to a function; a function without any side-effects will always return the same result if it gets the same input.

'''Examples:'''

<syntaxhighlight lang="php">
// gT accesses the file system and will return different result depending on what's in the translation files
function gT($sToTranslate, $sEscapeMode = 'html', $sLanguage = null);

// If $sText and $sEscapeMode is always the same, quoteText() will always return the same string.
function quoteText($sText, $sEscapeMode = 'html');
</syntaxhighlight>

A function with no side-effects is called '''pure'''. A function that is guaranteed to always return (no exceptions, no errors, no warnings, no division by zero) is called '''total'''.

It's a good thing if functions in a code-base ''either'' have side-effects, ''or'' return a result. Not both. This is called [https://en.wikipedia.org/wiki/Command%E2%80%93query_separation command-query separation].

Examples of side-effects:

* Database or file access
* Echo, or write to stdout or stderr
* Randomization

Why does this matter? Because side-effects make testing harder! '''If you have side-effects, you cannot create unit tests''', ''unless'' those side-effects can be mocked. If not, you need integrity tests with database setup or more. The more side-effects you have in a function, the more mocking is required to unit test it.

So, one solution to this is to move side-effects higher up in the stack trace, that is, move them to the calling code.

'''Example:'''

<syntaxhighlight lang="php">
function getSurveyInfo(int $surveyid, string $languagecode = '', boolean $force = false): array;
</syntaxhighlight>

Since this function takes $surveyid, we know it will probably query the database. Quering the database is a side-effect, and thus it requires a database scaffold for the test (or mocking, but the database connection is not injected, so there's no way to do it). One simple solution is to lift the side-effect out and pass in a Survey object instead:

<syntaxhighlight lang="php">
function getSurveyInfo(Survey $survey, string $languagecode = '', boolean $force = false): array;
</syntaxhighlight>

Much better! The side-effect of calling the database now happens ''before'' the function call. Now we can either mock a Survey object, or make an imitating stub for our test.

Reading the function body, there is in fact another database access, but since this is a relation to the Survey model, it could easily be moved out too. We've just made a function testable! Hooray!

This principle is rephrased in an architectural settings as [https://github.com/kbilsted/Functional-core-imperative-shell/blob/master/README.md functional core, imperative shell]. This architecture helps you get a good ratio between fast unit tests and slower integrity tests.

Moving side-effects up makes sure we can have a healthy ratio between integrity tests with scripted browser, and unit-tests; maybe around 20-80.

=== Function name ===

* The function name should tell you '''what''' it does; docs should tell you '''why''' (if this information is not obvious). '''How''' is described by the code itself (hopefully, but can in some cases be relevant to document).
* Function name can often be '''verb [+ adjective] + noun''', like "createFieldmap", "quoteText", "getRelativePath"
* Prefix with "is" for boolean functions

todo: difference between create, get, fetch, generate, ...

'''Good examples:'''

* createPassword() - One verb, one noun - clear
* isCaptchaEnabled() - Using "is" signifies it returns boolean; clear purpose
* getFullResponseTable() - Verb, adjective, noun - but is "full" needed here? Is there a non-full version of the same function?
* replaceExpressionCodes() - Pretty good, but it's obvious that more information is needed in the docblock to describe what "replace" means, and what an "expression code" is
* fixCKeditorText() - "fix" is a bit vague, but maybe best there is? Pray that docblock contains information!

'''Bad examples:'''

* languageDropdown() - No verb, doesn't tell you what it does
* rmdirr() - Two r's, looks like a typo, but the last "r" actually means "recursive"! Better: rmdir($recursive = false), rmdir or removeFolder.
* CSVUnquote() - Is CSV really the namespace? Why is the verb the second word?
* incompleteAnsFilterState() - One verb, but in the middle, or is "filter state" a noun?; why abbreviate "answer" to "ans"?
* reverseTranslateFieldNames() - Two verbs - did author mean "reverseTranslatedFieldNames"? Or "reverse and translate"? If so, it should be two functions, one for reverse and one for translate
* checkUploadedFileSizeAndRenderJson() - If you have an "and" in the function name, you should consider splitting it into two functions

'''Controversial'''

* gT() - An exception to descriptive function names; since this is used everywhere, the minimal name is motivated; maybe even name it "t()"? Still hard to read for someone who just started? But Yii uses t() too? Other frameworks use double underscore (Wordpress, Laravel) as function name.

<hr>

=== Function filename and namespace ===

If your function has dependencies or side-effects, it should be put into a class instead, in which the dependencies can be injected. Another alternative is to put the dependencies as argument in the function, although this muffles the relationship between input and output. Again, this is to increase testability.

Keep in mind that functions outside classes cannot be mocked, so only use them when you ''know'' you won't need to mock them.

todo, autoloading of functions and folder location

=== Assertions ===

NB: This is not assertions as used in unit-tests, but assertions as used to check invariants in production code.

Assertions can be used for mental checks. They are only used for internal logic - failed assertions are not supposed to be seen by the end user. For interaction with the outside world, like database or browser, exceptions should be used instead.

Assertions can be disabled in production mode and have then no runtime cost (since PHP 7).

'''Example:'''

<syntaxhighlight lang="php">
/**
* Translation helper function
*
* @param string $sToTranslate
* @param string $sEscapeMode Valid values are html (this is the default, js and unescaped)
* @param string $sLanguage
* @return string
*/
function gT($sToTranslate, $sEscapeMode = 'html', $sLanguage = null)
{
assert(is_string($sToTranslate));
assert(strlen($sToTranslate) > 0);
assert($sEscapeMode === 'html' || $sEscapeMode === 'js' || $sEscapeMode === 'unescaped');
return quoteText(Yii::t('', $sToTranslate, array(), null, $sLanguage), $sEscapeMode);
}
</syntaxhighlight>

<hr>

=== Exceptions ===

todo

todo: exception hierarchy

todo: what can be repaired after exception? transaction rollback

* Exceptions are used to check inputs from the outside world (browser, database, file system)
* Don't use exceptions for control flow, only when fatal errors happen that make further execution impossible
* Exceptions should have clear error messages that make them ''actionable'' - there should be a clear "next step" for the user or developer
* Never, ever, do an empty catch-block

==== Alternatives to exceptions ====

Some people consider exceptions being a hidden form of "goto" which confuses the control flow of the program. They propose different other solutions:

* Return a tuple, like <code>[$result, $errorMessage]</code> where $errorMessage is null at success
* Return <code>null</code> at failure
* Tagged union result type (not yet possible in latest PHP)
* Result object

The con being that you have to manually propagate the error, where an exception can happen from anywhere in the stack trace without any other function knowing about it.

=== If-statements ===

If-statements should not be too long or hard to understand. If they are, consider factor out the checks into separate functions.

<syntaxhighlight lang="php">
if ((empty($instance->oOptions->{$attribute}))
|| (
!empty($instance->oOptions->{$attribute})
&& (
$instance->oOptions->{$attribute} === 'inherit'
|| $instance->oOptions->{$attribute} === 'I'
// NB: Do NOT use === here, it won't work with Postgresql.
|| $instance->oOptions->{$attribute} == '-1'
)
)
) {
</syntaxhighlight>

Can be shortened by factoring out method <code>isInherit</code>:

<syntaxhighlight lang="php">
if (empty($instance->options->{$attribute})
|| $this->isInherit($instance-options->{$attribute})) {
}
/**
* Returns true if $value is set to inherit
* @param mixed|null $value
* @return boolean
*/
public function isInherit($value) {
return !empty($value)
&& (
$value === 'inherit'
|| $value === 'I'
// NB: Do NOT use === here, it won't work with Postgresql.
|| $value == '-1'
);
}
</syntaxhighlight>

And one more time by using a variable for the value:

<syntaxhighlight lang="php">
$value = $instance->options->{$attribute};
if (empty($value) || $this->isInherit($value)) {
}
</syntaxhighlight>

More clear, right? "If it's empty or set to inherit, do this and that."

=== Variables ===

Descriptive naming.

* Follow PSR-12 - no underscore, use camelCaseLikeThis
* Variables of ActiveRecord classes can have same name as the class, like "$survey" or "$question"
* Add -s for plural when it's a list of items: "$surveys", "$questions"
* Never include "array" or "list" in variable names - using plural is enough (for lists, not for associative arrays - see below)
* The ''context'' of the function helps with variable naming, e..g "$name" might be fine in a function about questions; this is extra helpful when functions are short!
* When a function is short, it's much easier to figure out variable meaning based on context
* $qid, $gid, and $sid are so established in the code-base that they could be considered OK
* The -data suffix means "blob of stuff", only use it when needed, like with $viewData
* Use $result when baking a return value; add its exact type as @var annotation (worst possible name, acceptable but anything with more meaning is better)

Not so good:

<syntaxhighlight lang="php">
$result = LabelSet::model()->findAll();
</syntaxhighlight>

Better with model name and -s for plural:

<syntaxhighlight lang="php">
$labelSets = LabelSet::model()->findAll();
</syntaxhighlight>

* Do not use Hungarian notation (prefix with "type"), but instead <code>/** @var */</code> annotations - these can be checked automatically and will then be enforced to be correct, unlike Hungarian notation which can "rot"

<syntaxhighlight lang="php">
/** string[] An array of strings with 0-n elements */
$allFields = [];
</syntaxhighlight>

Psalm can infer types if the function documentation is enough. The strictness can be adjusted. Not all variables will need @var annotation, the tool will warn you when it's confused.

* Data that is sent to views as associative arrays will be:

<syntaxhighlight lang="php">
/** @var array Can be basically anything :( Better would be data-transfer objects or more precise notation */
$data = [];
// Maybe more clear as $viewData? Discuss.
</syntaxhighlight>

You can be more precise when you specify which type of array you're writing:

<syntaxhighlight lang="php">
/** @var array<string, string> This means the array key is string, and the array value is also string */
$data = [];
$data['name'] = 'Olle';
$data['occupation'] = 'Developer';
$data['age'] = 38; // ERROR! Value must be string.
</syntaxhighlight>

For more info about array type notation, see the [https://psalm.dev/docs/annotating_code/type_syntax/array_types/ Psalm documentation].

Some smaller examples:

<syntaxhighlight lang="php">
$theme = App()->request->getPost('theme'); // Should be $themeType - $theme looks like a model/AR
$gridid === 'questionthemes-grid'; // Should be $gridId with capital "I", since it's two words in English
$delete = Yii::app()->request->getParam('delete'); // Tuff one - $delete is ok? Thoughts?
$files = json_decode(stripslashes($sJSON), true); // $file is a resource, $files an array of resources, this is $fileData perhaps?
$valid_extensions_array = explode(",", $aAttributes['allowed_filetypes']); // Should be $validExtensionTypes
$language = Yii::app()->session['survey_' . $surveyid]['s_lang']; // TODO: Should this be a value class? Then Language::make(...);
$surveyInfo = getSurveyInfo($surveyId, $language); // OK, BUT should be a separate DTO!
$fieldMap = createFieldMap($survey, 'short', false, false, $language); // Same, make a DTO
$cquestions = array(); // What's "c"? Method name is getChildQuestions and $questions is an argument - better with $childQuestions?
</syntaxhighlight>

Links:

[https://www.approxion.com/capital-offenses-how-to-handle-abbreviations-in-camelcase/ How to Handle Abbreviations in CamelCase]

[https://stackoverflow.com/questions/15526107/acronyms-in-camelcase Acronyms in CamelCase]

=== Looping ===

* The bodies of foreach-loops are often a good candidate to factor out into separate functions.

'''Example:'''

<syntaxhighlight lang="php">
foreach ($questions as $question) {
processQuestion($question);
}
</syntaxhighlight>

Note the variable naming from plural to singular.

* Loop indexing should be named i, j, k etc.

'''Example:'''

<syntaxhighlight lang="php">
for ($i = 0; $i < $length; $i++) {
for ($j = 0; $j < $otherLength; $j++) {
// ...
}
}
</syntaxhighlight>

<hr>

=== Function composition ===

todo, "doThisAndThat" --> "doThis(doThat())"

=== Cases ===

<syntaxhighlight lang="php">
/**
* This function generates an array containing the fieldcode, and matching data in the same order as the activate script
*
* @param Survey $survey Survey ActiveRecord model
* @param string $style 'short' (default) or 'full' - full creates extra information like default values
* @param boolean $force_refresh - Forces to really refresh the array, not just take the session copy
* @param bool|int $questionid Limit to a certain qid only (for question preview) - default is false
* @param string $sLanguage The language to use
* @param array $aDuplicateQIDs
* @return array
*/
function createFieldMap($survey, $style = 'short', $force_refresh = false, $questionid = false, $sLanguage = '', &$aDuplicateQIDs = array())
</syntaxhighlight>

'''Good:'''

* Name is verb and noun
* Each argument is documented (almost)

'''Bad:'''

* Returns "array", which can be anything. A separate class for "Fieldmap" would be better.
* Not clear if it should be "createFieldMap" or "createFieldmap" - is "fieldmap" one word or two?
* Very many boolean arguments. Should probably be a class with methods like <code>$fieldmapCreator->setForceRefresh(true);</code> instead.
* Too long.
* Doesn't elaborate on what "fieldmap" really is, and does not link to any documentation about it.
* Access super-global, which makes it hard to test. Should instead return a data-transfer object, like:<br><syntaxhighlight lang="php">
$_SESSION['fieldmap'] = createFieldMap(...);
</syntaxhighlight>
* Has no test
* Mixes Hungarian notation with non-Hungarian notation in the argument list

== Defensive programming and error handling ==

todo

* '''Fail hard, fail early'''. The earlier the program crashes when something is wrong, the lower is the probability that you'll end up with corrupt data in the database that will later require manual labor to correct.
* Fail with '''actionable information'''
* Check input to functions and throw <code>InvalidArgumentException</code> if it violates the function's pre-conditions
* Use assert for class-internal invariants
* Use assert to make assumptions explicit for the reader

== Documentation ==

=== PHPDoc ===

* All functions must have a proper docblock
* The first line of the docblock should describe the relation between ''all'' the input arguments and the output of the function in a single sentence
* Each parameter must have the correct type
* Don't use <code>array</code> as type if it's a list of object - instead, use <code>[]</code> like so: <code>Survey[]</code> for a list of surveys

=== Technical documentation ===

todo, UML, scenarios, use-cases

== The PHP of yesterday ==

Old idioms and habits that should be abandoned.

* Don't use associative arrays, almost never. Data-transfer objects have multiple benefits: they are clearly structured, can be documented, can enforce invariants. There's ''no'' performance overhead of objects compared to arrays in modern PHP.
* Objects are already passed by reference; arrays are value types
* Use <code>[]</code> instead of <code>array()</code>
* Hungarian notation was useful before static analysis existed for PHP. These days it's better to use something that can be checked automatically: docblock @param and inline @var annotations.

== The PHP of tomorrow ==

todo

Union tags

Short functions

Match expressions

== Security ==

todo

XSS

Database injection

Permissions and roles

== Performance ==

todo

Loading too many rows into PHP models

== Testing ==

todo

QA

PHPUnit

TDD

Mocks, can't mock functions, static methods, mocking as a DSL, PHPUnit mocking tools

Pure functions, referential transparency, side-effects

Unit, functional, integration

Don't test the framework; don't test PHP

Makes sure the function or class lives up to its specification; make sure it will ''always'' live up to its specification, even in the future, to avoid regressions.

== Static analysis ==

<code>php -l</code>, CodeSniffer, Mess Detector, Psalm

== Database design ==

todo

== JavaScript ==

todo

classes, functions, components, tests

== CSS ==

todo

== HTML ==

todo

== Feedback ==

=== "Why do I have to refactor code that works?" ===

todo, Sadly, it's not enough for the code to live up to the current specification and requirements, it must also be protected against future changes, regressions. Adding tests is the best way for this. Lots of people might read and change the LimeSurvey code the next 5-10 years. The test suite creates a security layer to make sure the specification is fulfilled even as the code changes.

Tests are not a magical solution, however. It does not protect us against other degradation of the code quality, like classes gaining too much responsibility (too many methods, unrelated methods, too many properties).

=== "What's the correct ratio between integrity tests and unit tests?" ===

todo, Don't know. Different pros and cons.

* Unit-test can be run in parallel and are faster
* Unit-tests don't need setup and teardown

Cons of unit-tests is that they need a bigger effort on the side of the developer to make them possible, for example injecting the dependencies properly to enable mocking, or lifting side-effects up in the stack trace.

=== How to disagree ===

All rules can be broken. To break a rule, you should reason in terms of risk and the assumptions used in this guide.

'''Assumptions:'''

# Regressions are the biggest technical risk for LimeSurvey the last five years (2021)
# Automated tests are the best risk mitigation technique against regressions

'''Possible disagreement:'''

# A certain piece of code has very low ''probability'' of regressions (maybe we "know" no one else will every touch or change it?)
# Regression in a certain piece of code would have very low ''impact''

== Architectural Decision Records ==

todo

https://adr.github.io/

== Resources ==

todo

Books, links, videos

File:Coupling.png

2021-05-19T10:07:40Z

Olle:

Code quality guide

2021-05-19T10:07:29Z

Olle: /* Modular coupling */

DRAFT

== Prologue ==

# '''Be risk aware'''. Too good code can be a business risk (slow to write, maybe over-designed). Too sloppy code can also be a business risk (hard to maintain and understand). You have to find a balance that is adapted to the current situation and risk analysis, in which code quality becomes a '''risk mitigation''' technique among others.
# '''Be humble'''. LimeSurvey was made by developers from all over the world, with different age, education and experience. Your code might be read by a completely different team ten years from now, in the same way you are now reading code by developers that no longer work with us, but which work pays our rent.
# '''Performance matters sometimes''', and shouldn't be disregarded completely. In particular, database queries using the ORM and ActiveRecord can be problematic. Some surveys have thousands of questions and hundreds of thousands of responses. Fast response time is also important for a fluid user experience.
# '''It's harder to read code than to write code'''. Don't choose patterns that are easy or fast to write, but that are easy to read.
# Make your code '''communicate intent'''.
# It's easy to forget '''cross-cutting concerns''' like translation and security. Keep a mental note.
# '''Stress affects code quality''' and your risk behaviour. If your stress level is too high to write code with proper quality, take a step back and discuss it with your boss, or you'll push problems to the future.

== Quality ==

The purpose of this guide is to increase the quality of the LimeSurvey code-base. What is quality? Which aspects of quality can be measured? Which kind of company culture gives rise to appropriate code quality?

It's usually easier to get along what is "bad" code than what's "best" code. Blacklist instead of whitelist?

Quality attributes related to code quality:

* Readability
* Testability
* Maintainability
* Performance
* Security
* Reliability

Can not increase all at the same time - performance vs readability.

It's better to avoid emotional language when describing code quality, like "clean" or "dirty". Be precise, objective and suggest solutions.

Idiomatic code is more readable than non-idiomatic code. What's idiomatic depends on which context or domain you work in. We work in PHP and web application development, and have other idioms than in, say, functional or hardware-close programming.

Some code are "hot spots" - changed often. Those parts should require higher quality than other code.

== Risk ==

todo

Couple of different definition of risk:

* Tuple of probability and severity
* Triple of consequence, uncertainty and knowledge base

Possible risks related to LimeSurvey (technical or business):

* Data loss
* Regressions
* Bad UI (higher churn-rate for users)
* Hard to maintain (reduced sprint velocity)
*

How know which is the biggest risk? How many risks can be approached at once?

Connection to architecture. Risk --> quality attributes --> architectural decisions.

usability a business risk - hard to use or understand, people will choose another tool

risks relevant when fixing bugs

risks relevant when adding new features (lack of testing, wrong requirements, scope creep)

risks relevant when refactoring (regressions)

unit tests and QA as risk mitigation

partial deployment, alpha/beta/rc, risk communication

software rot, design pattern rot/grime, software evolution

rot = non-pattern related code

testing by community, bug fixing by community

== Modules ==

There's no inherit module functionality in PHP, but Yii has a module system. Libraries can be seen as a module system.

Examples of implicit modules in LimeSurvey:

* Front-end (survey taking)
* Back-end (survey design)
* Survey theme editing
* Expression manager
* Plugin system

In the future, they need to be separated and implemented more clearly as whatever Yii 3 module system is in use.

Some data models are common for all modules, e.g. surveys and users. Can have a "Common" module for such data.

todo, relation to Yii config system

== Classes ==

* Avoid empty OOP ceremony, like defining getters and setters for all properties. Might as well make them public, ''unless'' they have invariants that need to be upheld, e.g. "this number is always between 1 and 10" or "this string is maximum length 20".
* Almost always avoid static methods. They cannot be mocked. One exception is (possibly) factory methods (Foo::make(...)).
* Inject all dependencies. This will make sure the class can be unit-tested (unit-tests have several benefits over integrity tests - they can be run in parallel and don't require any setup and teardown)
* A second way to achieve testability is to factor out the methods that access the dependencies

todo, state vs behaviour, state vs dependencies

=== OOP design ===

Start from top-down, with domain, behaviour, interaction between objects, database design, pseudo-code if needed. Can also include scenarios, use-cases and UML diagrams.

Object reification - not only domain models, but also domain actions, relations and activities can be objects, e.g. a class ActivateSurvey or ExportSurvey.

Hierarchy depth should be kept reasonable shallow to avoid conflicts between methods, spooky action at a distance. Compare with Yii 3, where controllers no longer inherit anything.

Some people advocate for composition instead of inheritance. Lots of blog posts available for more info.

Multiple inheritance is done with traits in PHP. Use-case: ActiveRecords where some but not all models support encryption.

==== Shape design problem ====

Point (x, y), rectangle (bottomLeft, topRight), circle (point, radius (int))

Area, draw

* Cohesion: A class (or module) should be responsible for one thing only
* Coupling: You should be able to ''isolate change'' in the system
* Encapsulation: Classes shouldn’t share internal representation
* Polymorphism: The design should be based on interfaces

Questions to consider:

* How easy would it be to move to a 3D representation?
* How easy would it be to add a new shape, say, triangle?
* How easy would it be to add a new behaviour to all shapes, like save/load from a SQL database?
* Which classes ''change together''?

Keep polymorphism and encapsulation - all properties are private.

forall shapes as shape, do shape.draw(surface)

forall shapes as shape, do surface.draw(shape) (where shape.getDrawData(), or shape.getPath())

=== Software evolution ===

Design rot after time - how to keep it tight? (Grime.)

todo

==== Grime and rot ====

design pattern rot --> lose behaviour relevant for pattern (active record without db connection)

design patter grime --> add behaviour irrelevant for pattern (active record that's also a singleton)

==== Class cohesion ====

[[File:cohesion.png]]

==== Modular coupling ====

[[File:coupling.png]]

=== State ===

Heuristics to consider but not follow slavishly.

Keep a clear separation between classes with state and classes with no state.

Classes with state should not have dependencies with IO (it's OK to depend on classes in the same application layer, e.g. other DTO classes), and vice versa. ActiveRecord is an example which violates this principle.

class Survey
// Confusion - first params are domain state, last a resource
__construct(id, language, dbConnection)

If a method does not call "this", should it instead be outside the class? A separate class or function, maybe.

todo, elaborate

=== Types of classes ===

Different categories of classes:

* Entity (domain class; has state and validation behaviour)
* Resource (database connection, file, curl, logger; state is in the resource (open, closed))
* Repository classes (database interaction, like splitting ActiveRecord in two parts: Entity class and database interaction)
* DAO, data access object (similar to resource)
* Builders (e.g. query builder, HTML message builder)
* Data-transfer object (no behaviour; pass to views to have better documentation and intent than associative arrays)
* Value classes (e.g. Email address to wrap email string around)
* Command object (e.g. SurveyActivator)
* Helper (no state; e.g. QuestionAttributeHelper to bake attributes into different formats used by the views)
* Wrapper

todo, immutability, possible with private properties that are set in the constructor,

todo: command-query separation for classes?

todo: dependencies between layers, dependencies to the framework

todo, pure vs effectful classes

=== Types of classes in LimeSurvey ===

* ActiveRecord, used to communicate with the database, and should not do ''anything'' else
* Controllers, used for glue code; should not contain business-logic (also CLI controllers)
* Helper functions (not classes, yet...), should be short and obey command-query separation (TODO: Long functions should be separated into command objects or service classes); todo: should not have any dependencies?
* Helper classes, similar to helper functions but have dependencies that need to be mocked during tests; should not have any state
* Service classes, contains logic related to a clear and separate task, like create or import survey
* Question render classes, contains logic related to how questions are rendered (TODO: Need better separation between state and logic and more clear design); similar to widgets
* Plugin classes, using the plugin event system
* Widgets, containing HTML logic for custom HTML widgets
* HTML helpers (Yii)
* Customizations to the Yii framework by inheritance
* Unit and functional test classes

A couple of classes contain only data, like LsDefaultDataSet.

todo, no difference between state property and dependency property in OOP

=== What is "glue code"? ===

todo

Putting the pieces together, e.g. service class A need data from model B, fetch it and run.

todo, add example

=== "Where do I cut?" ===

Separation of concerns, but which concerns and which type of separation? Command-query (function core, imperative shell) is one type of separation. Other separation between layers, e.g. logic layer and data persistency layer (similar in thought).

Other separation, that one class should have a clear purpose. A design pattern should only implement ''one'' pattern, not multiple, and not half a pattern.

There's a problem with "helper" or "manager" classes that they can grow indefinitely, but might be better than nothing. Example when moving business logic out of ActiveRecord class to a helper class it can sometimes hard to be more specific than "helper".

=== Size ===

A class should have a single and clear purpose; compare with [https://en.wikipedia.org/wiki/SOLID SOLID].

=== Class name ===

* ActiveRecord classes are named after the database table they are bound to, but with singular instead of plural. E.g. table "lime_users" have model "User".
* Command classes are named after what they ''do'' and imperatively, e.g. CreateSurvey
* Helper classes should probably be named as specific as possible when possible, to avoid them from growing too big
* Follow the naming tradition of the framework with regard to controllers, e.g. UserController or UserAdministrationController.
* Class properties of ActiveRecord classes will follow the naming of the database, using underscore instead of camel case (and ActiveRecord classes should have ''no'' other properties than those (excluding the database connection injected by the framework))

== Functions ==

Functions are one of the fundamental building blocks of programming, so it's important to get it right.

Functions that are part of a class are called "methods", if you want to be formal.

Different types of functions in PHP:

* Functions (not attached to a class)
* Methods (attached to class)
* Anonymous functions (does not capture scope automatically)
* Short functions (does capture scope automatically)

I'm using "function" as a word for all types of functions in PHP below.

<hr>

=== Size ===

* A function should be short enough to be completely readable on one screen, approx 60 lines at most
* A function should not have too many arguments; if you have five or more, consider making it a class instead
* If a function is growing too big, it might be better to create a class instead or split it into several functions (if both functions have '''common state''', a class might be better, unless you want to pass around '''explicit state''')

=== Contract ===

* A function has a contract with its surrounding environment:
** Pre-condition: What needs to be true before the function is executed
** Post-condition: What will be true after the function has returned
* The function contract can be checked with assertions (internal invariants) or exceptions (outside world); see below
* Another good way is to use unit-tests to make sure the function's contract remains stable through changes
* The first line in the docblock should be one sentence describing the relation between function arguments and its output<br>Example<br><syntaxhighlight lang="php">
/**
* Creates a random password of length $length (defaults to 12)
* @param int $length
* @return string
*/
function createPassword($lenght = 12)

/**
* Creates an HTML language drop down for survey with id $surveyId, marking $selectedLanguage as selected
* @param int $surveyId
* @param string $selectedLanguage
* @return string <select> HTML
*/
function createLanguageDropdown($surveyId, $selectedLanguage)

</syntaxhighlight>

=== Push side-effects up in the stack trace ===

This one is a bit abstract.

First, what is a '''side-effect'''? In short, it's anything that happens in a function that ''is not'' described by the ''relation'' between function arguments and output.

Another way to phrase it is, that a side-effect is anything that is not always the same for the given input to a function; a function without any side-effects will always return the same result if it gets the same input.

'''Examples:'''

<syntaxhighlight lang="php">
// gT accesses the file system and will return different result depending on what's in the translation files
function gT($sToTranslate, $sEscapeMode = 'html', $sLanguage = null);

// If $sText and $sEscapeMode is always the same, quoteText() will always return the same string.
function quoteText($sText, $sEscapeMode = 'html');
</syntaxhighlight>

A function with no side-effects is called '''pure'''. A function that is guaranteed to always return (no exceptions, no errors, no warnings, no division by zero) is called '''total'''.

It's a good thing if functions in a code-base ''either'' have side-effects, ''or'' return a result. Not both. This is called [https://en.wikipedia.org/wiki/Command%E2%80%93query_separation command-query separation].

Examples of side-effects:

* Database or file access
* Echo, or write to stdout or stderr
* Randomization

Why does this matter? Because side-effects make testing harder! '''If you have side-effects, you cannot create unit tests''', ''unless'' those side-effects can be mocked. If not, you need integrity tests with database setup or more. The more side-effects you have in a function, the more mocking is required to unit test it.

So, one solution to this is to move side-effects higher up in the stack trace, that is, move them to the calling code.

'''Example:'''

<syntaxhighlight lang="php">
function getSurveyInfo(int $surveyid, string $languagecode = '', boolean $force = false): array;
</syntaxhighlight>

Since this function takes $surveyid, we know it will probably query the database. Quering the database is a side-effect, and thus it requires a database scaffold for the test (or mocking, but the database connection is not injected, so there's no way to do it). One simple solution is to lift the side-effect out and pass in a Survey object instead:

<syntaxhighlight lang="php">
function getSurveyInfo(Survey $survey, string $languagecode = '', boolean $force = false): array;
</syntaxhighlight>

Much better! The side-effect of calling the database now happens ''before'' the function call. Now we can either mock a Survey object, or make an imitating stub for our test.

Reading the function body, there is in fact another database access, but since this is a relation to the Survey model, it could easily be moved out too. We've just made a function testable! Hooray!

This principle is rephrased in an architectural settings as [https://github.com/kbilsted/Functional-core-imperative-shell/blob/master/README.md functional core, imperative shell]. This architecture helps you get a good ratio between fast unit tests and slower integrity tests.

Moving side-effects up makes sure we can have a healthy ratio between integrity tests with scripted browser, and unit-tests; maybe around 20-80.

=== Function name ===

* The function name should tell you '''what''' it does; docs should tell you '''why''' (if this information is not obvious). '''How''' is described by the code itself (hopefully, but can in some cases be relevant to document).
* Function name can often be '''verb [+ adjective] + noun''', like "createFieldmap", "quoteText", "getRelativePath"
* Prefix with "is" for boolean functions

todo: difference between create, get, fetch, generate, ...

'''Good examples:'''

* createPassword() - One verb, one noun - clear
* isCaptchaEnabled() - Using "is" signifies it returns boolean; clear purpose
* getFullResponseTable() - Verb, adjective, noun - but is "full" needed here? Is there a non-full version of the same function?
* replaceExpressionCodes() - Pretty good, but it's obvious that more information is needed in the docblock to describe what "replace" means, and what an "expression code" is
* fixCKeditorText() - "fix" is a bit vague, but maybe best there is? Pray that docblock contains information!

'''Bad examples:'''

* languageDropdown() - No verb, doesn't tell you what it does
* rmdirr() - Two r's, looks like a typo, but the last "r" actually means "recursive"! Better: rmdir($recursive = false), rmdir or removeFolder.
* CSVUnquote() - Is CSV really the namespace? Why is the verb the second word?
* incompleteAnsFilterState() - One verb, but in the middle, or is "filter state" a noun?; why abbreviate "answer" to "ans"?
* reverseTranslateFieldNames() - Two verbs - did author mean "reverseTranslatedFieldNames"? Or "reverse and translate"? If so, it should be two functions, one for reverse and one for translate
* checkUploadedFileSizeAndRenderJson() - If you have an "and" in the function name, you should consider splitting it into two functions

'''Controversial'''

* gT() - An exception to descriptive function names; since this is used everywhere, the minimal name is motivated; maybe even name it "t()"? Still hard to read for someone who just started? But Yii uses t() too? Other frameworks use double underscore (Wordpress, Laravel) as function name.

<hr>

=== Function filename and namespace ===

If your function has dependencies or side-effects, it should be put into a class instead, in which the dependencies can be injected. Another alternative is to put the dependencies as argument in the function, although this muffles the relationship between input and output. Again, this is to increase testability.

Keep in mind that functions outside classes cannot be mocked, so only use them when you ''know'' you won't need to mock them.

todo, autoloading of functions and folder location

=== Assertions ===

NB: This is not assertions as used in unit-tests, but assertions as used to check invariants in production code.

Assertions can be used for mental checks. They are only used for internal logic - failed assertions are not supposed to be seen by the end user. For interaction with the outside world, like database or browser, exceptions should be used instead.

Assertions can be disabled in production mode and have then no runtime cost (since PHP 7).

'''Example:'''

<syntaxhighlight lang="php">
/**
* Translation helper function
*
* @param string $sToTranslate
* @param string $sEscapeMode Valid values are html (this is the default, js and unescaped)
* @param string $sLanguage
* @return string
*/
function gT($sToTranslate, $sEscapeMode = 'html', $sLanguage = null)
{
assert(is_string($sToTranslate));
assert(strlen($sToTranslate) > 0);
assert($sEscapeMode === 'html' || $sEscapeMode === 'js' || $sEscapeMode === 'unescaped');
return quoteText(Yii::t('', $sToTranslate, array(), null, $sLanguage), $sEscapeMode);
}
</syntaxhighlight>

<hr>

=== Exceptions ===

todo

todo: exception hierarchy

todo: what can be repaired after exception? transaction rollback

* Exceptions are used to check inputs from the outside world (browser, database, file system)
* Don't use exceptions for control flow, only when fatal errors happen that make further execution impossible
* Exceptions should have clear error messages that make them ''actionable'' - there should be a clear "next step" for the user or developer
* Never, ever, do an empty catch-block

==== Alternatives to exceptions ====

Some people consider exceptions being a hidden form of "goto" which confuses the control flow of the program. They propose different other solutions:

* Return a tuple, like <code>[$result, $errorMessage]</code> where $errorMessage is null at success
* Return <code>null</code> at failure
* Tagged union result type (not yet possible in latest PHP)
* Result object

The con being that you have to manually propagate the error, where an exception can happen from anywhere in the stack trace without any other function knowing about it.

=== If-statements ===

If-statements should not be too long or hard to understand. If they are, consider factor out the checks into separate functions.

<syntaxhighlight lang="php">
if ((empty($instance->oOptions->{$attribute}))
|| (
!empty($instance->oOptions->{$attribute})
&& (
$instance->oOptions->{$attribute} === 'inherit'
|| $instance->oOptions->{$attribute} === 'I'
// NB: Do NOT use === here, it won't work with Postgresql.
|| $instance->oOptions->{$attribute} == '-1'
)
)
) {
</syntaxhighlight>

Can be shortened by factoring out method <code>isInherit</code>:

<syntaxhighlight lang="php">
if (empty($instance->options->{$attribute})
|| $this->isInherit($instance-options->{$attribute})) {
}
/**
* Returns true if $value is set to inherit
* @param mixed|null $value
* @return boolean
*/
public function isInherit($value) {
return !empty($value)
&& (
$value === 'inherit'
|| $value === 'I'
// NB: Do NOT use === here, it won't work with Postgresql.
|| $value == '-1'
);
}
</syntaxhighlight>

And one more time by using a variable for the value:

<syntaxhighlight lang="php">
$value = $instance->options->{$attribute};
if (empty($value) || $this->isInherit($value)) {
}
</syntaxhighlight>

More clear, right? "If it's empty or set to inherit, do this and that."

=== Variables ===

Descriptive naming.

* Follow PSR-12 - no underscore, use camelCaseLikeThis
* Variables of ActiveRecord classes can have same name as the class, like "$survey" or "$question"
* Add -s for plural when it's a list of items: "$surveys", "$questions"
* Never include "array" or "list" in variable names - using plural is enough (for lists, not for associative arrays - see below)
* The ''context'' of the function helps with variable naming, e..g "$name" might be fine in a function about questions; this is extra helpful when functions are short!
* When a function is short, it's much easier to figure out variable meaning based on context
* $qid, $gid, and $sid are so established in the code-base that they could be considered OK
* The -data suffix means "blob of stuff", only use it when needed, like with $viewData
* Use $result when baking a return value; add its exact type as @var annotation (worst possible name, acceptable but anything with more meaning is better)

Not so good:

<syntaxhighlight lang="php">
$result = LabelSet::model()->findAll();
</syntaxhighlight>

Better with model name and -s for plural:

<syntaxhighlight lang="php">
$labelSets = LabelSet::model()->findAll();
</syntaxhighlight>

* Do not use Hungarian notation (prefix with "type"), but instead <code>/** @var */</code> annotations - these can be checked automatically and will then be enforced to be correct, unlike Hungarian notation which can "rot"

<syntaxhighlight lang="php">
/** string[] An array of strings with 0-n elements */
$allFields = [];
</syntaxhighlight>

Psalm can infer types if the function documentation is enough. The strictness can be adjusted. Not all variables will need @var annotation, the tool will warn you when it's confused.

* Data that is sent to views as associative arrays will be:

<syntaxhighlight lang="php">
/** @var array Can be basically anything :( Better would be data-transfer objects or more precise notation */
$data = [];
// Maybe more clear as $viewData? Discuss.
</syntaxhighlight>

You can be more precise when you specify which type of array you're writing:

<syntaxhighlight lang="php">
/** @var array<string, string> This means the array key is string, and the array value is also string */
$data = [];
$data['name'] = 'Olle';
$data['occupation'] = 'Developer';
$data['age'] = 38; // ERROR! Value must be string.
</syntaxhighlight>

For more info about array type notation, see the [https://psalm.dev/docs/annotating_code/type_syntax/array_types/ Psalm documentation].

Some smaller examples:

<syntaxhighlight lang="php">
$theme = App()->request->getPost('theme'); // Should be $themeType - $theme looks like a model/AR
$gridid === 'questionthemes-grid'; // Should be $gridId with capital "I", since it's two words in English
$delete = Yii::app()->request->getParam('delete'); // Tuff one - $delete is ok? Thoughts?
$files = json_decode(stripslashes($sJSON), true); // $file is a resource, $files an array of resources, this is $fileData perhaps?
$valid_extensions_array = explode(",", $aAttributes['allowed_filetypes']); // Should be $validExtensionTypes
$language = Yii::app()->session['survey_' . $surveyid]['s_lang']; // TODO: Should this be a value class? Then Language::make(...);
$surveyInfo = getSurveyInfo($surveyId, $language); // OK, BUT should be a separate DTO!
$fieldMap = createFieldMap($survey, 'short', false, false, $language); // Same, make a DTO
$cquestions = array(); // What's "c"? Method name is getChildQuestions and $questions is an argument - better with $childQuestions?
</syntaxhighlight>

Links:

[https://www.approxion.com/capital-offenses-how-to-handle-abbreviations-in-camelcase/ How to Handle Abbreviations in CamelCase]

[https://stackoverflow.com/questions/15526107/acronyms-in-camelcase Acronyms in CamelCase]

=== Looping ===

* The bodies of foreach-loops are often a good candidate to factor out into separate functions.

'''Example:'''

<syntaxhighlight lang="php">
foreach ($questions as $question) {
processQuestion($question);
}
</syntaxhighlight>

Note the variable naming from plural to singular.

* Loop indexing should be named i, j, k etc.

'''Example:'''

<syntaxhighlight lang="php">
for ($i = 0; $i < $length; $i++) {
for ($j = 0; $j < $otherLength; $j++) {
// ...
}
}
</syntaxhighlight>

<hr>

=== Function composition ===

todo, "doThisAndThat" --> "doThis(doThat())"

=== Cases ===

<syntaxhighlight lang="php">
/**
* This function generates an array containing the fieldcode, and matching data in the same order as the activate script
*
* @param Survey $survey Survey ActiveRecord model
* @param string $style 'short' (default) or 'full' - full creates extra information like default values
* @param boolean $force_refresh - Forces to really refresh the array, not just take the session copy
* @param bool|int $questionid Limit to a certain qid only (for question preview) - default is false
* @param string $sLanguage The language to use
* @param array $aDuplicateQIDs
* @return array
*/
function createFieldMap($survey, $style = 'short', $force_refresh = false, $questionid = false, $sLanguage = '', &$aDuplicateQIDs = array())
</syntaxhighlight>

'''Good:'''

* Name is verb and noun
* Each argument is documented (almost)

'''Bad:'''

* Returns "array", which can be anything. A separate class for "Fieldmap" would be better.
* Not clear if it should be "createFieldMap" or "createFieldmap" - is "fieldmap" one word or two?
* Very many boolean arguments. Should probably be a class with methods like <code>$fieldmapCreator->setForceRefresh(true);</code> instead.
* Too long.
* Doesn't elaborate on what "fieldmap" really is, and does not link to any documentation about it.
* Access super-global, which makes it hard to test. Should instead return a data-transfer object, like:<br><syntaxhighlight lang="php">
$_SESSION['fieldmap'] = createFieldMap(...);
</syntaxhighlight>
* Has no test
* Mixes Hungarian notation with non-Hungarian notation in the argument list

== Defensive programming and error handling ==

todo

* '''Fail hard, fail early'''. The earlier the program crashes when something is wrong, the lower is the probability that you'll end up with corrupt data in the database that will later require manual labor to correct.
* Fail with '''actionable information'''
* Check input to functions and throw <code>InvalidArgumentException</code> if it violates the function's pre-conditions
* Use assert for class-internal invariants
* Use assert to make assumptions explicit for the reader

== Documentation ==

=== PHPDoc ===

* All functions must have a proper docblock
* The first line of the docblock should describe the relation between ''all'' the input arguments and the output of the function in a single sentence
* Each parameter must have the correct type
* Don't use <code>array</code> as type if it's a list of object - instead, use <code>[]</code> like so: <code>Survey[]</code> for a list of surveys

=== Technical documentation ===

todo, UML, scenarios, use-cases

== The PHP of yesterday ==

Old idioms and habits that should be abandoned.

* Don't use associative arrays, almost never. Data-transfer objects have multiple benefits: they are clearly structured, can be documented, can enforce invariants. There's ''no'' performance overhead of objects compared to arrays in modern PHP.
* Objects are already passed by reference; arrays are value types
* Use <code>[]</code> instead of <code>array()</code>
* Hungarian notation was useful before static analysis existed for PHP. These days it's better to use something that can be checked automatically: docblock @param and inline @var annotations.

== The PHP of tomorrow ==

todo

Union tags

Short functions

Match expressions

== Security ==

todo

XSS

Database injection

Permissions and roles

== Performance ==

todo

Loading too many rows into PHP models

== Testing ==

todo

QA

PHPUnit

TDD

Mocks, can't mock functions, static methods, mocking as a DSL, PHPUnit mocking tools

Pure functions, referential transparency, side-effects

Unit, functional, integration

Don't test the framework; don't test PHP

Makes sure the function or class lives up to its specification; make sure it will ''always'' live up to its specification, even in the future, to avoid regressions.

== Static analysis ==

<code>php -l</code>, CodeSniffer, Mess Detector, Psalm

== Database design ==

todo

== JavaScript ==

todo

classes, functions, components, tests

== CSS ==

todo

== HTML ==

todo

== Feedback ==

=== "Why do I have to refactor code that works?" ===

todo, Sadly, it's not enough for the code to live up to the current specification and requirements, it must also be protected against future changes, regressions. Adding tests is the best way for this. Lots of people might read and change the LimeSurvey code the next 5-10 years. The test suite creates a security layer to make sure the specification is fulfilled even as the code changes.

Tests are not a magical solution, however. It does not protect us against other degradation of the code quality, like classes gaining too much responsibility (too many methods, unrelated methods, too many properties).

=== "What's the correct ratio between integrity tests and unit tests?" ===

todo, Don't know. Different pros and cons.

* Unit-test can be run in parallel and are faster
* Unit-tests don't need setup and teardown

Cons of unit-tests is that they need a bigger effort on the side of the developer to make them possible, for example injecting the dependencies properly to enable mocking, or lifting side-effects up in the stack trace.

=== How to disagree ===

All rules can be broken. To break a rule, you should reason in terms of risk and the assumptions used in this guide.

'''Assumptions:'''

# Regressions are the biggest technical risk for LimeSurvey the last five years (2021)
# Automated tests are the best risk mitigation technique against regressions

'''Possible disagreement:'''

# A certain piece of code has very low ''probability'' of regressions (maybe we "know" no one else will every touch or change it?)
# Regression in a certain piece of code would have very low ''impact''

== Architectural Decision Records ==

todo

https://adr.github.io/

== Resources ==

todo

Books, links, videos

File:Cohesion.png

2021-05-19T10:05:24Z

Olle:

Code quality guide

2021-05-19T10:05:14Z

Olle: /* Class cohesion */

DRAFT

== Prologue ==

# '''Be risk aware'''. Too good code can be a business risk (slow to write, maybe over-designed). Too sloppy code can also be a business risk (hard to maintain and understand). You have to find a balance that is adapted to the current situation and risk analysis, in which code quality becomes a '''risk mitigation''' technique among others.
# '''Be humble'''. LimeSurvey was made by developers from all over the world, with different age, education and experience. Your code might be read by a completely different team ten years from now, in the same way you are now reading code by developers that no longer work with us, but which work pays our rent.
# '''Performance matters sometimes''', and shouldn't be disregarded completely. In particular, database queries using the ORM and ActiveRecord can be problematic. Some surveys have thousands of questions and hundreds of thousands of responses. Fast response time is also important for a fluid user experience.
# '''It's harder to read code than to write code'''. Don't choose patterns that are easy or fast to write, but that are easy to read.
# Make your code '''communicate intent'''.
# It's easy to forget '''cross-cutting concerns''' like translation and security. Keep a mental note.
# '''Stress affects code quality''' and your risk behaviour. If your stress level is too high to write code with proper quality, take a step back and discuss it with your boss, or you'll push problems to the future.

== Quality ==

The purpose of this guide is to increase the quality of the LimeSurvey code-base. What is quality? Which aspects of quality can be measured? Which kind of company culture gives rise to appropriate code quality?

It's usually easier to get along what is "bad" code than what's "best" code. Blacklist instead of whitelist?

Quality attributes related to code quality:

* Readability
* Testability
* Maintainability
* Performance
* Security
* Reliability

Can not increase all at the same time - performance vs readability.

It's better to avoid emotional language when describing code quality, like "clean" or "dirty". Be precise, objective and suggest solutions.

Idiomatic code is more readable than non-idiomatic code. What's idiomatic depends on which context or domain you work in. We work in PHP and web application development, and have other idioms than in, say, functional or hardware-close programming.

Some code are "hot spots" - changed often. Those parts should require higher quality than other code.

== Risk ==

todo

Couple of different definition of risk:

* Tuple of probability and severity
* Triple of consequence, uncertainty and knowledge base

Possible risks related to LimeSurvey (technical or business):

* Data loss
* Regressions
* Bad UI (higher churn-rate for users)
* Hard to maintain (reduced sprint velocity)
*

How know which is the biggest risk? How many risks can be approached at once?

Connection to architecture. Risk --> quality attributes --> architectural decisions.

usability a business risk - hard to use or understand, people will choose another tool

risks relevant when fixing bugs

risks relevant when adding new features (lack of testing, wrong requirements, scope creep)

risks relevant when refactoring (regressions)

unit tests and QA as risk mitigation

partial deployment, alpha/beta/rc, risk communication

software rot, design pattern rot/grime, software evolution

rot = non-pattern related code

testing by community, bug fixing by community

== Modules ==

There's no inherit module functionality in PHP, but Yii has a module system. Libraries can be seen as a module system.

Examples of implicit modules in LimeSurvey:

* Front-end (survey taking)
* Back-end (survey design)
* Survey theme editing
* Expression manager
* Plugin system

In the future, they need to be separated and implemented more clearly as whatever Yii 3 module system is in use.

Some data models are common for all modules, e.g. surveys and users. Can have a "Common" module for such data.

todo, relation to Yii config system

== Classes ==

* Avoid empty OOP ceremony, like defining getters and setters for all properties. Might as well make them public, ''unless'' they have invariants that need to be upheld, e.g. "this number is always between 1 and 10" or "this string is maximum length 20".
* Almost always avoid static methods. They cannot be mocked. One exception is (possibly) factory methods (Foo::make(...)).
* Inject all dependencies. This will make sure the class can be unit-tested (unit-tests have several benefits over integrity tests - they can be run in parallel and don't require any setup and teardown)
* A second way to achieve testability is to factor out the methods that access the dependencies

todo, state vs behaviour, state vs dependencies

=== OOP design ===

Start from top-down, with domain, behaviour, interaction between objects, database design, pseudo-code if needed. Can also include scenarios, use-cases and UML diagrams.

Object reification - not only domain models, but also domain actions, relations and activities can be objects, e.g. a class ActivateSurvey or ExportSurvey.

Hierarchy depth should be kept reasonable shallow to avoid conflicts between methods, spooky action at a distance. Compare with Yii 3, where controllers no longer inherit anything.

Some people advocate for composition instead of inheritance. Lots of blog posts available for more info.

Multiple inheritance is done with traits in PHP. Use-case: ActiveRecords where some but not all models support encryption.

==== Shape design problem ====

Point (x, y), rectangle (bottomLeft, topRight), circle (point, radius (int))

Area, draw

* Cohesion: A class (or module) should be responsible for one thing only
* Coupling: You should be able to ''isolate change'' in the system
* Encapsulation: Classes shouldn’t share internal representation
* Polymorphism: The design should be based on interfaces

Questions to consider:

* How easy would it be to move to a 3D representation?
* How easy would it be to add a new shape, say, triangle?
* How easy would it be to add a new behaviour to all shapes, like save/load from a SQL database?
* Which classes ''change together''?

Keep polymorphism and encapsulation - all properties are private.

forall shapes as shape, do shape.draw(surface)

forall shapes as shape, do surface.draw(shape) (where shape.getDrawData(), or shape.getPath())

=== Software evolution ===

Design rot after time - how to keep it tight? (Grime.)

todo

==== Grime and rot ====

design pattern rot --> lose behaviour relevant for pattern (active record without db connection)

design patter grime --> add behaviour irrelevant for pattern (active record that's also a singleton)

==== Class cohesion ====

[[File:cohesion.png]]

==== Modular coupling ====

todo

=== State ===

Heuristics to consider but not follow slavishly.

Keep a clear separation between classes with state and classes with no state.

Classes with state should not have dependencies with IO (it's OK to depend on classes in the same application layer, e.g. other DTO classes), and vice versa. ActiveRecord is an example which violates this principle.

class Survey
// Confusion - first params are domain state, last a resource
__construct(id, language, dbConnection)

If a method does not call "this", should it instead be outside the class? A separate class or function, maybe.

todo, elaborate

=== Types of classes ===

Different categories of classes:

* Entity (domain class; has state and validation behaviour)
* Resource (database connection, file, curl, logger; state is in the resource (open, closed))
* Repository classes (database interaction, like splitting ActiveRecord in two parts: Entity class and database interaction)
* DAO, data access object (similar to resource)
* Builders (e.g. query builder, HTML message builder)
* Data-transfer object (no behaviour; pass to views to have better documentation and intent than associative arrays)
* Value classes (e.g. Email address to wrap email string around)
* Command object (e.g. SurveyActivator)
* Helper (no state; e.g. QuestionAttributeHelper to bake attributes into different formats used by the views)
* Wrapper

todo, immutability, possible with private properties that are set in the constructor,

todo: command-query separation for classes?

todo: dependencies between layers, dependencies to the framework

todo, pure vs effectful classes

=== Types of classes in LimeSurvey ===

* ActiveRecord, used to communicate with the database, and should not do ''anything'' else
* Controllers, used for glue code; should not contain business-logic (also CLI controllers)
* Helper functions (not classes, yet...), should be short and obey command-query separation (TODO: Long functions should be separated into command objects or service classes); todo: should not have any dependencies?
* Helper classes, similar to helper functions but have dependencies that need to be mocked during tests; should not have any state
* Service classes, contains logic related to a clear and separate task, like create or import survey
* Question render classes, contains logic related to how questions are rendered (TODO: Need better separation between state and logic and more clear design); similar to widgets
* Plugin classes, using the plugin event system
* Widgets, containing HTML logic for custom HTML widgets
* HTML helpers (Yii)
* Customizations to the Yii framework by inheritance
* Unit and functional test classes

A couple of classes contain only data, like LsDefaultDataSet.

todo, no difference between state property and dependency property in OOP

=== What is "glue code"? ===

todo

Putting the pieces together, e.g. service class A need data from model B, fetch it and run.

todo, add example

=== "Where do I cut?" ===

Separation of concerns, but which concerns and which type of separation? Command-query (function core, imperative shell) is one type of separation. Other separation between layers, e.g. logic layer and data persistency layer (similar in thought).

Other separation, that one class should have a clear purpose. A design pattern should only implement ''one'' pattern, not multiple, and not half a pattern.

There's a problem with "helper" or "manager" classes that they can grow indefinitely, but might be better than nothing. Example when moving business logic out of ActiveRecord class to a helper class it can sometimes hard to be more specific than "helper".

=== Size ===

A class should have a single and clear purpose; compare with [https://en.wikipedia.org/wiki/SOLID SOLID].

=== Class name ===

* ActiveRecord classes are named after the database table they are bound to, but with singular instead of plural. E.g. table "lime_users" have model "User".
* Command classes are named after what they ''do'' and imperatively, e.g. CreateSurvey
* Helper classes should probably be named as specific as possible when possible, to avoid them from growing too big
* Follow the naming tradition of the framework with regard to controllers, e.g. UserController or UserAdministrationController.
* Class properties of ActiveRecord classes will follow the naming of the database, using underscore instead of camel case (and ActiveRecord classes should have ''no'' other properties than those (excluding the database connection injected by the framework))

== Functions ==

Functions are one of the fundamental building blocks of programming, so it's important to get it right.

Functions that are part of a class are called "methods", if you want to be formal.

Different types of functions in PHP:

* Functions (not attached to a class)
* Methods (attached to class)
* Anonymous functions (does not capture scope automatically)
* Short functions (does capture scope automatically)

I'm using "function" as a word for all types of functions in PHP below.

<hr>

=== Size ===

* A function should be short enough to be completely readable on one screen, approx 60 lines at most
* A function should not have too many arguments; if you have five or more, consider making it a class instead
* If a function is growing too big, it might be better to create a class instead or split it into several functions (if both functions have '''common state''', a class might be better, unless you want to pass around '''explicit state''')

=== Contract ===

* A function has a contract with its surrounding environment:
** Pre-condition: What needs to be true before the function is executed
** Post-condition: What will be true after the function has returned
* The function contract can be checked with assertions (internal invariants) or exceptions (outside world); see below
* Another good way is to use unit-tests to make sure the function's contract remains stable through changes
* The first line in the docblock should be one sentence describing the relation between function arguments and its output<br>Example<br><syntaxhighlight lang="php">
/**
* Creates a random password of length $length (defaults to 12)
* @param int $length
* @return string
*/
function createPassword($lenght = 12)

/**
* Creates an HTML language drop down for survey with id $surveyId, marking $selectedLanguage as selected
* @param int $surveyId
* @param string $selectedLanguage
* @return string <select> HTML
*/
function createLanguageDropdown($surveyId, $selectedLanguage)

</syntaxhighlight>

=== Push side-effects up in the stack trace ===

This one is a bit abstract.

First, what is a '''side-effect'''? In short, it's anything that happens in a function that ''is not'' described by the ''relation'' between function arguments and output.

Another way to phrase it is, that a side-effect is anything that is not always the same for the given input to a function; a function without any side-effects will always return the same result if it gets the same input.

'''Examples:'''

<syntaxhighlight lang="php">
// gT accesses the file system and will return different result depending on what's in the translation files
function gT($sToTranslate, $sEscapeMode = 'html', $sLanguage = null);

// If $sText and $sEscapeMode is always the same, quoteText() will always return the same string.
function quoteText($sText, $sEscapeMode = 'html');
</syntaxhighlight>

A function with no side-effects is called '''pure'''. A function that is guaranteed to always return (no exceptions, no errors, no warnings, no division by zero) is called '''total'''.

It's a good thing if functions in a code-base ''either'' have side-effects, ''or'' return a result. Not both. This is called [https://en.wikipedia.org/wiki/Command%E2%80%93query_separation command-query separation].

Examples of side-effects:

* Database or file access
* Echo, or write to stdout or stderr
* Randomization

Why does this matter? Because side-effects make testing harder! '''If you have side-effects, you cannot create unit tests''', ''unless'' those side-effects can be mocked. If not, you need integrity tests with database setup or more. The more side-effects you have in a function, the more mocking is required to unit test it.

So, one solution to this is to move side-effects higher up in the stack trace, that is, move them to the calling code.

'''Example:'''

<syntaxhighlight lang="php">
function getSurveyInfo(int $surveyid, string $languagecode = '', boolean $force = false): array;
</syntaxhighlight>

Since this function takes $surveyid, we know it will probably query the database. Quering the database is a side-effect, and thus it requires a database scaffold for the test (or mocking, but the database connection is not injected, so there's no way to do it). One simple solution is to lift the side-effect out and pass in a Survey object instead:

<syntaxhighlight lang="php">
function getSurveyInfo(Survey $survey, string $languagecode = '', boolean $force = false): array;
</syntaxhighlight>

Much better! The side-effect of calling the database now happens ''before'' the function call. Now we can either mock a Survey object, or make an imitating stub for our test.

Reading the function body, there is in fact another database access, but since this is a relation to the Survey model, it could easily be moved out too. We've just made a function testable! Hooray!

This principle is rephrased in an architectural settings as [https://github.com/kbilsted/Functional-core-imperative-shell/blob/master/README.md functional core, imperative shell]. This architecture helps you get a good ratio between fast unit tests and slower integrity tests.

Moving side-effects up makes sure we can have a healthy ratio between integrity tests with scripted browser, and unit-tests; maybe around 20-80.

=== Function name ===

* The function name should tell you '''what''' it does; docs should tell you '''why''' (if this information is not obvious). '''How''' is described by the code itself (hopefully, but can in some cases be relevant to document).
* Function name can often be '''verb [+ adjective] + noun''', like "createFieldmap", "quoteText", "getRelativePath"
* Prefix with "is" for boolean functions

todo: difference between create, get, fetch, generate, ...

'''Good examples:'''

* createPassword() - One verb, one noun - clear
* isCaptchaEnabled() - Using "is" signifies it returns boolean; clear purpose
* getFullResponseTable() - Verb, adjective, noun - but is "full" needed here? Is there a non-full version of the same function?
* replaceExpressionCodes() - Pretty good, but it's obvious that more information is needed in the docblock to describe what "replace" means, and what an "expression code" is
* fixCKeditorText() - "fix" is a bit vague, but maybe best there is? Pray that docblock contains information!

'''Bad examples:'''

* languageDropdown() - No verb, doesn't tell you what it does
* rmdirr() - Two r's, looks like a typo, but the last "r" actually means "recursive"! Better: rmdir($recursive = false), rmdir or removeFolder.
* CSVUnquote() - Is CSV really the namespace? Why is the verb the second word?
* incompleteAnsFilterState() - One verb, but in the middle, or is "filter state" a noun?; why abbreviate "answer" to "ans"?
* reverseTranslateFieldNames() - Two verbs - did author mean "reverseTranslatedFieldNames"? Or "reverse and translate"? If so, it should be two functions, one for reverse and one for translate
* checkUploadedFileSizeAndRenderJson() - If you have an "and" in the function name, you should consider splitting it into two functions

'''Controversial'''

* gT() - An exception to descriptive function names; since this is used everywhere, the minimal name is motivated; maybe even name it "t()"? Still hard to read for someone who just started? But Yii uses t() too? Other frameworks use double underscore (Wordpress, Laravel) as function name.

<hr>

=== Function filename and namespace ===

If your function has dependencies or side-effects, it should be put into a class instead, in which the dependencies can be injected. Another alternative is to put the dependencies as argument in the function, although this muffles the relationship between input and output. Again, this is to increase testability.

Keep in mind that functions outside classes cannot be mocked, so only use them when you ''know'' you won't need to mock them.

todo, autoloading of functions and folder location

=== Assertions ===

NB: This is not assertions as used in unit-tests, but assertions as used to check invariants in production code.

Assertions can be used for mental checks. They are only used for internal logic - failed assertions are not supposed to be seen by the end user. For interaction with the outside world, like database or browser, exceptions should be used instead.

Assertions can be disabled in production mode and have then no runtime cost (since PHP 7).

'''Example:'''

<syntaxhighlight lang="php">
/**
* Translation helper function
*
* @param string $sToTranslate
* @param string $sEscapeMode Valid values are html (this is the default, js and unescaped)
* @param string $sLanguage
* @return string
*/
function gT($sToTranslate, $sEscapeMode = 'html', $sLanguage = null)
{
assert(is_string($sToTranslate));
assert(strlen($sToTranslate) > 0);
assert($sEscapeMode === 'html' || $sEscapeMode === 'js' || $sEscapeMode === 'unescaped');
return quoteText(Yii::t('', $sToTranslate, array(), null, $sLanguage), $sEscapeMode);
}
</syntaxhighlight>

<hr>

=== Exceptions ===

todo

todo: exception hierarchy

todo: what can be repaired after exception? transaction rollback

* Exceptions are used to check inputs from the outside world (browser, database, file system)
* Don't use exceptions for control flow, only when fatal errors happen that make further execution impossible
* Exceptions should have clear error messages that make them ''actionable'' - there should be a clear "next step" for the user or developer
* Never, ever, do an empty catch-block

==== Alternatives to exceptions ====

Some people consider exceptions being a hidden form of "goto" which confuses the control flow of the program. They propose different other solutions:

* Return a tuple, like <code>[$result, $errorMessage]</code> where $errorMessage is null at success
* Return <code>null</code> at failure
* Tagged union result type (not yet possible in latest PHP)
* Result object

The con being that you have to manually propagate the error, where an exception can happen from anywhere in the stack trace without any other function knowing about it.

=== If-statements ===

If-statements should not be too long or hard to understand. If they are, consider factor out the checks into separate functions.

<syntaxhighlight lang="php">
if ((empty($instance->oOptions->{$attribute}))
|| (
!empty($instance->oOptions->{$attribute})
&& (
$instance->oOptions->{$attribute} === 'inherit'
|| $instance->oOptions->{$attribute} === 'I'
// NB: Do NOT use === here, it won't work with Postgresql.
|| $instance->oOptions->{$attribute} == '-1'
)
)
) {
</syntaxhighlight>

Can be shortened by factoring out method <code>isInherit</code>:

<syntaxhighlight lang="php">
if (empty($instance->options->{$attribute})
|| $this->isInherit($instance-options->{$attribute})) {
}
/**
* Returns true if $value is set to inherit
* @param mixed|null $value
* @return boolean
*/
public function isInherit($value) {
return !empty($value)
&& (
$value === 'inherit'
|| $value === 'I'
// NB: Do NOT use === here, it won't work with Postgresql.
|| $value == '-1'
);
}
</syntaxhighlight>

And one more time by using a variable for the value:

<syntaxhighlight lang="php">
$value = $instance->options->{$attribute};
if (empty($value) || $this->isInherit($value)) {
}
</syntaxhighlight>

More clear, right? "If it's empty or set to inherit, do this and that."

=== Variables ===

Descriptive naming.

* Follow PSR-12 - no underscore, use camelCaseLikeThis
* Variables of ActiveRecord classes can have same name as the class, like "$survey" or "$question"
* Add -s for plural when it's a list of items: "$surveys", "$questions"
* Never include "array" or "list" in variable names - using plural is enough (for lists, not for associative arrays - see below)
* The ''context'' of the function helps with variable naming, e..g "$name" might be fine in a function about questions; this is extra helpful when functions are short!
* When a function is short, it's much easier to figure out variable meaning based on context
* $qid, $gid, and $sid are so established in the code-base that they could be considered OK
* The -data suffix means "blob of stuff", only use it when needed, like with $viewData
* Use $result when baking a return value; add its exact type as @var annotation (worst possible name, acceptable but anything with more meaning is better)

Not so good:

<syntaxhighlight lang="php">
$result = LabelSet::model()->findAll();
</syntaxhighlight>

Better with model name and -s for plural:

<syntaxhighlight lang="php">
$labelSets = LabelSet::model()->findAll();
</syntaxhighlight>

* Do not use Hungarian notation (prefix with "type"), but instead <code>/** @var */</code> annotations - these can be checked automatically and will then be enforced to be correct, unlike Hungarian notation which can "rot"

<syntaxhighlight lang="php">
/** string[] An array of strings with 0-n elements */
$allFields = [];
</syntaxhighlight>

Psalm can infer types if the function documentation is enough. The strictness can be adjusted. Not all variables will need @var annotation, the tool will warn you when it's confused.

* Data that is sent to views as associative arrays will be:

<syntaxhighlight lang="php">
/** @var array Can be basically anything :( Better would be data-transfer objects or more precise notation */
$data = [];
// Maybe more clear as $viewData? Discuss.
</syntaxhighlight>

You can be more precise when you specify which type of array you're writing:

<syntaxhighlight lang="php">
/** @var array<string, string> This means the array key is string, and the array value is also string */
$data = [];
$data['name'] = 'Olle';
$data['occupation'] = 'Developer';
$data['age'] = 38; // ERROR! Value must be string.
</syntaxhighlight>

For more info about array type notation, see the [https://psalm.dev/docs/annotating_code/type_syntax/array_types/ Psalm documentation].

Some smaller examples:

<syntaxhighlight lang="php">
$theme = App()->request->getPost('theme'); // Should be $themeType - $theme looks like a model/AR
$gridid === 'questionthemes-grid'; // Should be $gridId with capital "I", since it's two words in English
$delete = Yii::app()->request->getParam('delete'); // Tuff one - $delete is ok? Thoughts?
$files = json_decode(stripslashes($sJSON), true); // $file is a resource, $files an array of resources, this is $fileData perhaps?
$valid_extensions_array = explode(",", $aAttributes['allowed_filetypes']); // Should be $validExtensionTypes
$language = Yii::app()->session['survey_' . $surveyid]['s_lang']; // TODO: Should this be a value class? Then Language::make(...);
$surveyInfo = getSurveyInfo($surveyId, $language); // OK, BUT should be a separate DTO!
$fieldMap = createFieldMap($survey, 'short', false, false, $language); // Same, make a DTO
$cquestions = array(); // What's "c"? Method name is getChildQuestions and $questions is an argument - better with $childQuestions?
</syntaxhighlight>

Links:

[https://www.approxion.com/capital-offenses-how-to-handle-abbreviations-in-camelcase/ How to Handle Abbreviations in CamelCase]

[https://stackoverflow.com/questions/15526107/acronyms-in-camelcase Acronyms in CamelCase]

=== Looping ===

* The bodies of foreach-loops are often a good candidate to factor out into separate functions.

'''Example:'''

<syntaxhighlight lang="php">
foreach ($questions as $question) {
processQuestion($question);
}
</syntaxhighlight>

Note the variable naming from plural to singular.

* Loop indexing should be named i, j, k etc.

'''Example:'''

<syntaxhighlight lang="php">
for ($i = 0; $i < $length; $i++) {
for ($j = 0; $j < $otherLength; $j++) {
// ...
}
}
</syntaxhighlight>

<hr>

=== Function composition ===

todo, "doThisAndThat" --> "doThis(doThat())"

=== Cases ===

<syntaxhighlight lang="php">
/**
* This function generates an array containing the fieldcode, and matching data in the same order as the activate script
*
* @param Survey $survey Survey ActiveRecord model
* @param string $style 'short' (default) or 'full' - full creates extra information like default values
* @param boolean $force_refresh - Forces to really refresh the array, not just take the session copy
* @param bool|int $questionid Limit to a certain qid only (for question preview) - default is false
* @param string $sLanguage The language to use
* @param array $aDuplicateQIDs
* @return array
*/
function createFieldMap($survey, $style = 'short', $force_refresh = false, $questionid = false, $sLanguage = '', &$aDuplicateQIDs = array())
</syntaxhighlight>

'''Good:'''

* Name is verb and noun
* Each argument is documented (almost)

'''Bad:'''

* Returns "array", which can be anything. A separate class for "Fieldmap" would be better.
* Not clear if it should be "createFieldMap" or "createFieldmap" - is "fieldmap" one word or two?
* Very many boolean arguments. Should probably be a class with methods like <code>$fieldmapCreator->setForceRefresh(true);</code> instead.
* Too long.
* Doesn't elaborate on what "fieldmap" really is, and does not link to any documentation about it.
* Access super-global, which makes it hard to test. Should instead return a data-transfer object, like:<br><syntaxhighlight lang="php">
$_SESSION['fieldmap'] = createFieldMap(...);
</syntaxhighlight>
* Has no test
* Mixes Hungarian notation with non-Hungarian notation in the argument list

== Defensive programming and error handling ==

todo

* '''Fail hard, fail early'''. The earlier the program crashes when something is wrong, the lower is the probability that you'll end up with corrupt data in the database that will later require manual labor to correct.
* Fail with '''actionable information'''
* Check input to functions and throw <code>InvalidArgumentException</code> if it violates the function's pre-conditions
* Use assert for class-internal invariants
* Use assert to make assumptions explicit for the reader

== Documentation ==

=== PHPDoc ===

* All functions must have a proper docblock
* The first line of the docblock should describe the relation between ''all'' the input arguments and the output of the function in a single sentence
* Each parameter must have the correct type
* Don't use <code>array</code> as type if it's a list of object - instead, use <code>[]</code> like so: <code>Survey[]</code> for a list of surveys

=== Technical documentation ===

todo, UML, scenarios, use-cases

== The PHP of yesterday ==

Old idioms and habits that should be abandoned.

* Don't use associative arrays, almost never. Data-transfer objects have multiple benefits: they are clearly structured, can be documented, can enforce invariants. There's ''no'' performance overhead of objects compared to arrays in modern PHP.
* Objects are already passed by reference; arrays are value types
* Use <code>[]</code> instead of <code>array()</code>
* Hungarian notation was useful before static analysis existed for PHP. These days it's better to use something that can be checked automatically: docblock @param and inline @var annotations.

== The PHP of tomorrow ==

todo

Union tags

Short functions

Match expressions

== Security ==

todo

XSS

Database injection

Permissions and roles

== Performance ==

todo

Loading too many rows into PHP models

== Testing ==

todo

QA

PHPUnit

TDD

Mocks, can't mock functions, static methods, mocking as a DSL, PHPUnit mocking tools

Pure functions, referential transparency, side-effects

Unit, functional, integration

Don't test the framework; don't test PHP

Makes sure the function or class lives up to its specification; make sure it will ''always'' live up to its specification, even in the future, to avoid regressions.

== Static analysis ==

<code>php -l</code>, CodeSniffer, Mess Detector, Psalm

== Database design ==

todo

== JavaScript ==

todo

classes, functions, components, tests

== CSS ==

todo

== HTML ==

todo

== Feedback ==

=== "Why do I have to refactor code that works?" ===

todo, Sadly, it's not enough for the code to live up to the current specification and requirements, it must also be protected against future changes, regressions. Adding tests is the best way for this. Lots of people might read and change the LimeSurvey code the next 5-10 years. The test suite creates a security layer to make sure the specification is fulfilled even as the code changes.

Tests are not a magical solution, however. It does not protect us against other degradation of the code quality, like classes gaining too much responsibility (too many methods, unrelated methods, too many properties).

=== "What's the correct ratio between integrity tests and unit tests?" ===

todo, Don't know. Different pros and cons.

* Unit-test can be run in parallel and are faster
* Unit-tests don't need setup and teardown

Cons of unit-tests is that they need a bigger effort on the side of the developer to make them possible, for example injecting the dependencies properly to enable mocking, or lifting side-effects up in the stack trace.

=== How to disagree ===

All rules can be broken. To break a rule, you should reason in terms of risk and the assumptions used in this guide.

'''Assumptions:'''

# Regressions are the biggest technical risk for LimeSurvey the last five years (2021)
# Automated tests are the best risk mitigation technique against regressions

'''Possible disagreement:'''

# A certain piece of code has very low ''probability'' of regressions (maybe we "know" no one else will every touch or change it?)
# Regression in a certain piece of code would have very low ''impact''

== Architectural Decision Records ==

todo

https://adr.github.io/

== Resources ==

todo

Books, links, videos

Code quality guide

2021-05-19T09:53:39Z

Olle: /* Shape design problem */

DRAFT

== Prologue ==

# '''Be risk aware'''. Too good code can be a business risk (slow to write, maybe over-designed). Too sloppy code can also be a business risk (hard to maintain and understand). You have to find a balance that is adapted to the current situation and risk analysis, in which code quality becomes a '''risk mitigation''' technique among others.
# '''Be humble'''. LimeSurvey was made by developers from all over the world, with different age, education and experience. Your code might be read by a completely different team ten years from now, in the same way you are now reading code by developers that no longer work with us, but which work pays our rent.
# '''Performance matters sometimes''', and shouldn't be disregarded completely. In particular, database queries using the ORM and ActiveRecord can be problematic. Some surveys have thousands of questions and hundreds of thousands of responses. Fast response time is also important for a fluid user experience.
# '''It's harder to read code than to write code'''. Don't choose patterns that are easy or fast to write, but that are easy to read.
# Make your code '''communicate intent'''.
# It's easy to forget '''cross-cutting concerns''' like translation and security. Keep a mental note.
# '''Stress affects code quality''' and your risk behaviour. If your stress level is too high to write code with proper quality, take a step back and discuss it with your boss, or you'll push problems to the future.

== Quality ==

The purpose of this guide is to increase the quality of the LimeSurvey code-base. What is quality? Which aspects of quality can be measured? Which kind of company culture gives rise to appropriate code quality?

It's usually easier to get along what is "bad" code than what's "best" code. Blacklist instead of whitelist?

Quality attributes related to code quality:

* Readability
* Testability
* Maintainability
* Performance
* Security
* Reliability

Can not increase all at the same time - performance vs readability.

It's better to avoid emotional language when describing code quality, like "clean" or "dirty". Be precise, objective and suggest solutions.

Idiomatic code is more readable than non-idiomatic code. What's idiomatic depends on which context or domain you work in. We work in PHP and web application development, and have other idioms than in, say, functional or hardware-close programming.

Some code are "hot spots" - changed often. Those parts should require higher quality than other code.

== Risk ==

todo

Couple of different definition of risk:

* Tuple of probability and severity
* Triple of consequence, uncertainty and knowledge base

Possible risks related to LimeSurvey (technical or business):

* Data loss
* Regressions
* Bad UI (higher churn-rate for users)
* Hard to maintain (reduced sprint velocity)
*

How know which is the biggest risk? How many risks can be approached at once?

Connection to architecture. Risk --> quality attributes --> architectural decisions.

usability a business risk - hard to use or understand, people will choose another tool

risks relevant when fixing bugs

risks relevant when adding new features (lack of testing, wrong requirements, scope creep)

risks relevant when refactoring (regressions)

unit tests and QA as risk mitigation

partial deployment, alpha/beta/rc, risk communication

software rot, design pattern rot/grime, software evolution

rot = non-pattern related code

testing by community, bug fixing by community

== Modules ==

There's no inherit module functionality in PHP, but Yii has a module system. Libraries can be seen as a module system.

Examples of implicit modules in LimeSurvey:

* Front-end (survey taking)
* Back-end (survey design)
* Survey theme editing
* Expression manager
* Plugin system

In the future, they need to be separated and implemented more clearly as whatever Yii 3 module system is in use.

Some data models are common for all modules, e.g. surveys and users. Can have a "Common" module for such data.

todo, relation to Yii config system

== Classes ==

* Avoid empty OOP ceremony, like defining getters and setters for all properties. Might as well make them public, ''unless'' they have invariants that need to be upheld, e.g. "this number is always between 1 and 10" or "this string is maximum length 20".
* Almost always avoid static methods. They cannot be mocked. One exception is (possibly) factory methods (Foo::make(...)).
* Inject all dependencies. This will make sure the class can be unit-tested (unit-tests have several benefits over integrity tests - they can be run in parallel and don't require any setup and teardown)
* A second way to achieve testability is to factor out the methods that access the dependencies

todo, state vs behaviour, state vs dependencies

=== OOP design ===

Start from top-down, with domain, behaviour, interaction between objects, database design, pseudo-code if needed. Can also include scenarios, use-cases and UML diagrams.

Object reification - not only domain models, but also domain actions, relations and activities can be objects, e.g. a class ActivateSurvey or ExportSurvey.

Hierarchy depth should be kept reasonable shallow to avoid conflicts between methods, spooky action at a distance. Compare with Yii 3, where controllers no longer inherit anything.

Some people advocate for composition instead of inheritance. Lots of blog posts available for more info.

Multiple inheritance is done with traits in PHP. Use-case: ActiveRecords where some but not all models support encryption.

==== Shape design problem ====

Point (x, y), rectangle (bottomLeft, topRight), circle (point, radius (int))

Area, draw

* Cohesion: A class (or module) should be responsible for one thing only
* Coupling: You should be able to ''isolate change'' in the system
* Encapsulation: Classes shouldn’t share internal representation
* Polymorphism: The design should be based on interfaces

Questions to consider:

* How easy would it be to move to a 3D representation?
* How easy would it be to add a new shape, say, triangle?
* How easy would it be to add a new behaviour to all shapes, like save/load from a SQL database?
* Which classes ''change together''?

Keep polymorphism and encapsulation - all properties are private.

forall shapes as shape, do shape.draw(surface)

forall shapes as shape, do surface.draw(shape) (where shape.getDrawData(), or shape.getPath())

=== Software evolution ===

Design rot after time - how to keep it tight? (Grime.)

todo

==== Grime and rot ====

design pattern rot --> lose behaviour relevant for pattern (active record without db connection)

design patter grime --> add behaviour irrelevant for pattern (active record that's also a singleton)

==== Class cohesion ====

LCOM

==== Modular coupling ====

todo

=== State ===

Heuristics to consider but not follow slavishly.

Keep a clear separation between classes with state and classes with no state.

Classes with state should not have dependencies with IO (it's OK to depend on classes in the same application layer, e.g. other DTO classes), and vice versa. ActiveRecord is an example which violates this principle.

class Survey
// Confusion - first params are domain state, last a resource
__construct(id, language, dbConnection)

If a method does not call "this", should it instead be outside the class? A separate class or function, maybe.

todo, elaborate

=== Types of classes ===

Different categories of classes:

* Entity (domain class; has state and validation behaviour)
* Resource (database connection, file, curl, logger; state is in the resource (open, closed))
* Repository classes (database interaction, like splitting ActiveRecord in two parts: Entity class and database interaction)
* DAO, data access object (similar to resource)
* Builders (e.g. query builder, HTML message builder)
* Data-transfer object (no behaviour; pass to views to have better documentation and intent than associative arrays)
* Value classes (e.g. Email address to wrap email string around)
* Command object (e.g. SurveyActivator)
* Helper (no state; e.g. QuestionAttributeHelper to bake attributes into different formats used by the views)
* Wrapper

todo, immutability, possible with private properties that are set in the constructor,

todo: command-query separation for classes?

todo: dependencies between layers, dependencies to the framework

todo, pure vs effectful classes

=== Types of classes in LimeSurvey ===

* ActiveRecord, used to communicate with the database, and should not do ''anything'' else
* Controllers, used for glue code; should not contain business-logic (also CLI controllers)
* Helper functions (not classes, yet...), should be short and obey command-query separation (TODO: Long functions should be separated into command objects or service classes); todo: should not have any dependencies?
* Helper classes, similar to helper functions but have dependencies that need to be mocked during tests; should not have any state
* Service classes, contains logic related to a clear and separate task, like create or import survey
* Question render classes, contains logic related to how questions are rendered (TODO: Need better separation between state and logic and more clear design); similar to widgets
* Plugin classes, using the plugin event system
* Widgets, containing HTML logic for custom HTML widgets
* HTML helpers (Yii)
* Customizations to the Yii framework by inheritance
* Unit and functional test classes

A couple of classes contain only data, like LsDefaultDataSet.

todo, no difference between state property and dependency property in OOP

=== What is "glue code"? ===

todo

Putting the pieces together, e.g. service class A need data from model B, fetch it and run.

todo, add example

=== "Where do I cut?" ===

Separation of concerns, but which concerns and which type of separation? Command-query (function core, imperative shell) is one type of separation. Other separation between layers, e.g. logic layer and data persistency layer (similar in thought).

Other separation, that one class should have a clear purpose. A design pattern should only implement ''one'' pattern, not multiple, and not half a pattern.

There's a problem with "helper" or "manager" classes that they can grow indefinitely, but might be better than nothing. Example when moving business logic out of ActiveRecord class to a helper class it can sometimes hard to be more specific than "helper".

=== Size ===

A class should have a single and clear purpose; compare with [https://en.wikipedia.org/wiki/SOLID SOLID].

=== Class name ===

* ActiveRecord classes are named after the database table they are bound to, but with singular instead of plural. E.g. table "lime_users" have model "User".
* Command classes are named after what they ''do'' and imperatively, e.g. CreateSurvey
* Helper classes should probably be named as specific as possible when possible, to avoid them from growing too big
* Follow the naming tradition of the framework with regard to controllers, e.g. UserController or UserAdministrationController.
* Class properties of ActiveRecord classes will follow the naming of the database, using underscore instead of camel case (and ActiveRecord classes should have ''no'' other properties than those (excluding the database connection injected by the framework))

== Functions ==

Functions are one of the fundamental building blocks of programming, so it's important to get it right.

Functions that are part of a class are called "methods", if you want to be formal.

Different types of functions in PHP:

* Functions (not attached to a class)
* Methods (attached to class)
* Anonymous functions (does not capture scope automatically)
* Short functions (does capture scope automatically)

I'm using "function" as a word for all types of functions in PHP below.

<hr>

=== Size ===

* A function should be short enough to be completely readable on one screen, approx 60 lines at most
* A function should not have too many arguments; if you have five or more, consider making it a class instead
* If a function is growing too big, it might be better to create a class instead or split it into several functions (if both functions have '''common state''', a class might be better, unless you want to pass around '''explicit state''')

=== Contract ===

* A function has a contract with its surrounding environment:
** Pre-condition: What needs to be true before the function is executed
** Post-condition: What will be true after the function has returned
* The function contract can be checked with assertions (internal invariants) or exceptions (outside world); see below
* Another good way is to use unit-tests to make sure the function's contract remains stable through changes
* The first line in the docblock should be one sentence describing the relation between function arguments and its output<br>Example<br><syntaxhighlight lang="php">
/**
* Creates a random password of length $length (defaults to 12)
* @param int $length
* @return string
*/
function createPassword($lenght = 12)

/**
* Creates an HTML language drop down for survey with id $surveyId, marking $selectedLanguage as selected
* @param int $surveyId
* @param string $selectedLanguage
* @return string <select> HTML
*/
function createLanguageDropdown($surveyId, $selectedLanguage)

</syntaxhighlight>

=== Push side-effects up in the stack trace ===

This one is a bit abstract.

First, what is a '''side-effect'''? In short, it's anything that happens in a function that ''is not'' described by the ''relation'' between function arguments and output.

Another way to phrase it is, that a side-effect is anything that is not always the same for the given input to a function; a function without any side-effects will always return the same result if it gets the same input.

'''Examples:'''

<syntaxhighlight lang="php">
// gT accesses the file system and will return different result depending on what's in the translation files
function gT($sToTranslate, $sEscapeMode = 'html', $sLanguage = null);

// If $sText and $sEscapeMode is always the same, quoteText() will always return the same string.
function quoteText($sText, $sEscapeMode = 'html');
</syntaxhighlight>

A function with no side-effects is called '''pure'''. A function that is guaranteed to always return (no exceptions, no errors, no warnings, no division by zero) is called '''total'''.

It's a good thing if functions in a code-base ''either'' have side-effects, ''or'' return a result. Not both. This is called [https://en.wikipedia.org/wiki/Command%E2%80%93query_separation command-query separation].

Examples of side-effects:

* Database or file access
* Echo, or write to stdout or stderr
* Randomization

Why does this matter? Because side-effects make testing harder! '''If you have side-effects, you cannot create unit tests''', ''unless'' those side-effects can be mocked. If not, you need integrity tests with database setup or more. The more side-effects you have in a function, the more mocking is required to unit test it.

So, one solution to this is to move side-effects higher up in the stack trace, that is, move them to the calling code.

'''Example:'''

<syntaxhighlight lang="php">
function getSurveyInfo(int $surveyid, string $languagecode = '', boolean $force = false): array;
</syntaxhighlight>

Since this function takes $surveyid, we know it will probably query the database. Quering the database is a side-effect, and thus it requires a database scaffold for the test (or mocking, but the database connection is not injected, so there's no way to do it). One simple solution is to lift the side-effect out and pass in a Survey object instead:

<syntaxhighlight lang="php">
function getSurveyInfo(Survey $survey, string $languagecode = '', boolean $force = false): array;
</syntaxhighlight>

Much better! The side-effect of calling the database now happens ''before'' the function call. Now we can either mock a Survey object, or make an imitating stub for our test.

Reading the function body, there is in fact another database access, but since this is a relation to the Survey model, it could easily be moved out too. We've just made a function testable! Hooray!

This principle is rephrased in an architectural settings as [https://github.com/kbilsted/Functional-core-imperative-shell/blob/master/README.md functional core, imperative shell]. This architecture helps you get a good ratio between fast unit tests and slower integrity tests.

Moving side-effects up makes sure we can have a healthy ratio between integrity tests with scripted browser, and unit-tests; maybe around 20-80.

=== Function name ===

* The function name should tell you '''what''' it does; docs should tell you '''why''' (if this information is not obvious). '''How''' is described by the code itself (hopefully, but can in some cases be relevant to document).
* Function name can often be '''verb [+ adjective] + noun''', like "createFieldmap", "quoteText", "getRelativePath"
* Prefix with "is" for boolean functions

todo: difference between create, get, fetch, generate, ...

'''Good examples:'''

* createPassword() - One verb, one noun - clear
* isCaptchaEnabled() - Using "is" signifies it returns boolean; clear purpose
* getFullResponseTable() - Verb, adjective, noun - but is "full" needed here? Is there a non-full version of the same function?
* replaceExpressionCodes() - Pretty good, but it's obvious that more information is needed in the docblock to describe what "replace" means, and what an "expression code" is
* fixCKeditorText() - "fix" is a bit vague, but maybe best there is? Pray that docblock contains information!

'''Bad examples:'''

* languageDropdown() - No verb, doesn't tell you what it does
* rmdirr() - Two r's, looks like a typo, but the last "r" actually means "recursive"! Better: rmdir($recursive = false), rmdir or removeFolder.
* CSVUnquote() - Is CSV really the namespace? Why is the verb the second word?
* incompleteAnsFilterState() - One verb, but in the middle, or is "filter state" a noun?; why abbreviate "answer" to "ans"?
* reverseTranslateFieldNames() - Two verbs - did author mean "reverseTranslatedFieldNames"? Or "reverse and translate"? If so, it should be two functions, one for reverse and one for translate
* checkUploadedFileSizeAndRenderJson() - If you have an "and" in the function name, you should consider splitting it into two functions

'''Controversial'''

* gT() - An exception to descriptive function names; since this is used everywhere, the minimal name is motivated; maybe even name it "t()"? Still hard to read for someone who just started? But Yii uses t() too? Other frameworks use double underscore (Wordpress, Laravel) as function name.

<hr>

=== Function filename and namespace ===

If your function has dependencies or side-effects, it should be put into a class instead, in which the dependencies can be injected. Another alternative is to put the dependencies as argument in the function, although this muffles the relationship between input and output. Again, this is to increase testability.

Keep in mind that functions outside classes cannot be mocked, so only use them when you ''know'' you won't need to mock them.

todo, autoloading of functions and folder location

=== Assertions ===

NB: This is not assertions as used in unit-tests, but assertions as used to check invariants in production code.

Assertions can be used for mental checks. They are only used for internal logic - failed assertions are not supposed to be seen by the end user. For interaction with the outside world, like database or browser, exceptions should be used instead.

Assertions can be disabled in production mode and have then no runtime cost (since PHP 7).

'''Example:'''

<syntaxhighlight lang="php">
/**
* Translation helper function
*
* @param string $sToTranslate
* @param string $sEscapeMode Valid values are html (this is the default, js and unescaped)
* @param string $sLanguage
* @return string
*/
function gT($sToTranslate, $sEscapeMode = 'html', $sLanguage = null)
{
assert(is_string($sToTranslate));
assert(strlen($sToTranslate) > 0);
assert($sEscapeMode === 'html' || $sEscapeMode === 'js' || $sEscapeMode === 'unescaped');
return quoteText(Yii::t('', $sToTranslate, array(), null, $sLanguage), $sEscapeMode);
}
</syntaxhighlight>

<hr>

=== Exceptions ===

todo

todo: exception hierarchy

todo: what can be repaired after exception? transaction rollback

* Exceptions are used to check inputs from the outside world (browser, database, file system)
* Don't use exceptions for control flow, only when fatal errors happen that make further execution impossible
* Exceptions should have clear error messages that make them ''actionable'' - there should be a clear "next step" for the user or developer
* Never, ever, do an empty catch-block

==== Alternatives to exceptions ====

Some people consider exceptions being a hidden form of "goto" which confuses the control flow of the program. They propose different other solutions:

* Return a tuple, like <code>[$result, $errorMessage]</code> where $errorMessage is null at success
* Return <code>null</code> at failure
* Tagged union result type (not yet possible in latest PHP)
* Result object

The con being that you have to manually propagate the error, where an exception can happen from anywhere in the stack trace without any other function knowing about it.

=== If-statements ===

If-statements should not be too long or hard to understand. If they are, consider factor out the checks into separate functions.

<syntaxhighlight lang="php">
if ((empty($instance->oOptions->{$attribute}))
|| (
!empty($instance->oOptions->{$attribute})
&& (
$instance->oOptions->{$attribute} === 'inherit'
|| $instance->oOptions->{$attribute} === 'I'
// NB: Do NOT use === here, it won't work with Postgresql.
|| $instance->oOptions->{$attribute} == '-1'
)
)
) {
</syntaxhighlight>

Can be shortened by factoring out method <code>isInherit</code>:

<syntaxhighlight lang="php">
if (empty($instance->options->{$attribute})
|| $this->isInherit($instance-options->{$attribute})) {
}
/**
* Returns true if $value is set to inherit
* @param mixed|null $value
* @return boolean
*/
public function isInherit($value) {
return !empty($value)
&& (
$value === 'inherit'
|| $value === 'I'
// NB: Do NOT use === here, it won't work with Postgresql.
|| $value == '-1'
);
}
</syntaxhighlight>

And one more time by using a variable for the value:

<syntaxhighlight lang="php">
$value = $instance->options->{$attribute};
if (empty($value) || $this->isInherit($value)) {
}
</syntaxhighlight>

More clear, right? "If it's empty or set to inherit, do this and that."

=== Variables ===

Descriptive naming.

* Follow PSR-12 - no underscore, use camelCaseLikeThis
* Variables of ActiveRecord classes can have same name as the class, like "$survey" or "$question"
* Add -s for plural when it's a list of items: "$surveys", "$questions"
* Never include "array" or "list" in variable names - using plural is enough (for lists, not for associative arrays - see below)
* The ''context'' of the function helps with variable naming, e..g "$name" might be fine in a function about questions; this is extra helpful when functions are short!
* When a function is short, it's much easier to figure out variable meaning based on context
* $qid, $gid, and $sid are so established in the code-base that they could be considered OK
* The -data suffix means "blob of stuff", only use it when needed, like with $viewData
* Use $result when baking a return value; add its exact type as @var annotation (worst possible name, acceptable but anything with more meaning is better)

Not so good:

<syntaxhighlight lang="php">
$result = LabelSet::model()->findAll();
</syntaxhighlight>

Better with model name and -s for plural:

<syntaxhighlight lang="php">
$labelSets = LabelSet::model()->findAll();
</syntaxhighlight>

* Do not use Hungarian notation (prefix with "type"), but instead <code>/** @var */</code> annotations - these can be checked automatically and will then be enforced to be correct, unlike Hungarian notation which can "rot"

<syntaxhighlight lang="php">
/** string[] An array of strings with 0-n elements */
$allFields = [];
</syntaxhighlight>

Psalm can infer types if the function documentation is enough. The strictness can be adjusted. Not all variables will need @var annotation, the tool will warn you when it's confused.

* Data that is sent to views as associative arrays will be:

<syntaxhighlight lang="php">
/** @var array Can be basically anything :( Better would be data-transfer objects or more precise notation */
$data = [];
// Maybe more clear as $viewData? Discuss.
</syntaxhighlight>

You can be more precise when you specify which type of array you're writing:

<syntaxhighlight lang="php">
/** @var array<string, string> This means the array key is string, and the array value is also string */
$data = [];
$data['name'] = 'Olle';
$data['occupation'] = 'Developer';
$data['age'] = 38; // ERROR! Value must be string.
</syntaxhighlight>

For more info about array type notation, see the [https://psalm.dev/docs/annotating_code/type_syntax/array_types/ Psalm documentation].

Some smaller examples:

<syntaxhighlight lang="php">
$theme = App()->request->getPost('theme'); // Should be $themeType - $theme looks like a model/AR
$gridid === 'questionthemes-grid'; // Should be $gridId with capital "I", since it's two words in English
$delete = Yii::app()->request->getParam('delete'); // Tuff one - $delete is ok? Thoughts?
$files = json_decode(stripslashes($sJSON), true); // $file is a resource, $files an array of resources, this is $fileData perhaps?
$valid_extensions_array = explode(",", $aAttributes['allowed_filetypes']); // Should be $validExtensionTypes
$language = Yii::app()->session['survey_' . $surveyid]['s_lang']; // TODO: Should this be a value class? Then Language::make(...);
$surveyInfo = getSurveyInfo($surveyId, $language); // OK, BUT should be a separate DTO!
$fieldMap = createFieldMap($survey, 'short', false, false, $language); // Same, make a DTO
$cquestions = array(); // What's "c"? Method name is getChildQuestions and $questions is an argument - better with $childQuestions?
</syntaxhighlight>

Links:

[https://www.approxion.com/capital-offenses-how-to-handle-abbreviations-in-camelcase/ How to Handle Abbreviations in CamelCase]

[https://stackoverflow.com/questions/15526107/acronyms-in-camelcase Acronyms in CamelCase]

=== Looping ===

* The bodies of foreach-loops are often a good candidate to factor out into separate functions.

'''Example:'''

<syntaxhighlight lang="php">
foreach ($questions as $question) {
processQuestion($question);
}
</syntaxhighlight>

Note the variable naming from plural to singular.

* Loop indexing should be named i, j, k etc.

'''Example:'''

<syntaxhighlight lang="php">
for ($i = 0; $i < $length; $i++) {
for ($j = 0; $j < $otherLength; $j++) {
// ...
}
}
</syntaxhighlight>

<hr>

=== Function composition ===

todo, "doThisAndThat" --> "doThis(doThat())"

=== Cases ===

<syntaxhighlight lang="php">
/**
* This function generates an array containing the fieldcode, and matching data in the same order as the activate script
*
* @param Survey $survey Survey ActiveRecord model
* @param string $style 'short' (default) or 'full' - full creates extra information like default values
* @param boolean $force_refresh - Forces to really refresh the array, not just take the session copy
* @param bool|int $questionid Limit to a certain qid only (for question preview) - default is false
* @param string $sLanguage The language to use
* @param array $aDuplicateQIDs
* @return array
*/
function createFieldMap($survey, $style = 'short', $force_refresh = false, $questionid = false, $sLanguage = '', &$aDuplicateQIDs = array())
</syntaxhighlight>

'''Good:'''

* Name is verb and noun
* Each argument is documented (almost)

'''Bad:'''

* Returns "array", which can be anything. A separate class for "Fieldmap" would be better.
* Not clear if it should be "createFieldMap" or "createFieldmap" - is "fieldmap" one word or two?
* Very many boolean arguments. Should probably be a class with methods like <code>$fieldmapCreator->setForceRefresh(true);</code> instead.
* Too long.
* Doesn't elaborate on what "fieldmap" really is, and does not link to any documentation about it.
* Access super-global, which makes it hard to test. Should instead return a data-transfer object, like:<br><syntaxhighlight lang="php">
$_SESSION['fieldmap'] = createFieldMap(...);
</syntaxhighlight>
* Has no test
* Mixes Hungarian notation with non-Hungarian notation in the argument list

== Defensive programming and error handling ==

todo

* '''Fail hard, fail early'''. The earlier the program crashes when something is wrong, the lower is the probability that you'll end up with corrupt data in the database that will later require manual labor to correct.
* Fail with '''actionable information'''
* Check input to functions and throw <code>InvalidArgumentException</code> if it violates the function's pre-conditions
* Use assert for class-internal invariants
* Use assert to make assumptions explicit for the reader

== Documentation ==

=== PHPDoc ===

* All functions must have a proper docblock
* The first line of the docblock should describe the relation between ''all'' the input arguments and the output of the function in a single sentence
* Each parameter must have the correct type
* Don't use <code>array</code> as type if it's a list of object - instead, use <code>[]</code> like so: <code>Survey[]</code> for a list of surveys

=== Technical documentation ===

todo, UML, scenarios, use-cases

== The PHP of yesterday ==

Old idioms and habits that should be abandoned.

* Don't use associative arrays, almost never. Data-transfer objects have multiple benefits: they are clearly structured, can be documented, can enforce invariants. There's ''no'' performance overhead of objects compared to arrays in modern PHP.
* Objects are already passed by reference; arrays are value types
* Use <code>[]</code> instead of <code>array()</code>
* Hungarian notation was useful before static analysis existed for PHP. These days it's better to use something that can be checked automatically: docblock @param and inline @var annotations.

== The PHP of tomorrow ==

todo

Union tags

Short functions

Match expressions

== Security ==

todo

XSS

Database injection

Permissions and roles

== Performance ==

todo

Loading too many rows into PHP models

== Testing ==

todo

QA

PHPUnit

TDD

Mocks, can't mock functions, static methods, mocking as a DSL, PHPUnit mocking tools

Pure functions, referential transparency, side-effects

Unit, functional, integration

Don't test the framework; don't test PHP

Makes sure the function or class lives up to its specification; make sure it will ''always'' live up to its specification, even in the future, to avoid regressions.

== Static analysis ==

<code>php -l</code>, CodeSniffer, Mess Detector, Psalm

== Database design ==

todo

== JavaScript ==

todo

classes, functions, components, tests

== CSS ==

todo

== HTML ==

todo

== Feedback ==

=== "Why do I have to refactor code that works?" ===

todo, Sadly, it's not enough for the code to live up to the current specification and requirements, it must also be protected against future changes, regressions. Adding tests is the best way for this. Lots of people might read and change the LimeSurvey code the next 5-10 years. The test suite creates a security layer to make sure the specification is fulfilled even as the code changes.

Tests are not a magical solution, however. It does not protect us against other degradation of the code quality, like classes gaining too much responsibility (too many methods, unrelated methods, too many properties).

=== "What's the correct ratio between integrity tests and unit tests?" ===

todo, Don't know. Different pros and cons.

* Unit-test can be run in parallel and are faster
* Unit-tests don't need setup and teardown

Cons of unit-tests is that they need a bigger effort on the side of the developer to make them possible, for example injecting the dependencies properly to enable mocking, or lifting side-effects up in the stack trace.

=== How to disagree ===

All rules can be broken. To break a rule, you should reason in terms of risk and the assumptions used in this guide.

'''Assumptions:'''

# Regressions are the biggest technical risk for LimeSurvey the last five years (2021)
# Automated tests are the best risk mitigation technique against regressions

'''Possible disagreement:'''

# A certain piece of code has very low ''probability'' of regressions (maybe we "know" no one else will every touch or change it?)
# Regression in a certain piece of code would have very low ''impact''

== Architectural Decision Records ==

todo

https://adr.github.io/

== Resources ==

todo

Books, links, videos

Code quality guide

2021-05-19T09:48:53Z

Olle: /* Shape design problem */

DRAFT

== Prologue ==

# '''Be risk aware'''. Too good code can be a business risk (slow to write, maybe over-designed). Too sloppy code can also be a business risk (hard to maintain and understand). You have to find a balance that is adapted to the current situation and risk analysis, in which code quality becomes a '''risk mitigation''' technique among others.
# '''Be humble'''. LimeSurvey was made by developers from all over the world, with different age, education and experience. Your code might be read by a completely different team ten years from now, in the same way you are now reading code by developers that no longer work with us, but which work pays our rent.
# '''Performance matters sometimes''', and shouldn't be disregarded completely. In particular, database queries using the ORM and ActiveRecord can be problematic. Some surveys have thousands of questions and hundreds of thousands of responses. Fast response time is also important for a fluid user experience.
# '''It's harder to read code than to write code'''. Don't choose patterns that are easy or fast to write, but that are easy to read.
# Make your code '''communicate intent'''.
# It's easy to forget '''cross-cutting concerns''' like translation and security. Keep a mental note.
# '''Stress affects code quality''' and your risk behaviour. If your stress level is too high to write code with proper quality, take a step back and discuss it with your boss, or you'll push problems to the future.

== Quality ==

The purpose of this guide is to increase the quality of the LimeSurvey code-base. What is quality? Which aspects of quality can be measured? Which kind of company culture gives rise to appropriate code quality?

It's usually easier to get along what is "bad" code than what's "best" code. Blacklist instead of whitelist?

Quality attributes related to code quality:

* Readability
* Testability
* Maintainability
* Performance
* Security
* Reliability

Can not increase all at the same time - performance vs readability.

It's better to avoid emotional language when describing code quality, like "clean" or "dirty". Be precise, objective and suggest solutions.

Idiomatic code is more readable than non-idiomatic code. What's idiomatic depends on which context or domain you work in. We work in PHP and web application development, and have other idioms than in, say, functional or hardware-close programming.

Some code are "hot spots" - changed often. Those parts should require higher quality than other code.

== Risk ==

todo

Couple of different definition of risk:

* Tuple of probability and severity
* Triple of consequence, uncertainty and knowledge base

Possible risks related to LimeSurvey (technical or business):

* Data loss
* Regressions
* Bad UI (higher churn-rate for users)
* Hard to maintain (reduced sprint velocity)
*

How know which is the biggest risk? How many risks can be approached at once?

Connection to architecture. Risk --> quality attributes --> architectural decisions.

usability a business risk - hard to use or understand, people will choose another tool

risks relevant when fixing bugs

risks relevant when adding new features (lack of testing, wrong requirements, scope creep)

risks relevant when refactoring (regressions)

unit tests and QA as risk mitigation

partial deployment, alpha/beta/rc, risk communication

software rot, design pattern rot/grime, software evolution

rot = non-pattern related code

testing by community, bug fixing by community

== Modules ==

There's no inherit module functionality in PHP, but Yii has a module system. Libraries can be seen as a module system.

Examples of implicit modules in LimeSurvey:

* Front-end (survey taking)
* Back-end (survey design)
* Survey theme editing
* Expression manager
* Plugin system

In the future, they need to be separated and implemented more clearly as whatever Yii 3 module system is in use.

Some data models are common for all modules, e.g. surveys and users. Can have a "Common" module for such data.

todo, relation to Yii config system

== Classes ==

* Avoid empty OOP ceremony, like defining getters and setters for all properties. Might as well make them public, ''unless'' they have invariants that need to be upheld, e.g. "this number is always between 1 and 10" or "this string is maximum length 20".
* Almost always avoid static methods. They cannot be mocked. One exception is (possibly) factory methods (Foo::make(...)).
* Inject all dependencies. This will make sure the class can be unit-tested (unit-tests have several benefits over integrity tests - they can be run in parallel and don't require any setup and teardown)
* A second way to achieve testability is to factor out the methods that access the dependencies

todo, state vs behaviour, state vs dependencies

=== OOP design ===

Start from top-down, with domain, behaviour, interaction between objects, database design, pseudo-code if needed. Can also include scenarios, use-cases and UML diagrams.

Object reification - not only domain models, but also domain actions, relations and activities can be objects, e.g. a class ActivateSurvey or ExportSurvey.

Hierarchy depth should be kept reasonable shallow to avoid conflicts between methods, spooky action at a distance. Compare with Yii 3, where controllers no longer inherit anything.

Some people advocate for composition instead of inheritance. Lots of blog posts available for more info.

Multiple inheritance is done with traits in PHP. Use-case: ActiveRecords where some but not all models support encryption.

==== Shape design problem ====

Point (x, y), rectangle (bottomLeft, topRight), circle (point, radius (int))

Area, draw

* Cohesion: A class (or module) should be responsible for one thing only
* Coupling: You should be able to ''isolate change'' in the system
* Encapsulation: Classes shouldn’t share internal representation
* Polymorphism: The design should be based on interfaces

Questions to consider:

* How easy would it be to move to a 3D representation?
* How easy would it be to add a new shape, say, triangle?
* How easy would it be to add a new behaviour to all shapes, like save/load from a SQL database?

Keep polymorphism and encapsulation - all properties are private.

forall shapes as shape, do shape.draw(surface)

forall shapes as shape, do surface.draw(shape) (where shape.getDrawData(), or shape.getPath())

=== Software evolution ===

Design rot after time - how to keep it tight? (Grime.)

todo

==== Grime and rot ====

design pattern rot --> lose behaviour relevant for pattern (active record without db connection)

design patter grime --> add behaviour irrelevant for pattern (active record that's also a singleton)

==== Class cohesion ====

LCOM

==== Modular coupling ====

todo

=== State ===

Heuristics to consider but not follow slavishly.

Keep a clear separation between classes with state and classes with no state.

Classes with state should not have dependencies with IO (it's OK to depend on classes in the same application layer, e.g. other DTO classes), and vice versa. ActiveRecord is an example which violates this principle.

class Survey
// Confusion - first params are domain state, last a resource
__construct(id, language, dbConnection)

If a method does not call "this", should it instead be outside the class? A separate class or function, maybe.

todo, elaborate

=== Types of classes ===

Different categories of classes:

* Entity (domain class; has state and validation behaviour)
* Resource (database connection, file, curl, logger; state is in the resource (open, closed))
* Repository classes (database interaction, like splitting ActiveRecord in two parts: Entity class and database interaction)
* DAO, data access object (similar to resource)
* Builders (e.g. query builder, HTML message builder)
* Data-transfer object (no behaviour; pass to views to have better documentation and intent than associative arrays)
* Value classes (e.g. Email address to wrap email string around)
* Command object (e.g. SurveyActivator)
* Helper (no state; e.g. QuestionAttributeHelper to bake attributes into different formats used by the views)
* Wrapper

todo, immutability, possible with private properties that are set in the constructor,

todo: command-query separation for classes?

todo: dependencies between layers, dependencies to the framework

todo, pure vs effectful classes

=== Types of classes in LimeSurvey ===

* ActiveRecord, used to communicate with the database, and should not do ''anything'' else
* Controllers, used for glue code; should not contain business-logic (also CLI controllers)
* Helper functions (not classes, yet...), should be short and obey command-query separation (TODO: Long functions should be separated into command objects or service classes); todo: should not have any dependencies?
* Helper classes, similar to helper functions but have dependencies that need to be mocked during tests; should not have any state
* Service classes, contains logic related to a clear and separate task, like create or import survey
* Question render classes, contains logic related to how questions are rendered (TODO: Need better separation between state and logic and more clear design); similar to widgets
* Plugin classes, using the plugin event system
* Widgets, containing HTML logic for custom HTML widgets
* HTML helpers (Yii)
* Customizations to the Yii framework by inheritance
* Unit and functional test classes

A couple of classes contain only data, like LsDefaultDataSet.

todo, no difference between state property and dependency property in OOP

=== What is "glue code"? ===

todo

Putting the pieces together, e.g. service class A need data from model B, fetch it and run.

todo, add example

=== "Where do I cut?" ===

Separation of concerns, but which concerns and which type of separation? Command-query (function core, imperative shell) is one type of separation. Other separation between layers, e.g. logic layer and data persistency layer (similar in thought).

Other separation, that one class should have a clear purpose. A design pattern should only implement ''one'' pattern, not multiple, and not half a pattern.

There's a problem with "helper" or "manager" classes that they can grow indefinitely, but might be better than nothing. Example when moving business logic out of ActiveRecord class to a helper class it can sometimes hard to be more specific than "helper".

=== Size ===

A class should have a single and clear purpose; compare with [https://en.wikipedia.org/wiki/SOLID SOLID].

=== Class name ===

* ActiveRecord classes are named after the database table they are bound to, but with singular instead of plural. E.g. table "lime_users" have model "User".
* Command classes are named after what they ''do'' and imperatively, e.g. CreateSurvey
* Helper classes should probably be named as specific as possible when possible, to avoid them from growing too big
* Follow the naming tradition of the framework with regard to controllers, e.g. UserController or UserAdministrationController.
* Class properties of ActiveRecord classes will follow the naming of the database, using underscore instead of camel case (and ActiveRecord classes should have ''no'' other properties than those (excluding the database connection injected by the framework))

== Functions ==

Functions are one of the fundamental building blocks of programming, so it's important to get it right.

Functions that are part of a class are called "methods", if you want to be formal.

Different types of functions in PHP:

* Functions (not attached to a class)
* Methods (attached to class)
* Anonymous functions (does not capture scope automatically)
* Short functions (does capture scope automatically)

I'm using "function" as a word for all types of functions in PHP below.

<hr>

=== Size ===

* A function should be short enough to be completely readable on one screen, approx 60 lines at most
* A function should not have too many arguments; if you have five or more, consider making it a class instead
* If a function is growing too big, it might be better to create a class instead or split it into several functions (if both functions have '''common state''', a class might be better, unless you want to pass around '''explicit state''')

=== Contract ===

* A function has a contract with its surrounding environment:
** Pre-condition: What needs to be true before the function is executed
** Post-condition: What will be true after the function has returned
* The function contract can be checked with assertions (internal invariants) or exceptions (outside world); see below
* Another good way is to use unit-tests to make sure the function's contract remains stable through changes
* The first line in the docblock should be one sentence describing the relation between function arguments and its output<br>Example<br><syntaxhighlight lang="php">
/**
* Creates a random password of length $length (defaults to 12)
* @param int $length
* @return string
*/
function createPassword($lenght = 12)

/**
* Creates an HTML language drop down for survey with id $surveyId, marking $selectedLanguage as selected
* @param int $surveyId
* @param string $selectedLanguage
* @return string <select> HTML
*/
function createLanguageDropdown($surveyId, $selectedLanguage)

</syntaxhighlight>

=== Push side-effects up in the stack trace ===

This one is a bit abstract.

First, what is a '''side-effect'''? In short, it's anything that happens in a function that ''is not'' described by the ''relation'' between function arguments and output.

Another way to phrase it is, that a side-effect is anything that is not always the same for the given input to a function; a function without any side-effects will always return the same result if it gets the same input.

'''Examples:'''

<syntaxhighlight lang="php">
// gT accesses the file system and will return different result depending on what's in the translation files
function gT($sToTranslate, $sEscapeMode = 'html', $sLanguage = null);

// If $sText and $sEscapeMode is always the same, quoteText() will always return the same string.
function quoteText($sText, $sEscapeMode = 'html');
</syntaxhighlight>

A function with no side-effects is called '''pure'''. A function that is guaranteed to always return (no exceptions, no errors, no warnings, no division by zero) is called '''total'''.

It's a good thing if functions in a code-base ''either'' have side-effects, ''or'' return a result. Not both. This is called [https://en.wikipedia.org/wiki/Command%E2%80%93query_separation command-query separation].

Examples of side-effects:

* Database or file access
* Echo, or write to stdout or stderr
* Randomization

Why does this matter? Because side-effects make testing harder! '''If you have side-effects, you cannot create unit tests''', ''unless'' those side-effects can be mocked. If not, you need integrity tests with database setup or more. The more side-effects you have in a function, the more mocking is required to unit test it.

So, one solution to this is to move side-effects higher up in the stack trace, that is, move them to the calling code.

'''Example:'''

<syntaxhighlight lang="php">
function getSurveyInfo(int $surveyid, string $languagecode = '', boolean $force = false): array;
</syntaxhighlight>

Since this function takes $surveyid, we know it will probably query the database. Quering the database is a side-effect, and thus it requires a database scaffold for the test (or mocking, but the database connection is not injected, so there's no way to do it). One simple solution is to lift the side-effect out and pass in a Survey object instead:

<syntaxhighlight lang="php">
function getSurveyInfo(Survey $survey, string $languagecode = '', boolean $force = false): array;
</syntaxhighlight>

Much better! The side-effect of calling the database now happens ''before'' the function call. Now we can either mock a Survey object, or make an imitating stub for our test.

Reading the function body, there is in fact another database access, but since this is a relation to the Survey model, it could easily be moved out too. We've just made a function testable! Hooray!

This principle is rephrased in an architectural settings as [https://github.com/kbilsted/Functional-core-imperative-shell/blob/master/README.md functional core, imperative shell]. This architecture helps you get a good ratio between fast unit tests and slower integrity tests.

Moving side-effects up makes sure we can have a healthy ratio between integrity tests with scripted browser, and unit-tests; maybe around 20-80.

=== Function name ===

* The function name should tell you '''what''' it does; docs should tell you '''why''' (if this information is not obvious). '''How''' is described by the code itself (hopefully, but can in some cases be relevant to document).
* Function name can often be '''verb [+ adjective] + noun''', like "createFieldmap", "quoteText", "getRelativePath"
* Prefix with "is" for boolean functions

todo: difference between create, get, fetch, generate, ...

'''Good examples:'''

* createPassword() - One verb, one noun - clear
* isCaptchaEnabled() - Using "is" signifies it returns boolean; clear purpose
* getFullResponseTable() - Verb, adjective, noun - but is "full" needed here? Is there a non-full version of the same function?
* replaceExpressionCodes() - Pretty good, but it's obvious that more information is needed in the docblock to describe what "replace" means, and what an "expression code" is
* fixCKeditorText() - "fix" is a bit vague, but maybe best there is? Pray that docblock contains information!

'''Bad examples:'''

* languageDropdown() - No verb, doesn't tell you what it does
* rmdirr() - Two r's, looks like a typo, but the last "r" actually means "recursive"! Better: rmdir($recursive = false), rmdir or removeFolder.
* CSVUnquote() - Is CSV really the namespace? Why is the verb the second word?
* incompleteAnsFilterState() - One verb, but in the middle, or is "filter state" a noun?; why abbreviate "answer" to "ans"?
* reverseTranslateFieldNames() - Two verbs - did author mean "reverseTranslatedFieldNames"? Or "reverse and translate"? If so, it should be two functions, one for reverse and one for translate
* checkUploadedFileSizeAndRenderJson() - If you have an "and" in the function name, you should consider splitting it into two functions

'''Controversial'''

* gT() - An exception to descriptive function names; since this is used everywhere, the minimal name is motivated; maybe even name it "t()"? Still hard to read for someone who just started? But Yii uses t() too? Other frameworks use double underscore (Wordpress, Laravel) as function name.

<hr>

=== Function filename and namespace ===

If your function has dependencies or side-effects, it should be put into a class instead, in which the dependencies can be injected. Another alternative is to put the dependencies as argument in the function, although this muffles the relationship between input and output. Again, this is to increase testability.

Keep in mind that functions outside classes cannot be mocked, so only use them when you ''know'' you won't need to mock them.

todo, autoloading of functions and folder location

=== Assertions ===

NB: This is not assertions as used in unit-tests, but assertions as used to check invariants in production code.

Assertions can be used for mental checks. They are only used for internal logic - failed assertions are not supposed to be seen by the end user. For interaction with the outside world, like database or browser, exceptions should be used instead.

Assertions can be disabled in production mode and have then no runtime cost (since PHP 7).

'''Example:'''

<syntaxhighlight lang="php">
/**
* Translation helper function
*
* @param string $sToTranslate
* @param string $sEscapeMode Valid values are html (this is the default, js and unescaped)
* @param string $sLanguage
* @return string
*/
function gT($sToTranslate, $sEscapeMode = 'html', $sLanguage = null)
{
assert(is_string($sToTranslate));
assert(strlen($sToTranslate) > 0);
assert($sEscapeMode === 'html' || $sEscapeMode === 'js' || $sEscapeMode === 'unescaped');
return quoteText(Yii::t('', $sToTranslate, array(), null, $sLanguage), $sEscapeMode);
}
</syntaxhighlight>

<hr>

=== Exceptions ===

todo

todo: exception hierarchy

todo: what can be repaired after exception? transaction rollback

* Exceptions are used to check inputs from the outside world (browser, database, file system)
* Don't use exceptions for control flow, only when fatal errors happen that make further execution impossible
* Exceptions should have clear error messages that make them ''actionable'' - there should be a clear "next step" for the user or developer
* Never, ever, do an empty catch-block

==== Alternatives to exceptions ====

Some people consider exceptions being a hidden form of "goto" which confuses the control flow of the program. They propose different other solutions:

* Return a tuple, like <code>[$result, $errorMessage]</code> where $errorMessage is null at success
* Return <code>null</code> at failure
* Tagged union result type (not yet possible in latest PHP)
* Result object

The con being that you have to manually propagate the error, where an exception can happen from anywhere in the stack trace without any other function knowing about it.

=== If-statements ===

If-statements should not be too long or hard to understand. If they are, consider factor out the checks into separate functions.

<syntaxhighlight lang="php">
if ((empty($instance->oOptions->{$attribute}))
|| (
!empty($instance->oOptions->{$attribute})
&& (
$instance->oOptions->{$attribute} === 'inherit'
|| $instance->oOptions->{$attribute} === 'I'
// NB: Do NOT use === here, it won't work with Postgresql.
|| $instance->oOptions->{$attribute} == '-1'
)
)
) {
</syntaxhighlight>

Can be shortened by factoring out method <code>isInherit</code>:

<syntaxhighlight lang="php">
if (empty($instance->options->{$attribute})
|| $this->isInherit($instance-options->{$attribute})) {
}
/**
* Returns true if $value is set to inherit
* @param mixed|null $value
* @return boolean
*/
public function isInherit($value) {
return !empty($value)
&& (
$value === 'inherit'
|| $value === 'I'
// NB: Do NOT use === here, it won't work with Postgresql.
|| $value == '-1'
);
}
</syntaxhighlight>

And one more time by using a variable for the value:

<syntaxhighlight lang="php">
$value = $instance->options->{$attribute};
if (empty($value) || $this->isInherit($value)) {
}
</syntaxhighlight>

More clear, right? "If it's empty or set to inherit, do this and that."

=== Variables ===

Descriptive naming.

* Follow PSR-12 - no underscore, use camelCaseLikeThis
* Variables of ActiveRecord classes can have same name as the class, like "$survey" or "$question"
* Add -s for plural when it's a list of items: "$surveys", "$questions"
* Never include "array" or "list" in variable names - using plural is enough (for lists, not for associative arrays - see below)
* The ''context'' of the function helps with variable naming, e..g "$name" might be fine in a function about questions; this is extra helpful when functions are short!
* When a function is short, it's much easier to figure out variable meaning based on context
* $qid, $gid, and $sid are so established in the code-base that they could be considered OK
* The -data suffix means "blob of stuff", only use it when needed, like with $viewData
* Use $result when baking a return value; add its exact type as @var annotation (worst possible name, acceptable but anything with more meaning is better)

Not so good:

<syntaxhighlight lang="php">
$result = LabelSet::model()->findAll();
</syntaxhighlight>

Better with model name and -s for plural:

<syntaxhighlight lang="php">
$labelSets = LabelSet::model()->findAll();
</syntaxhighlight>

* Do not use Hungarian notation (prefix with "type"), but instead <code>/** @var */</code> annotations - these can be checked automatically and will then be enforced to be correct, unlike Hungarian notation which can "rot"

<syntaxhighlight lang="php">
/** string[] An array of strings with 0-n elements */
$allFields = [];
</syntaxhighlight>

Psalm can infer types if the function documentation is enough. The strictness can be adjusted. Not all variables will need @var annotation, the tool will warn you when it's confused.

* Data that is sent to views as associative arrays will be:

<syntaxhighlight lang="php">
/** @var array Can be basically anything :( Better would be data-transfer objects or more precise notation */
$data = [];
// Maybe more clear as $viewData? Discuss.
</syntaxhighlight>

You can be more precise when you specify which type of array you're writing:

<syntaxhighlight lang="php">
/** @var array<string, string> This means the array key is string, and the array value is also string */
$data = [];
$data['name'] = 'Olle';
$data['occupation'] = 'Developer';
$data['age'] = 38; // ERROR! Value must be string.
</syntaxhighlight>

For more info about array type notation, see the [https://psalm.dev/docs/annotating_code/type_syntax/array_types/ Psalm documentation].

Some smaller examples:

<syntaxhighlight lang="php">
$theme = App()->request->getPost('theme'); // Should be $themeType - $theme looks like a model/AR
$gridid === 'questionthemes-grid'; // Should be $gridId with capital "I", since it's two words in English
$delete = Yii::app()->request->getParam('delete'); // Tuff one - $delete is ok? Thoughts?
$files = json_decode(stripslashes($sJSON), true); // $file is a resource, $files an array of resources, this is $fileData perhaps?
$valid_extensions_array = explode(",", $aAttributes['allowed_filetypes']); // Should be $validExtensionTypes
$language = Yii::app()->session['survey_' . $surveyid]['s_lang']; // TODO: Should this be a value class? Then Language::make(...);
$surveyInfo = getSurveyInfo($surveyId, $language); // OK, BUT should be a separate DTO!
$fieldMap = createFieldMap($survey, 'short', false, false, $language); // Same, make a DTO
$cquestions = array(); // What's "c"? Method name is getChildQuestions and $questions is an argument - better with $childQuestions?
</syntaxhighlight>

Links:

[https://www.approxion.com/capital-offenses-how-to-handle-abbreviations-in-camelcase/ How to Handle Abbreviations in CamelCase]

[https://stackoverflow.com/questions/15526107/acronyms-in-camelcase Acronyms in CamelCase]

=== Looping ===

* The bodies of foreach-loops are often a good candidate to factor out into separate functions.

'''Example:'''

<syntaxhighlight lang="php">
foreach ($questions as $question) {
processQuestion($question);
}
</syntaxhighlight>

Note the variable naming from plural to singular.

* Loop indexing should be named i, j, k etc.

'''Example:'''

<syntaxhighlight lang="php">
for ($i = 0; $i < $length; $i++) {
for ($j = 0; $j < $otherLength; $j++) {
// ...
}
}
</syntaxhighlight>

<hr>

=== Function composition ===

todo, "doThisAndThat" --> "doThis(doThat())"

=== Cases ===

<syntaxhighlight lang="php">
/**
* This function generates an array containing the fieldcode, and matching data in the same order as the activate script
*
* @param Survey $survey Survey ActiveRecord model
* @param string $style 'short' (default) or 'full' - full creates extra information like default values
* @param boolean $force_refresh - Forces to really refresh the array, not just take the session copy
* @param bool|int $questionid Limit to a certain qid only (for question preview) - default is false
* @param string $sLanguage The language to use
* @param array $aDuplicateQIDs
* @return array
*/
function createFieldMap($survey, $style = 'short', $force_refresh = false, $questionid = false, $sLanguage = '', &$aDuplicateQIDs = array())
</syntaxhighlight>

'''Good:'''

* Name is verb and noun
* Each argument is documented (almost)

'''Bad:'''

* Returns "array", which can be anything. A separate class for "Fieldmap" would be better.
* Not clear if it should be "createFieldMap" or "createFieldmap" - is "fieldmap" one word or two?
* Very many boolean arguments. Should probably be a class with methods like <code>$fieldmapCreator->setForceRefresh(true);</code> instead.
* Too long.
* Doesn't elaborate on what "fieldmap" really is, and does not link to any documentation about it.
* Access super-global, which makes it hard to test. Should instead return a data-transfer object, like:<br><syntaxhighlight lang="php">
$_SESSION['fieldmap'] = createFieldMap(...);
</syntaxhighlight>
* Has no test
* Mixes Hungarian notation with non-Hungarian notation in the argument list

== Defensive programming and error handling ==

todo

* '''Fail hard, fail early'''. The earlier the program crashes when something is wrong, the lower is the probability that you'll end up with corrupt data in the database that will later require manual labor to correct.
* Fail with '''actionable information'''
* Check input to functions and throw <code>InvalidArgumentException</code> if it violates the function's pre-conditions
* Use assert for class-internal invariants
* Use assert to make assumptions explicit for the reader

== Documentation ==

=== PHPDoc ===

* All functions must have a proper docblock
* The first line of the docblock should describe the relation between ''all'' the input arguments and the output of the function in a single sentence
* Each parameter must have the correct type
* Don't use <code>array</code> as type if it's a list of object - instead, use <code>[]</code> like so: <code>Survey[]</code> for a list of surveys

=== Technical documentation ===

todo, UML, scenarios, use-cases

== The PHP of yesterday ==

Old idioms and habits that should be abandoned.

* Don't use associative arrays, almost never. Data-transfer objects have multiple benefits: they are clearly structured, can be documented, can enforce invariants. There's ''no'' performance overhead of objects compared to arrays in modern PHP.
* Objects are already passed by reference; arrays are value types
* Use <code>[]</code> instead of <code>array()</code>
* Hungarian notation was useful before static analysis existed for PHP. These days it's better to use something that can be checked automatically: docblock @param and inline @var annotations.

== The PHP of tomorrow ==

todo

Union tags

Short functions

Match expressions

== Security ==

todo

XSS

Database injection

Permissions and roles

== Performance ==

todo

Loading too many rows into PHP models

== Testing ==

todo

QA

PHPUnit

TDD

Mocks, can't mock functions, static methods, mocking as a DSL, PHPUnit mocking tools

Pure functions, referential transparency, side-effects

Unit, functional, integration

Don't test the framework; don't test PHP

Makes sure the function or class lives up to its specification; make sure it will ''always'' live up to its specification, even in the future, to avoid regressions.

== Static analysis ==

<code>php -l</code>, CodeSniffer, Mess Detector, Psalm

== Database design ==

todo

== JavaScript ==

todo

classes, functions, components, tests

== CSS ==

todo

== HTML ==

todo

== Feedback ==

=== "Why do I have to refactor code that works?" ===

todo, Sadly, it's not enough for the code to live up to the current specification and requirements, it must also be protected against future changes, regressions. Adding tests is the best way for this. Lots of people might read and change the LimeSurvey code the next 5-10 years. The test suite creates a security layer to make sure the specification is fulfilled even as the code changes.

Tests are not a magical solution, however. It does not protect us against other degradation of the code quality, like classes gaining too much responsibility (too many methods, unrelated methods, too many properties).

=== "What's the correct ratio between integrity tests and unit tests?" ===

todo, Don't know. Different pros and cons.

* Unit-test can be run in parallel and are faster
* Unit-tests don't need setup and teardown

Cons of unit-tests is that they need a bigger effort on the side of the developer to make them possible, for example injecting the dependencies properly to enable mocking, or lifting side-effects up in the stack trace.

=== How to disagree ===

All rules can be broken. To break a rule, you should reason in terms of risk and the assumptions used in this guide.

'''Assumptions:'''

# Regressions are the biggest technical risk for LimeSurvey the last five years (2021)
# Automated tests are the best risk mitigation technique against regressions

'''Possible disagreement:'''

# A certain piece of code has very low ''probability'' of regressions (maybe we "know" no one else will every touch or change it?)
# Regression in a certain piece of code would have very low ''impact''

== Architectural Decision Records ==

todo

https://adr.github.io/

== Resources ==

todo

Books, links, videos

Regression and unit tests

2021-05-10T09:49:16Z

Olle:

{{Alert|title=Warning|text=NEVER run tests on a production system. The tests WILL delete and modify the <code>limesurvey</code> database as well as the <code>config.php</code> file. Always do a backup of important data before running the tests.}}

{{Hint|Text=Always make sure new code follows the PSR-12 standard for PHP. Use [https://github.com/squizlabs/PHP_CodeSniffer codesniffer] and [https://phpmd.org/ mess detector] to catch common bugs and style fixes in your code.}}
{{Hint|Text=Every time you discover a new bug, you should add a regression test to make sure it does not appear again.}}

Since LimeSurvey 2.65.6 you have the possibility to add unit tests to LimeSurvey.

Since LImeSurvey 3.0.0, we use Selenium, headless Firefox (geckodriver) and Facebook web driver to test with the browser from PHPUnit.

== Introduction ==

An extensive test suite will give the programmer a better sense of security, and allow him/her to make bigger re-factorizations without risking the soundness of the codebase. In an ideal world, a regression test is added every time a new bug is discovered. That way you make sure you never have to fix the same bug twice.

You can run the tests locally if you want, or you can setup a docker container that mimics the Travis CI environment. Alternatively, you can visit Travis CI after you've pushed to github to make sure your commits didn't break anything. If you think Travis is falsely reporting a bug, you should contact the person who constructed the test.

== Installation ==

=== Linux ===

(All commands below are executed in the LimeSurvey web root folder.)

The browser tests uses Firefox, so you have to install it before running.

# A good idea is to clear the database and make a fresh install using the command-line (backup any data you want to save first):<syntaxhighlight lang="sql">DROP DATABASE limesurvey; CREATE DATABASE limesurvey</syntaxhighlight><syntaxhighlight lang="bash">$ DBENGINE=INNODB php application/commands/console.php install admin password TravisLS no@email.com verbose</syntaxhighlight>Make sure your config.php has the correct database credentials.
# To enable unit testing, you have to issue the command<br/><syntaxhighlight lang="bash">
$ touch enabletests</syntaxhighlight>
# To install Facebook web driver and PHPUnit, run<syntaxhighlight lang="bash">$ composer install</syntaxhighlight>
# <strike>Install [https://nodejs.org/en/ node] (needed for EM tests).</strike> Not used right now.
# Download Selenium and the geckodriver:<syntaxhighlight lang="bash">$ wget "https://selenium-release.storage.googleapis.com/3.7/selenium-server-standalone-3.7.1.jar"</syntaxhighlight><syntaxhighlight lang="bash">$ wget "https://github.com/mozilla/geckodriver/releases/download/v0.23.0/geckodriver-v0.23.0-linux64.tar.gz"</syntaxhighlight><syntaxhighlight lang="bash">$ tar xvzf geckodriver-v0.23.0-linux64.tar.gz</syntaxhighlight>
# Make sure you have Java installed, and start Selenium in a separate terminal:<syntaxhighlight lang="bash">$ java -jar selenium-server-standalone-3.7.1.jar -enablePassThrough false</syntaxhighlight>If you want to use the headless browser, prepend with:<syntaxhighlight lang="bash">MOZ_HEADLESS=1</syntaxhighlight>
# Run tests with <syntaxhighlight lang="bash">$ DOMAIN=<local domain> ./third_party/bin/phpunit </syntaxhighlight>where "<local domain>" is replaced with your localhost domain, e.g. "localhost" or "localhost/limesurvey".

=== Windows ===
==== Vagrant Box Setup ====
# Install [https://www.virtualbox.org/ Virtualbox]
# Install [https://www.vagrantup.com/downloads.html Vagrant]
# If you have used Docker before and/or have Hyper-V activated you have to disable it, Virtualbox and Hyper-V can not run simultaneously. You can do this by executing following in powershell. <syntaxhighlight>bcdedit /set hypervisorlaunchtype off</syntaxhighlight> If the command is denied make sure you run your powershell as system administrator: Press Windows+R to open the “Run” box. Type “powershell” into the box and then press Ctrl+Shift+Enter to run the command as an administrator.
# Clone the Vagrant Box into your desired folder, the Vagrant Box can be found [https://github.com/LimeSurvey/LimeSurvey-Vagrant here]<syntaxhighlight lang="cmd">git clone https://github.com/LimeSurvey/LimeSurvey-Vagrant.git YOURFOLDERNAME</syntaxhighlight>
# Modify the file 'Vagrantfile' in the root folder and edit the IP address if it is already taken and set the PHP version to your requirements (usually 5.6 or 7.4). If you need other versions, then please look at the README file in the [https://github.com/LimeSurvey/LimeSurvey-Vagrant Repository]. There are other settings like the SQL and Xdebug settings that can be customized to your needs.<syntaxhighlight>
#Custom variable for installation
ip = "10.0.0.10"
#php setup
phpversion = "7.4"
#mysql setup
mysqlRootPass = "password"
mysqlDBName = "limesurvey"
mySqlDBUser = "limesurvey"
mySqlDBPassword = "password"
#postgres setup
postgresDB = "limesurvey"
postgresPassword = "password"
#limesurvey setup
limeSurveyBranch = "master"
#IDE KEY for Xdebug
ideKey = "VSCODE"</syntaxhighlight>
# Remove the # before<syntaxhighlight>
#enable this line on windows machine (Optional).
#vb.customize ["modifyvm", :id, "--natdnshostresolver1", "on"]
</syntaxhighlight><syntaxhighlight>
vb.customize ["modifyvm", :id, "--natdnshostresolver1", "on"]
</syntaxhighlight>
# Set the branch you to checkout during Setup, by default it is set to the "master" branch <syntaxhighlight>limeSurveyBranch = "master"</syntaxhighlight>
# Start vagrant in the root Folder where the Vagranfile is located:<syntaxhighlight>
vagrant up</syntaxhighlight>Be patient, this will take 10-15 minutes on the first start because various resources need to be downloaded and installed.
# You can now access your Installation by typing the hostname set in the Vagrantfile or using the ip address and appending a "/". By default this is set to "limesurvey". Follow the the normal Limesurvey Installation process. The Database username is "limesurvey" and password is "password" unless changed.
# Install your desired PHP version on your PC, not in the Vagrant Box
# Run composer installation inside your local Installation Folder in Windows "VAGRANTFOLDER/INSTALLATIONFOLDER" <syntaxhighlight>
composer install</syntaxhighlight>
# Download [https://selenium-release.storage.googleapis.com/3.7/selenium-server-standalone-3.7.1.jar Selenium] and the [https://github.com/mozilla/geckodriver/releases/download/v0.23.0/geckodriver-v0.23.0-win64.zip geckodriver]. Extract the geckodriver.exe and place it inside the installation folder and place the selenium jar file at the same location.
# Create a file named "enabletests" in the installation root folder.
# Make sure you have Java installed, and start Selenium in a separate terminal:<syntaxhighlight lang="bash">java -jar selenium-server-standalone-3.7.1.jar -enablePassThrough false</syntaxhighlight>If you want to use the headless browser make an environment variable called "MOZ_HEADLESS" and set it to 1, in the powershell:<syntaxhighlight lang="bash">$Env:MOZ_HEADLESS = 1</syntaxhighlight> This will only be set in the current powershell window. If you want to set it permanently, open the environment variables in windows and create the variable. You will have to reload the powershell window for the settings to take effect.
# To run tests log in to your Vagrantbox from the vagrant folder and navigate to the installation folder <syntaxhighlight>
vagrant ssh
# by default the installation folder is mapped to /var/www
cd /var/www/
</syntaxhighlight>
# Now you can run tests! All tests are located inside the "tests" folder. To run a specific test:<syntaxhighlight>DOMAIN=localhost ./third_party/bin/phpunit ./tests/PATH/TO/THE/FILE</syntaxhighlight>Example: <syntaxhighlight>DOMAIN=localhost ./third_party/bin/phpunit ./tests/functional/backend/AdminViewsTest.php</syntaxhighlight> If you should have permission issues set the synced_folder fmode option in the Vagrantfile to "fmode=777". For the new permission setting to work you must shutdown the vagrant machine and start it up again. Type <syntaxhighlight>
sudo shutdown now
</syntaxhighlight> in the SSH console and after the machine has shut down, start it up again using <syntaxhighlight>vagrant up</syntaxhighlight> as shown above.

=== Docker Setup ===
Install [https://docs.docker.com/docker-for-windows/install/ docker on windows].

Open your command prompt and enter

$ docker run --name travis-debug -dit travisci/ci-garnet:packer-1512502276-986baf0 /sbin/init

[[Using PHP from docker]]

=== Mac ===

TODO

== Usage ==

After all steps for the installation are completed, you should be able to write

<syntaxhighlight lang="html">
$ PASSWORD=adminpassword DOMAIN=your_limesurvey_domain phpunit
</syntaxhighlight>

in the LimeSurvey root folder to run the tests.

If LimeSurvey is installed on your web root, use "DOMAIN=localhost".

This is an example of the output:

<syntaxhighlight lang="html">
$ phpunit
PHPUnit 5.6.2 by Sebastian Bergmann and contributors.

.... 4 / 4 (100%)

Time: 713 ms, Memory: 14.00MB

OK (4 tests, 24 assertions)
</syntaxhighlight>

You can get some more information if you use the switch <code lang="html">--testdox</code>:

<syntaxhighlight lang="html">
$ phpunit --testdox
PHPUnit 5.6.2 by Sebastian Bergmann and contributors.

ls\tests\DateTimeForwardBack
[x] Q 1

ls\tests\DateTime
[x] Wrong input
[x] Correct date format
[x] Q 1
</syntaxhighlight>

During testing, you might want to use <code lang="html">--group <test group></code> and/or <code lang="html">--stop-on-failure</code>.

== What can be tested? ==

Right now, there are tests for the expression manager, qanda and updatedb helper. The Selenium driver makes it also possible to test the full browser experience, including JavaScript.

== What should be tested? ==

Everything that can be reported as a bug should be tested, but especially critical is of course the relation between user input and database, that is, that the correct answer is saved.

== Adding a test ==

First of all, make sure to head over to the [https://phpunit.de/ phpunit] web site and read the introduction.

When done with that, I will assume you want to add a new test for a question type. Tests for questions are stored in folder <code lang="html">tests/questions</code>.

You should create a minimal survey to reproduce your bug. Export it as an lss file and put it in <code lang="html">tests/data/surveys</code>. Then create a class for your test. Name the file the same as the class, like "DateTimeForwardBackTest.php". The class name must end with "Test", so phpunit can find it.

Inside the class you might want to add code to import and delete the survey. I usually do this class-wide, which means that the survey gets imported when the class is loaded and then deleted when all tests in the class is done (whether failed or successfully).

The static methods <code lang="html">setupBeforeClass</code> and <code lang="html">teardownAfterClass</code> is used to setup and teardown the test fixture, respectively. You can read more about fixtures in the [https://phpunit.de/manual/current/en/fixtures.html phpunit manual].

Let's list what we know so far:

<syntaxhighlight lang="php">
namespace ls\tests;

use PHPUnit\Framework\TestCase;

/**
* @since 2017-06-16
* @author Olle Haerstedt
*/
class DateTimeDefaultAnswerExpressionTest extends \TestCase
{
public static function setupBeforeClass()
{
// Init stuff
}

public static function teardownAfterClass()
{
// Tear down what you setup before.
}
}
</syntaxhighlight>

To test with Selenium and the Facebook web driver, check out the [https://github.com/facebook/php-webdriver/wiki wiki page] on github.

TODO

== Travis ==

All tests are run automatically after each commit using Travis continuous integration. https://travis-ci.org/LimeSurvey/LimeSurvey/

[[Category:Development]]

Code quality guide

2021-05-05T09:20:01Z

Olle: /* Types of classes */

DRAFT

== Prologue ==

# '''Be risk aware'''. Too good code can be a business risk (slow to write, maybe over-designed). Too sloppy code can also be a business risk (hard to maintain and understand). You have to find a balance that is adapted to the current situation and risk analysis, in which code quality becomes a '''risk mitigation''' technique among others.
# '''Be humble'''. LimeSurvey was made by developers from all over the world, with different age, education and experience. Your code might be read by a completely different team ten years from now, in the same way you are now reading code by developers that no longer work with us, but which work pays our rent.
# '''Performance matters sometimes''', and shouldn't be disregarded completely. In particular, database queries using the ORM and ActiveRecord can be problematic. Some surveys have thousands of questions and hundreds of thousands of responses. Fast response time is also important for a fluid user experience.
# '''It's harder to read code than to write code'''. Don't choose patterns that are easy or fast to write, but that are easy to read.
# Make your code '''communicate intent'''.
# It's easy to forget '''cross-cutting concerns''' like translation and security. Keep a mental note.
# '''Stress affects code quality''' and your risk behaviour. If your stress level is too high to write code with proper quality, take a step back and discuss it with your boss, or you'll push problems to the future.

== Quality ==

The purpose of this guide is to increase the quality of the LimeSurvey code-base. What is quality? Which aspects of quality can be measured? Which kind of company culture gives rise to appropriate code quality?

It's usually easier to get along what is "bad" code than what's "best" code. Blacklist instead of whitelist?

Quality attributes related to code quality:

* Readability
* Testability
* Maintainability
* Performance
* Security
* Reliability

Can not increase all at the same time - performance vs readability.

It's better to avoid emotional language when describing code quality, like "clean" or "dirty". Be precise, objective and suggest solutions.

Idiomatic code is more readable than non-idiomatic code. What's idiomatic depends on which context or domain you work in. We work in PHP and web application development, and have other idioms than in, say, functional or hardware-close programming.

Some code are "hot spots" - changed often. Those parts should require higher quality than other code.

== Risk ==

todo

data loss as most severe risk for LS

usability a business risk - hard to use or understand, people will choose another tool

risks relevant when fixing bugs

risks relevant when adding new features (lack of testing, wrong requirements, scope creep)

risks relevant when refactoring (regressions)

unit tests and QA as risk mitigation

partial deployment, alpha/beta/rc, risk communication

software rot, design pattern rot/grime, software evolution

rot = non-pattern related code

testing by community, bug fixing by community

== Modules ==

There's no inherit module functionality in PHP, but Yii has a module system. Libraries can be seen as a module system.

Examples of implicit modules in LimeSurvey:

* Front-end (survey taking)
* Back-end (survey design)
* Survey theme editing
* Expression manager
* Plugin system

In the future, they need to be separated and implemented more clearly as whatever Yii 3 module system is in use.

Some data models are common for all modules, e.g. surveys and users. Can have a "Common" module for such data.

todo, relation to Yii config system

== Classes ==

* Avoid empty OOP ceremony, like defining getters and setters for all properties. Might as well make them public, ''unless'' they have invariants that need to be upheld, e.g. "this number is always between 1 and 10" or "this string is maximum length 20".
* Almost always avoid static methods. They cannot be mocked. One exception is (possibly) factory methods (Foo::make(...)).
* Inject all dependencies. This will make sure the class can be unit-tested (unit-tests have several benefits over integrity tests - they can be run in parallel and don't require any setup and teardown)
* A second way to achieve testability is to factor out the methods that access the dependencies

todo, state vs behaviour, state vs dependencies

=== OOP design ===

Start from top-down, with domain, behaviour, interaction between objects, database design, pseudo-code if needed. Can also include scenarios, use-cases and UML diagrams.

Object reification - not only domain models, but also domain actions, relations and activities can be objects, e.g. a class ActivateSurvey or ExportSurvey.

Hierarchy depth should be kept reasonable shallow to avoid conflicts between methods, spooky action at a distance. Compare with Yii 3, where controllers no longer inherit anything.

Some people advocate for composition instead of inheritance. Lots of blog posts available for more info.

Multiple inheritance is done with traits in PHP. Use-case: ActiveRecords that support encryption, but not all.

=== Design pattern grime and software evolution ===

Design rot after time - how to keep it tight? (Grime.)

todo

design pattern rot --> lose behaviour relevant for pattern (active record without db connection)

design patter grime --> add behaviour irrelevant for pattern (active record that's also a singleton)

=== State ===

Heuristics to consider but not follow slavishly.

Keep a clear separation between classes with state and classes with no state.

Classes with state should not have dependencies with IO (it's OK to depend on classes in the same application layer, e.g. other DTO classes), and vice versa. ActiveRecord is an example which violates this principle.

class Survey
// Confusion - first params are domain state, last a resource
__construct(id, language, dbConnection)

If a method does not call "this", should it instead be outside the class? A separate class or function, maybe.

todo, elaborate

=== Types of classes ===

Different categories of classes:

* Entity (domain class; has state and validation behaviour)
* Resource (database connection, file, curl, logger; state is in the resource (open, closed))
* Repository classes (database interaction, like splitting ActiveRecord in two parts: Entity class and database interaction)
* DAO, data access object (similar to resource)
* Builders (e.g. query builder, HTML message builder)
* Data-transfer object (no behaviour; pass to views to have better documentation and intent than associative arrays)
* Value classes (e.g. Email address to wrap email string around)
* Command object (e.g. SurveyActivator)
* Helper (no state; e.g. QuestionAttributeHelper to bake attributes into different formats used by the views)
* Wrapper

todo, immutability, possible with private properties that are set in the constructor,

todo: command-query separation for classes?

todo: dependencies between layers, dependencies to the framework

todo, pure vs effectful classes

=== Types of classes in LimeSurvey ===

* ActiveRecord, used to communicate with the database, and should not do ''anything'' else
* Controllers, used for glue code; should not contain business-logic (also CLI controllers)
* Helper functions (not classes, yet...), should be short and obey command-query separation (TODO: Long functions should be separated into command objects or service classes); todo: should not have any dependencies?
* Helper classes, similar to helper functions but have dependencies that need to be mocked during tests; should not have any state
* Service classes, contains logic related to a clear and separate task, like create or import survey
* Question render classes, contains logic related to how questions are rendered (TODO: Need better separation between state and logic and more clear design); similar to widgets
* Plugin classes, using the plugin event system
* Widgets, containing HTML logic for custom HTML widgets
* HTML helpers (Yii)
* Customizations to the Yii framework by inheritance
* Unit and functional test classes

A couple of classes contain only data, like LsDefaultDataSet.

todo, no difference between state property and dependency property in OOP

=== What is "glue code"? ===

todo

Putting the pieces together, e.g. service class A need data from model B, fetch it and run.

todo, add example

=== "Where do I cut?" ===

Separation of concerns, but which concerns and which type of separation? Command-query (function core, imperative shell) is one type of separation. Other separation between layers, e.g. logic layer and data persistency layer (similar in thought).

Other separation, that one class should have a clear purpose. A design pattern should only implement ''one'' pattern, not multiple, and not half a pattern.

There's a problem with "helper" or "manager" classes that they can grow indefinitely, but might be better than nothing. Example when moving business logic out of ActiveRecord class to a helper class it can sometimes hard to be more specific than "helper".

=== Size ===

A class should have a single and clear purpose; compare with [https://en.wikipedia.org/wiki/SOLID SOLID].

=== Class name ===

* ActiveRecord classes are named after the database table they are bound to, but with singular instead of plural. E.g. table "lime_users" have model "User".
* Command classes are named after what they ''do'' and imperatively, e.g. CreateSurvey
* Helper classes should probably be named as specific as possible when possible, to avoid them from growing too big
* Follow the naming tradition of the framework with regard to controllers, e.g. UserController or UserAdministrationController.
* Class properties of ActiveRecord classes will follow the naming of the database, using underscore instead of camel case (and ActiveRecord classes should have ''no'' other properties than those (excluding the database connection injected by the framework))

== Functions ==

Functions are one of the fundamental building blocks of programming, so it's important to get it right.

Functions that are part of a class are called "methods", if you want to be formal.

Different types of functions in PHP:

* Functions (not attached to a class)
* Methods (attached to class)
* Anonymous functions (does not capture scope automatically)
* Short functions (does capture scope automatically)

I'm using "function" as a word for all types of functions in PHP below.

<hr>

=== Size ===

* A function should be short enough to be completely readable on one screen, approx 60 lines at most
* A function should not have too many arguments; if you have five or more, consider making it a class instead
* If a function is growing too big, it might be better to create a class instead or split it into several functions (if both functions have '''common state''', a class might be better, unless you want to pass around '''explicit state''')

=== Contract ===

* A function has a contract with its surrounding environment:
** Pre-condition: What needs to be true before the function is executed
** Post-condition: What will be true after the function has returned
* The function contract can be checked with assertions (internal invariants) or exceptions (outside world); see below
* Another good way is to use unit-tests to make sure the function's contract remains stable through changes
* The first line in the docblock should be one sentence describing the relation between function arguments and its output<br>Example<br><syntaxhighlight lang="php">
/**
* Creates a random password of length $length (defaults to 12)
* @param int $length
* @return string
*/
function createPassword($lenght = 12)

/**
* Creates an HTML language drop down for survey with id $surveyId, marking $selectedLanguage as selected
* @param int $surveyId
* @param string $selectedLanguage
* @return string <select> HTML
*/
function createLanguageDropdown($surveyId, $selectedLanguage)

</syntaxhighlight>

=== Push side-effects up in the stack trace ===

This one is a bit abstract.

First, what is a '''side-effect'''? In short, it's anything that happens in a function that ''is not'' described by the ''relation'' between function arguments and output.

Another way to phrase it is, that a side-effect is anything that is not always the same for the given input to a function; a function without any side-effects will always return the same result if it gets the same input.

'''Examples:'''

<syntaxhighlight lang="php">
// gT accesses the file system and will return different result depending on what's in the translation files
function gT($sToTranslate, $sEscapeMode = 'html', $sLanguage = null);

// If $sText and $sEscapeMode is always the same, quoteText() will always return the same string.
function quoteText($sText, $sEscapeMode = 'html');
</syntaxhighlight>

A function with no side-effects is called '''pure'''. A function that is guaranteed to always return (no exceptions, no errors, no warnings, no division by zero) is called '''total'''.

It's a good thing if functions in a code-base ''either'' have side-effects, ''or'' return a result. Not both. This is called [https://en.wikipedia.org/wiki/Command%E2%80%93query_separation command-query separation].

Examples of side-effects:

* Database or file access
* Echo, or write to stdout or stderr
* Randomization

Why does this matter? Because side-effects make testing harder! '''If you have side-effects, you cannot create unit tests''', ''unless'' those side-effects can be mocked. If not, you need integrity tests with database setup or more. The more side-effects you have in a function, the more mocking is required to unit test it.

So, one solution to this is to move side-effects higher up in the stack trace, that is, move them to the calling code.

'''Example:'''

<syntaxhighlight lang="php">
function getSurveyInfo(int $surveyid, string $languagecode = '', boolean $force = false): array;
</syntaxhighlight>

Since this function takes $surveyid, we know it will probably query the database. Quering the database is a side-effect, and thus it requires a database scaffold for the test (or mocking, but the database connection is not injected, so there's no way to do it). One simple solution is to lift the side-effect out and pass in a Survey object instead:

<syntaxhighlight lang="php">
function getSurveyInfo(Survey $survey, string $languagecode = '', boolean $force = false): array;
</syntaxhighlight>

Much better! The side-effect of calling the database now happens ''before'' the function call. Now we can either mock a Survey object, or make an imitating stub for our test.

Reading the function body, there is in fact another database access, but since this is a relation to the Survey model, it could easily be moved out too. We've just made a function testable! Hooray!

This principle is rephrased in an architectural settings as [https://github.com/kbilsted/Functional-core-imperative-shell/blob/master/README.md functional core, imperative shell]. This architecture helps you get a good ratio between fast unit tests and slower integrity tests.

Moving side-effects up makes sure we can have a healthy ratio between integrity tests with scripted browser, and unit-tests; maybe around 20-80.

=== Function name ===

* The function name should tell you '''what''' it does; docs should tell you '''why''' (if this information is not obvious). '''How''' is described by the code itself (hopefully, but can in some cases be relevant to document).
* Function name can often be '''verb [+ adjective] + noun''', like "createFieldmap", "quoteText", "getRelativePath"
* Prefix with "is" for boolean functions

todo: difference between create, get, fetch, generate, ...

'''Good examples:'''

* createPassword() - One verb, one noun - clear
* isCaptchaEnabled() - Using "is" signifies it returns boolean; clear purpose
* getFullResponseTable() - Verb, adjective, noun - but is "full" needed here? Is there a non-full version of the same function?
* replaceExpressionCodes() - Pretty good, but it's obvious that more information is needed in the docblock to describe what "replace" means, and what an "expression code" is
* fixCKeditorText() - "fix" is a bit vague, but maybe best there is? Pray that docblock contains information!

'''Bad examples:'''

* languageDropdown() - No verb, doesn't tell you what it does
* rmdirr() - Two r's, looks like a typo, but the last "r" actually means "recursive"! Better: rmdir($recursive = false), rmdir or removeFolder.
* CSVUnquote() - Is CSV really the namespace? Why is the verb the second word?
* incompleteAnsFilterState() - One verb, but in the middle, or is "filter state" a noun?; why abbreviate "answer" to "ans"?
* reverseTranslateFieldNames() - Two verbs - did author mean "reverseTranslatedFieldNames"? Or "reverse and translate"? If so, it should be two functions, one for reverse and one for translate
* checkUploadedFileSizeAndRenderJson() - If you have an "and" in the function name, you should consider splitting it into two functions

'''Controversial'''

* gT() - An exception to descriptive function names; since this is used everywhere, the minimal name is motivated; maybe even name it "t()"? Still hard to read for someone who just started? But Yii uses t() too? Other frameworks use double underscore (Wordpress, Laravel) as function name.

<hr>

=== Function filename and namespace ===

If your function has dependencies or side-effects, it should be put into a class instead, in which the dependencies can be injected. Another alternative is to put the dependencies as argument in the function, although this muffles the relationship between input and output. Again, this is to increase testability.

Keep in mind that functions outside classes cannot be mocked, so only use them when you ''know'' you won't need to mock them.

todo, autoloading of functions and folder location

=== Assertions ===

NB: This is not assertions as used in unit-tests, but assertions as used to check invariants in production code.

Assertions can be used for mental checks. They are only used for internal logic - failed assertions are not supposed to be seen by the end user. For interaction with the outside world, like database or browser, exceptions should be used instead.

Assertions can be disabled in production mode and have then no runtime cost (since PHP 7).

'''Example:'''

<syntaxhighlight lang="php">
/**
* Translation helper function
*
* @param string $sToTranslate
* @param string $sEscapeMode Valid values are html (this is the default, js and unescaped)
* @param string $sLanguage
* @return string
*/
function gT($sToTranslate, $sEscapeMode = 'html', $sLanguage = null)
{
assert(is_string($sToTranslate));
assert(strlen($sToTranslate) > 0);
assert($sEscapeMode === 'html' || $sEscapeMode === 'js' || $sEscapeMode === 'unescaped');
return quoteText(Yii::t('', $sToTranslate, array(), null, $sLanguage), $sEscapeMode);
}
</syntaxhighlight>

<hr>

=== Exceptions ===

todo

todo: exception hierarchy

todo: what can be repaired after exception? transaction rollback

* Exceptions are used to check inputs from the outside world (browser, database, file system)
* Don't use exceptions for control flow, only when fatal errors happen that make further execution impossible
* Exceptions should have clear error messages that make them ''actionable'' - there should be a clear "next step" for the user or developer
* Never, ever, do an empty catch-block

==== Alternatives to exceptions ====

Some people consider exceptions being a hidden form of "goto" which confuses the control flow of the program. They propose different other solutions:

* Return a tuple, like <code>[$result, $errorMessage]</code> where $errorMessage is null at success
* Return <code>null</code> at failure
* Tagged union result type (not yet possible in latest PHP)
* Result object

The con being that you have to manually propagate the error, where an exception can happen from anywhere in the stack trace without any other function knowing about it.

=== If-statements ===

If-statements should not be too long or hard to understand. If they are, consider factor out the checks into separate functions.

<syntaxhighlight lang="php">
if ((empty($instance->oOptions->{$attribute}))
|| (
!empty($instance->oOptions->{$attribute})
&& (
$instance->oOptions->{$attribute} === 'inherit'
|| $instance->oOptions->{$attribute} === 'I'
// NB: Do NOT use === here, it won't work with Postgresql.
|| $instance->oOptions->{$attribute} == '-1'
)
)
) {
</syntaxhighlight>

Can be shortened by factoring out method <code>isInherit</code>:

<syntaxhighlight lang="php">
if (empty($instance->options->{$attribute})
|| $this->isInherit($instance-options->{$attribute})) {
}
/**
* Returns true if $value is set to inherit
* @param mixed|null $value
* @return boolean
*/
public function isInherit($value) {
return !empty($value)
&& (
$value === 'inherit'
|| $value === 'I'
// NB: Do NOT use === here, it won't work with Postgresql.
|| $value == '-1'
);
}
</syntaxhighlight>

And one more time by using a variable for the value:

<syntaxhighlight lang="php">
$value = $instance->options->{$attribute};
if (empty($value) || $this->isInherit($value)) {
}
</syntaxhighlight>

More clear, right? "If it's empty or set to inherit, do this and that."

=== Variables ===

Descriptive naming.

* Follow PSR-12 - no underscore, use camelCaseLikeThis
* Variables of ActiveRecord classes can have same name as the class, like "$survey" or "$question"
* Add -s for plural when it's a list of items: "$surveys", "$questions"
* Never include "array" or "list" in variable names - using plural is enough (for lists, not for associative arrays - see below)
* The ''context'' of the function helps with variable naming, e..g "$name" might be fine in a function about questions; this is extra helpful when functions are short!
* When a function is short, it's much easier to figure out variable meaning based on context
* $qid, $gid, and $sid are so established in the code-base that they could be considered OK
* The -data suffix means "blob of stuff", only use it when needed, like with $viewData
* Use $result when baking a return value; add its exact type as @var annotation (worst possible name, acceptable but anything with more meaning is better)

Not so good:

<syntaxhighlight lang="php">
$result = LabelSet::model()->findAll();
</syntaxhighlight>

Better with model name and -s for plural:

<syntaxhighlight lang="php">
$labelSets = LabelSet::model()->findAll();
</syntaxhighlight>

* Do not use Hungarian notation (prefix with "type"), but instead <code>/** @var */</code> annotations - these can be checked automatically and will then be enforced to be correct, unlike Hungarian notation which can "rot"

<syntaxhighlight lang="php">
/** string[] An array of strings with 0-n elements */
$allFields = [];
</syntaxhighlight>

Psalm can infer types if the function documentation is enough. The strictness can be adjusted. Not all variables will need @var annotation, the tool will warn you when it's confused.

* Data that is sent to views as associative arrays will be:

<syntaxhighlight lang="php">
/** @var array Can be basically anything :( Better would be data-transfer objects or more precise notation */
$data = [];
// Maybe more clear as $viewData? Discuss.
</syntaxhighlight>

You can be more precise when you specify which type of array you're writing:

<syntaxhighlight lang="php">
/** @var array<string, string> This means the array key is string, and the array value is also string */
$data = [];
$data['name'] = 'Olle';
$data['occupation'] = 'Developer';
$data['age'] = 38; // ERROR! Value must be string.
</syntaxhighlight>

For more info about array type notation, see the [https://psalm.dev/docs/annotating_code/type_syntax/array_types/ Psalm documentation].

Some smaller examples:

<syntaxhighlight lang="php">
$theme = App()->request->getPost('theme'); // Should be $themeType - $theme looks like a model/AR
$gridid === 'questionthemes-grid'; // Should be $gridId with capital "I", since it's two words in English
$delete = Yii::app()->request->getParam('delete'); // Tuff one - $delete is ok? Thoughts?
$files = json_decode(stripslashes($sJSON), true); // $file is a resource, $files an array of resources, this is $fileData perhaps?
$valid_extensions_array = explode(",", $aAttributes['allowed_filetypes']); // Should be $validExtensionTypes
$language = Yii::app()->session['survey_' . $surveyid]['s_lang']; // TODO: Should this be a value class? Then Language::make(...);
$surveyInfo = getSurveyInfo($surveyId, $language); // OK, BUT should be a separate DTO!
$fieldMap = createFieldMap($survey, 'short', false, false, $language); // Same, make a DTO
$cquestions = array(); // What's "c"? Method name is getChildQuestions and $questions is an argument - better with $childQuestions?
</syntaxhighlight>

Links:

[https://www.approxion.com/capital-offenses-how-to-handle-abbreviations-in-camelcase/ How to Handle Abbreviations in CamelCase]

[https://stackoverflow.com/questions/15526107/acronyms-in-camelcase Acronyms in CamelCase]

=== Looping ===

* The bodies of foreach-loops are often a good candidate to factor out into separate functions.

'''Example:'''

<syntaxhighlight lang="php">
foreach ($questions as $question) {
processQuestion($question);
}
</syntaxhighlight>

Note the variable naming from plural to singular.

* Loop indexing should be named i, j, k etc.

'''Example:'''

<syntaxhighlight lang="php">
for ($i = 0; $i < $length; $i++) {
for ($j = 0; $j < $otherLength; $j++) {
// ...
}
}
</syntaxhighlight>

<hr>

=== Function composition ===

todo, "doThisAndThat" --> "doThis(doThat())"

=== Cases ===

<syntaxhighlight lang="php">
/**
* This function generates an array containing the fieldcode, and matching data in the same order as the activate script
*
* @param Survey $survey Survey ActiveRecord model
* @param string $style 'short' (default) or 'full' - full creates extra information like default values
* @param boolean $force_refresh - Forces to really refresh the array, not just take the session copy
* @param bool|int $questionid Limit to a certain qid only (for question preview) - default is false
* @param string $sLanguage The language to use
* @param array $aDuplicateQIDs
* @return array
*/
function createFieldMap($survey, $style = 'short', $force_refresh = false, $questionid = false, $sLanguage = '', &$aDuplicateQIDs = array())
</syntaxhighlight>

'''Good:'''

* Name is verb and noun
* Each argument is documented (almost)

'''Bad:'''

* Returns "array", which can be anything. A separate class for "Fieldmap" would be better.
* Not clear if it should be "createFieldMap" or "createFieldmap" - is "fieldmap" one word or two?
* Very many boolean arguments. Should probably be a class with methods like <code>$fieldmapCreator->setForceRefresh(true);</code> instead.
* Too long.
* Doesn't elaborate on what "fieldmap" really is, and does not link to any documentation about it.
* Access super-global, which makes it hard to test. Should instead return a data-transfer object, like:<br><syntaxhighlight lang="php">
$_SESSION['fieldmap'] = createFieldMap(...);
</syntaxhighlight>
* Has no test
* Mixes Hungarian notation with non-Hungarian notation in the argument list

== Defensive programming and error handling ==

todo

* '''Fail hard, fail early'''. The earlier the program crashes when something is wrong, the lower is the probability that you'll end up with corrupt data in the database that will later require manual labor to correct.
* Fail with '''actionable information'''
* Check input to functions and throw <code>InvalidArgumentException</code> if it violates the function's pre-conditions
* Use assert for class-internal invariants
* Use assert to make assumptions explicit for the reader

== Documentation ==

=== PHPDoc ===

* All functions must have a proper docblock
* The first line of the docblock should describe the relation between ''all'' the input arguments and the output of the function in a single sentence
* Each parameter must have the correct type
* Don't use <code>array</code> as type if it's a list of object - instead, use <code>[]</code> like so: <code>Survey[]</code> for a list of surveys

=== Technical documentation ===

todo, UML, scenarios, use-cases

== The PHP of yesterday ==

Old idioms and habits that should be abandoned.

* Don't use associative arrays, almost never. Data-transfer objects have multiple benefits: they are clearly structured, can be documented, can enforce invariants. There's ''no'' performance overhead of objects compared to arrays in modern PHP.
* Objects are already passed by reference; arrays are value types
* Use <code>[]</code> instead of <code>array()</code>
* Hungarian notation was useful before static analysis existed for PHP. These days it's better to use something that can be checked automatically: docblock @param and inline @var annotations.

== The PHP of tomorrow ==

todo

Union tags

Short functions

Match expressions

== Security ==

todo

XSS

Database injection

Permissions and roles

== Performance ==

todo

Loading too many rows into PHP models

== Testing ==

todo

QA

PHPUnit

TDD

Mocks, can't mock functions, static methods, mocking as a DSL, PHPUnit mocking tools

Pure functions, referential transparency, side-effects

Unit, functional, integration

Don't test the framework; don't test PHP

Makes sure the function or class lives up to its specification; make sure it will ''always'' live up to its specification, even in the future, to avoid regressions.

== Static analysis ==

<code>php -l</code>, CodeSniffer, Mess Detector, Psalm

== Database design ==

todo

== JavaScript ==

todo

classes, functions, components, tests

== CSS ==

todo

== HTML ==

todo

== Feedback ==

=== "Why do I have to refactor code that works?" ===

todo, Sadly, it's not enough for the code to live up to the current specification and requirements, it must also be protected against future changes, regressions. Adding tests is the best way for this. Lots of people might read and change the LimeSurvey code the next 5-10 years. The test suite creates a security layer to make sure the specification is fulfilled even as the code changes.

Tests are not a magical solution, however. It does not protect us against other degradation of the code quality, like classes gaining too much responsibility (too many methods, unrelated methods, too many properties).

=== "What's the correct ratio between integrity tests and unit tests?" ===

todo, Don't know. Different pros and cons.

* Unit-test can be run in parallel and are faster
* Unit-tests don't need setup and teardown

Cons of unit-tests is that they need a bigger effort on the side of the developer to make them possible, for example injecting the dependencies properly to enable mocking, or lifting side-effects up in the stack trace.

=== How to disagree ===

All rules can be broken. To break a rule, you should reason in terms of risk and the assumptions used in this guide.

'''Assumptions:'''

# Regressions are the biggest technical risk for LimeSurvey the last five years (2021)
# Automated tests are the best risk mitigation technique against regressions

'''Possible disagreement:'''

# A certain piece of code has very low ''probability'' of regressions (maybe we "know" no one else will every touch or change it?)
# Regression in a certain piece of code would have very low ''impact''

== Resources ==

todo

Books, links, videos

Code quality guide

2021-05-05T09:18:46Z

Olle: /* Types of classes */

DRAFT

== Prologue ==

# '''Be risk aware'''. Too good code can be a business risk (slow to write, maybe over-designed). Too sloppy code can also be a business risk (hard to maintain and understand). You have to find a balance that is adapted to the current situation and risk analysis, in which code quality becomes a '''risk mitigation''' technique among others.
# '''Be humble'''. LimeSurvey was made by developers from all over the world, with different age, education and experience. Your code might be read by a completely different team ten years from now, in the same way you are now reading code by developers that no longer work with us, but which work pays our rent.
# '''Performance matters sometimes''', and shouldn't be disregarded completely. In particular, database queries using the ORM and ActiveRecord can be problematic. Some surveys have thousands of questions and hundreds of thousands of responses. Fast response time is also important for a fluid user experience.
# '''It's harder to read code than to write code'''. Don't choose patterns that are easy or fast to write, but that are easy to read.
# Make your code '''communicate intent'''.
# It's easy to forget '''cross-cutting concerns''' like translation and security. Keep a mental note.
# '''Stress affects code quality''' and your risk behaviour. If your stress level is too high to write code with proper quality, take a step back and discuss it with your boss, or you'll push problems to the future.

== Quality ==

The purpose of this guide is to increase the quality of the LimeSurvey code-base. What is quality? Which aspects of quality can be measured? Which kind of company culture gives rise to appropriate code quality?

It's usually easier to get along what is "bad" code than what's "best" code. Blacklist instead of whitelist?

Quality attributes related to code quality:

* Readability
* Testability
* Maintainability
* Performance
* Security
* Reliability

Can not increase all at the same time - performance vs readability.

It's better to avoid emotional language when describing code quality, like "clean" or "dirty". Be precise, objective and suggest solutions.

Idiomatic code is more readable than non-idiomatic code. What's idiomatic depends on which context or domain you work in. We work in PHP and web application development, and have other idioms than in, say, functional or hardware-close programming.

Some code are "hot spots" - changed often. Those parts should require higher quality than other code.

== Risk ==

todo

data loss as most severe risk for LS

usability a business risk - hard to use or understand, people will choose another tool

risks relevant when fixing bugs

risks relevant when adding new features (lack of testing, wrong requirements, scope creep)

risks relevant when refactoring (regressions)

unit tests and QA as risk mitigation

partial deployment, alpha/beta/rc, risk communication

software rot, design pattern rot/grime, software evolution

rot = non-pattern related code

testing by community, bug fixing by community

== Modules ==

There's no inherit module functionality in PHP, but Yii has a module system. Libraries can be seen as a module system.

Examples of implicit modules in LimeSurvey:

* Front-end (survey taking)
* Back-end (survey design)
* Survey theme editing
* Expression manager
* Plugin system

In the future, they need to be separated and implemented more clearly as whatever Yii 3 module system is in use.

Some data models are common for all modules, e.g. surveys and users. Can have a "Common" module for such data.

todo, relation to Yii config system

== Classes ==

* Avoid empty OOP ceremony, like defining getters and setters for all properties. Might as well make them public, ''unless'' they have invariants that need to be upheld, e.g. "this number is always between 1 and 10" or "this string is maximum length 20".
* Almost always avoid static methods. They cannot be mocked. One exception is (possibly) factory methods (Foo::make(...)).
* Inject all dependencies. This will make sure the class can be unit-tested (unit-tests have several benefits over integrity tests - they can be run in parallel and don't require any setup and teardown)
* A second way to achieve testability is to factor out the methods that access the dependencies

todo, state vs behaviour, state vs dependencies

=== OOP design ===

Start from top-down, with domain, behaviour, interaction between objects, database design, pseudo-code if needed. Can also include scenarios, use-cases and UML diagrams.

Object reification - not only domain models, but also domain actions, relations and activities can be objects, e.g. a class ActivateSurvey or ExportSurvey.

Hierarchy depth should be kept reasonable shallow to avoid conflicts between methods, spooky action at a distance. Compare with Yii 3, where controllers no longer inherit anything.

Some people advocate for composition instead of inheritance. Lots of blog posts available for more info.

Multiple inheritance is done with traits in PHP. Use-case: ActiveRecords that support encryption, but not all.

=== Design pattern grime and software evolution ===

Design rot after time - how to keep it tight? (Grime.)

todo

design pattern rot --> lose behaviour relevant for pattern (active record without db connection)

design patter grime --> add behaviour irrelevant for pattern (active record that's also a singleton)

=== State ===

Heuristics to consider but not follow slavishly.

Keep a clear separation between classes with state and classes with no state.

Classes with state should not have dependencies with IO (it's OK to depend on classes in the same application layer, e.g. other DTO classes), and vice versa. ActiveRecord is an example which violates this principle.

class Survey
// Confusion - first params are domain state, last a resource
__construct(id, language, dbConnection)

If a method does not call "this", should it instead be outside the class? A separate class or function, maybe.

todo, elaborate

=== Types of classes ===

Different categories of classes:

* Entity (domain class; has state and validation behaviour)
* Resource (database connection, file, curl, logger; state is in the resource (open, closed))
* Repository classes (database interaction, like splitting ActiveRecord in two parts: Entity class and database interaction)
* DAO, data access object
* Builders (e.g. query builder, HTML message builder)
* Data-transfer object (no behaviour; pass to views to have better documentation and intent than associative arrays)
* Value classes (e.g. Email address to wrap email string around)
* Command object (e.g. SurveyActivator)
* Helper (no state; e.g. QuestionAttributeHelper to bake attributes into different formats used by the views)
* Wrapper

todo, immutability, possible with private properties that are set in the constructor,

todo: command-query separation for classes?

todo: dependencies between layers, dependencies to the framework

todo, pure vs effectful classes

=== Types of classes in LimeSurvey ===

* ActiveRecord, used to communicate with the database, and should not do ''anything'' else
* Controllers, used for glue code; should not contain business-logic (also CLI controllers)
* Helper functions (not classes, yet...), should be short and obey command-query separation (TODO: Long functions should be separated into command objects or service classes); todo: should not have any dependencies?
* Helper classes, similar to helper functions but have dependencies that need to be mocked during tests; should not have any state
* Service classes, contains logic related to a clear and separate task, like create or import survey
* Question render classes, contains logic related to how questions are rendered (TODO: Need better separation between state and logic and more clear design); similar to widgets
* Plugin classes, using the plugin event system
* Widgets, containing HTML logic for custom HTML widgets
* HTML helpers (Yii)
* Customizations to the Yii framework by inheritance
* Unit and functional test classes

A couple of classes contain only data, like LsDefaultDataSet.

todo, no difference between state property and dependency property in OOP

=== What is "glue code"? ===

todo

Putting the pieces together, e.g. service class A need data from model B, fetch it and run.

todo, add example

=== "Where do I cut?" ===

Separation of concerns, but which concerns and which type of separation? Command-query (function core, imperative shell) is one type of separation. Other separation between layers, e.g. logic layer and data persistency layer (similar in thought).

Other separation, that one class should have a clear purpose. A design pattern should only implement ''one'' pattern, not multiple, and not half a pattern.

There's a problem with "helper" or "manager" classes that they can grow indefinitely, but might be better than nothing. Example when moving business logic out of ActiveRecord class to a helper class it can sometimes hard to be more specific than "helper".

=== Size ===

A class should have a single and clear purpose; compare with [https://en.wikipedia.org/wiki/SOLID SOLID].

=== Class name ===

* ActiveRecord classes are named after the database table they are bound to, but with singular instead of plural. E.g. table "lime_users" have model "User".
* Command classes are named after what they ''do'' and imperatively, e.g. CreateSurvey
* Helper classes should probably be named as specific as possible when possible, to avoid them from growing too big
* Follow the naming tradition of the framework with regard to controllers, e.g. UserController or UserAdministrationController.
* Class properties of ActiveRecord classes will follow the naming of the database, using underscore instead of camel case (and ActiveRecord classes should have ''no'' other properties than those (excluding the database connection injected by the framework))

== Functions ==

Functions are one of the fundamental building blocks of programming, so it's important to get it right.

Functions that are part of a class are called "methods", if you want to be formal.

Different types of functions in PHP:

* Functions (not attached to a class)
* Methods (attached to class)
* Anonymous functions (does not capture scope automatically)
* Short functions (does capture scope automatically)

I'm using "function" as a word for all types of functions in PHP below.

<hr>

=== Size ===

* A function should be short enough to be completely readable on one screen, approx 60 lines at most
* A function should not have too many arguments; if you have five or more, consider making it a class instead
* If a function is growing too big, it might be better to create a class instead or split it into several functions (if both functions have '''common state''', a class might be better, unless you want to pass around '''explicit state''')

=== Contract ===

* A function has a contract with its surrounding environment:
** Pre-condition: What needs to be true before the function is executed
** Post-condition: What will be true after the function has returned
* The function contract can be checked with assertions (internal invariants) or exceptions (outside world); see below
* Another good way is to use unit-tests to make sure the function's contract remains stable through changes
* The first line in the docblock should be one sentence describing the relation between function arguments and its output<br>Example<br><syntaxhighlight lang="php">
/**
* Creates a random password of length $length (defaults to 12)
* @param int $length
* @return string
*/
function createPassword($lenght = 12)

/**
* Creates an HTML language drop down for survey with id $surveyId, marking $selectedLanguage as selected
* @param int $surveyId
* @param string $selectedLanguage
* @return string <select> HTML
*/
function createLanguageDropdown($surveyId, $selectedLanguage)

</syntaxhighlight>

=== Push side-effects up in the stack trace ===

This one is a bit abstract.

First, what is a '''side-effect'''? In short, it's anything that happens in a function that ''is not'' described by the ''relation'' between function arguments and output.

Another way to phrase it is, that a side-effect is anything that is not always the same for the given input to a function; a function without any side-effects will always return the same result if it gets the same input.

'''Examples:'''

<syntaxhighlight lang="php">
// gT accesses the file system and will return different result depending on what's in the translation files
function gT($sToTranslate, $sEscapeMode = 'html', $sLanguage = null);

// If $sText and $sEscapeMode is always the same, quoteText() will always return the same string.
function quoteText($sText, $sEscapeMode = 'html');
</syntaxhighlight>

A function with no side-effects is called '''pure'''. A function that is guaranteed to always return (no exceptions, no errors, no warnings, no division by zero) is called '''total'''.

It's a good thing if functions in a code-base ''either'' have side-effects, ''or'' return a result. Not both. This is called [https://en.wikipedia.org/wiki/Command%E2%80%93query_separation command-query separation].

Examples of side-effects:

* Database or file access
* Echo, or write to stdout or stderr
* Randomization

Why does this matter? Because side-effects make testing harder! '''If you have side-effects, you cannot create unit tests''', ''unless'' those side-effects can be mocked. If not, you need integrity tests with database setup or more. The more side-effects you have in a function, the more mocking is required to unit test it.

So, one solution to this is to move side-effects higher up in the stack trace, that is, move them to the calling code.

'''Example:'''

<syntaxhighlight lang="php">
function getSurveyInfo(int $surveyid, string $languagecode = '', boolean $force = false): array;
</syntaxhighlight>

Since this function takes $surveyid, we know it will probably query the database. Quering the database is a side-effect, and thus it requires a database scaffold for the test (or mocking, but the database connection is not injected, so there's no way to do it). One simple solution is to lift the side-effect out and pass in a Survey object instead:

<syntaxhighlight lang="php">
function getSurveyInfo(Survey $survey, string $languagecode = '', boolean $force = false): array;
</syntaxhighlight>

Much better! The side-effect of calling the database now happens ''before'' the function call. Now we can either mock a Survey object, or make an imitating stub for our test.

Reading the function body, there is in fact another database access, but since this is a relation to the Survey model, it could easily be moved out too. We've just made a function testable! Hooray!

This principle is rephrased in an architectural settings as [https://github.com/kbilsted/Functional-core-imperative-shell/blob/master/README.md functional core, imperative shell]. This architecture helps you get a good ratio between fast unit tests and slower integrity tests.

Moving side-effects up makes sure we can have a healthy ratio between integrity tests with scripted browser, and unit-tests; maybe around 20-80.

=== Function name ===

* The function name should tell you '''what''' it does; docs should tell you '''why''' (if this information is not obvious). '''How''' is described by the code itself (hopefully, but can in some cases be relevant to document).
* Function name can often be '''verb [+ adjective] + noun''', like "createFieldmap", "quoteText", "getRelativePath"
* Prefix with "is" for boolean functions

todo: difference between create, get, fetch, generate, ...

'''Good examples:'''

* createPassword() - One verb, one noun - clear
* isCaptchaEnabled() - Using "is" signifies it returns boolean; clear purpose
* getFullResponseTable() - Verb, adjective, noun - but is "full" needed here? Is there a non-full version of the same function?
* replaceExpressionCodes() - Pretty good, but it's obvious that more information is needed in the docblock to describe what "replace" means, and what an "expression code" is
* fixCKeditorText() - "fix" is a bit vague, but maybe best there is? Pray that docblock contains information!

'''Bad examples:'''

* languageDropdown() - No verb, doesn't tell you what it does
* rmdirr() - Two r's, looks like a typo, but the last "r" actually means "recursive"! Better: rmdir($recursive = false), rmdir or removeFolder.
* CSVUnquote() - Is CSV really the namespace? Why is the verb the second word?
* incompleteAnsFilterState() - One verb, but in the middle, or is "filter state" a noun?; why abbreviate "answer" to "ans"?
* reverseTranslateFieldNames() - Two verbs - did author mean "reverseTranslatedFieldNames"? Or "reverse and translate"? If so, it should be two functions, one for reverse and one for translate
* checkUploadedFileSizeAndRenderJson() - If you have an "and" in the function name, you should consider splitting it into two functions

'''Controversial'''

* gT() - An exception to descriptive function names; since this is used everywhere, the minimal name is motivated; maybe even name it "t()"? Still hard to read for someone who just started? But Yii uses t() too? Other frameworks use double underscore (Wordpress, Laravel) as function name.

<hr>

=== Function filename and namespace ===

If your function has dependencies or side-effects, it should be put into a class instead, in which the dependencies can be injected. Another alternative is to put the dependencies as argument in the function, although this muffles the relationship between input and output. Again, this is to increase testability.

Keep in mind that functions outside classes cannot be mocked, so only use them when you ''know'' you won't need to mock them.

todo, autoloading of functions and folder location

=== Assertions ===

NB: This is not assertions as used in unit-tests, but assertions as used to check invariants in production code.

Assertions can be used for mental checks. They are only used for internal logic - failed assertions are not supposed to be seen by the end user. For interaction with the outside world, like database or browser, exceptions should be used instead.

Assertions can be disabled in production mode and have then no runtime cost (since PHP 7).

'''Example:'''

<syntaxhighlight lang="php">
/**
* Translation helper function
*
* @param string $sToTranslate
* @param string $sEscapeMode Valid values are html (this is the default, js and unescaped)
* @param string $sLanguage
* @return string
*/
function gT($sToTranslate, $sEscapeMode = 'html', $sLanguage = null)
{
assert(is_string($sToTranslate));
assert(strlen($sToTranslate) > 0);
assert($sEscapeMode === 'html' || $sEscapeMode === 'js' || $sEscapeMode === 'unescaped');
return quoteText(Yii::t('', $sToTranslate, array(), null, $sLanguage), $sEscapeMode);
}
</syntaxhighlight>

<hr>

=== Exceptions ===

todo

todo: exception hierarchy

todo: what can be repaired after exception? transaction rollback

* Exceptions are used to check inputs from the outside world (browser, database, file system)
* Don't use exceptions for control flow, only when fatal errors happen that make further execution impossible
* Exceptions should have clear error messages that make them ''actionable'' - there should be a clear "next step" for the user or developer
* Never, ever, do an empty catch-block

==== Alternatives to exceptions ====

Some people consider exceptions being a hidden form of "goto" which confuses the control flow of the program. They propose different other solutions:

* Return a tuple, like <code>[$result, $errorMessage]</code> where $errorMessage is null at success
* Return <code>null</code> at failure
* Tagged union result type (not yet possible in latest PHP)
* Result object

The con being that you have to manually propagate the error, where an exception can happen from anywhere in the stack trace without any other function knowing about it.

=== If-statements ===

If-statements should not be too long or hard to understand. If they are, consider factor out the checks into separate functions.

<syntaxhighlight lang="php">
if ((empty($instance->oOptions->{$attribute}))
|| (
!empty($instance->oOptions->{$attribute})
&& (
$instance->oOptions->{$attribute} === 'inherit'
|| $instance->oOptions->{$attribute} === 'I'
// NB: Do NOT use === here, it won't work with Postgresql.
|| $instance->oOptions->{$attribute} == '-1'
)
)
) {
</syntaxhighlight>

Can be shortened by factoring out method <code>isInherit</code>:

<syntaxhighlight lang="php">
if (empty($instance->options->{$attribute})
|| $this->isInherit($instance-options->{$attribute})) {
}
/**
* Returns true if $value is set to inherit
* @param mixed|null $value
* @return boolean
*/
public function isInherit($value) {
return !empty($value)
&& (
$value === 'inherit'
|| $value === 'I'
// NB: Do NOT use === here, it won't work with Postgresql.
|| $value == '-1'
);
}
</syntaxhighlight>

And one more time by using a variable for the value:

<syntaxhighlight lang="php">
$value = $instance->options->{$attribute};
if (empty($value) || $this->isInherit($value)) {
}
</syntaxhighlight>

More clear, right? "If it's empty or set to inherit, do this and that."

=== Variables ===

Descriptive naming.

* Follow PSR-12 - no underscore, use camelCaseLikeThis
* Variables of ActiveRecord classes can have same name as the class, like "$survey" or "$question"
* Add -s for plural when it's a list of items: "$surveys", "$questions"
* Never include "array" or "list" in variable names - using plural is enough (for lists, not for associative arrays - see below)
* The ''context'' of the function helps with variable naming, e..g "$name" might be fine in a function about questions; this is extra helpful when functions are short!
* When a function is short, it's much easier to figure out variable meaning based on context
* $qid, $gid, and $sid are so established in the code-base that they could be considered OK
* The -data suffix means "blob of stuff", only use it when needed, like with $viewData
* Use $result when baking a return value; add its exact type as @var annotation (worst possible name, acceptable but anything with more meaning is better)

Not so good:

<syntaxhighlight lang="php">
$result = LabelSet::model()->findAll();
</syntaxhighlight>

Better with model name and -s for plural:

<syntaxhighlight lang="php">
$labelSets = LabelSet::model()->findAll();
</syntaxhighlight>

* Do not use Hungarian notation (prefix with "type"), but instead <code>/** @var */</code> annotations - these can be checked automatically and will then be enforced to be correct, unlike Hungarian notation which can "rot"

<syntaxhighlight lang="php">
/** string[] An array of strings with 0-n elements */
$allFields = [];
</syntaxhighlight>

Psalm can infer types if the function documentation is enough. The strictness can be adjusted. Not all variables will need @var annotation, the tool will warn you when it's confused.

* Data that is sent to views as associative arrays will be:

<syntaxhighlight lang="php">
/** @var array Can be basically anything :( Better would be data-transfer objects or more precise notation */
$data = [];
// Maybe more clear as $viewData? Discuss.
</syntaxhighlight>

You can be more precise when you specify which type of array you're writing:

<syntaxhighlight lang="php">
/** @var array<string, string> This means the array key is string, and the array value is also string */
$data = [];
$data['name'] = 'Olle';
$data['occupation'] = 'Developer';
$data['age'] = 38; // ERROR! Value must be string.
</syntaxhighlight>

For more info about array type notation, see the [https://psalm.dev/docs/annotating_code/type_syntax/array_types/ Psalm documentation].

Some smaller examples:

<syntaxhighlight lang="php">
$theme = App()->request->getPost('theme'); // Should be $themeType - $theme looks like a model/AR
$gridid === 'questionthemes-grid'; // Should be $gridId with capital "I", since it's two words in English
$delete = Yii::app()->request->getParam('delete'); // Tuff one - $delete is ok? Thoughts?
$files = json_decode(stripslashes($sJSON), true); // $file is a resource, $files an array of resources, this is $fileData perhaps?
$valid_extensions_array = explode(",", $aAttributes['allowed_filetypes']); // Should be $validExtensionTypes
$language = Yii::app()->session['survey_' . $surveyid]['s_lang']; // TODO: Should this be a value class? Then Language::make(...);
$surveyInfo = getSurveyInfo($surveyId, $language); // OK, BUT should be a separate DTO!
$fieldMap = createFieldMap($survey, 'short', false, false, $language); // Same, make a DTO
$cquestions = array(); // What's "c"? Method name is getChildQuestions and $questions is an argument - better with $childQuestions?
</syntaxhighlight>

Links:

[https://www.approxion.com/capital-offenses-how-to-handle-abbreviations-in-camelcase/ How to Handle Abbreviations in CamelCase]

[https://stackoverflow.com/questions/15526107/acronyms-in-camelcase Acronyms in CamelCase]

=== Looping ===

* The bodies of foreach-loops are often a good candidate to factor out into separate functions.

'''Example:'''

<syntaxhighlight lang="php">
foreach ($questions as $question) {
processQuestion($question);
}
</syntaxhighlight>

Note the variable naming from plural to singular.

* Loop indexing should be named i, j, k etc.

'''Example:'''

<syntaxhighlight lang="php">
for ($i = 0; $i < $length; $i++) {
for ($j = 0; $j < $otherLength; $j++) {
// ...
}
}
</syntaxhighlight>

<hr>

=== Function composition ===

todo, "doThisAndThat" --> "doThis(doThat())"

=== Cases ===

<syntaxhighlight lang="php">
/**
* This function generates an array containing the fieldcode, and matching data in the same order as the activate script
*
* @param Survey $survey Survey ActiveRecord model
* @param string $style 'short' (default) or 'full' - full creates extra information like default values
* @param boolean $force_refresh - Forces to really refresh the array, not just take the session copy
* @param bool|int $questionid Limit to a certain qid only (for question preview) - default is false
* @param string $sLanguage The language to use
* @param array $aDuplicateQIDs
* @return array
*/
function createFieldMap($survey, $style = 'short', $force_refresh = false, $questionid = false, $sLanguage = '', &$aDuplicateQIDs = array())
</syntaxhighlight>

'''Good:'''

* Name is verb and noun
* Each argument is documented (almost)

'''Bad:'''

* Returns "array", which can be anything. A separate class for "Fieldmap" would be better.
* Not clear if it should be "createFieldMap" or "createFieldmap" - is "fieldmap" one word or two?
* Very many boolean arguments. Should probably be a class with methods like <code>$fieldmapCreator->setForceRefresh(true);</code> instead.
* Too long.
* Doesn't elaborate on what "fieldmap" really is, and does not link to any documentation about it.
* Access super-global, which makes it hard to test. Should instead return a data-transfer object, like:<br><syntaxhighlight lang="php">
$_SESSION['fieldmap'] = createFieldMap(...);
</syntaxhighlight>
* Has no test
* Mixes Hungarian notation with non-Hungarian notation in the argument list

== Defensive programming and error handling ==

todo

* '''Fail hard, fail early'''. The earlier the program crashes when something is wrong, the lower is the probability that you'll end up with corrupt data in the database that will later require manual labor to correct.
* Fail with '''actionable information'''
* Check input to functions and throw <code>InvalidArgumentException</code> if it violates the function's pre-conditions
* Use assert for class-internal invariants
* Use assert to make assumptions explicit for the reader

== Documentation ==

=== PHPDoc ===

* All functions must have a proper docblock
* The first line of the docblock should describe the relation between ''all'' the input arguments and the output of the function in a single sentence
* Each parameter must have the correct type
* Don't use <code>array</code> as type if it's a list of object - instead, use <code>[]</code> like so: <code>Survey[]</code> for a list of surveys

=== Technical documentation ===

todo, UML, scenarios, use-cases

== The PHP of yesterday ==

Old idioms and habits that should be abandoned.

* Don't use associative arrays, almost never. Data-transfer objects have multiple benefits: they are clearly structured, can be documented, can enforce invariants. There's ''no'' performance overhead of objects compared to arrays in modern PHP.
* Objects are already passed by reference; arrays are value types
* Use <code>[]</code> instead of <code>array()</code>
* Hungarian notation was useful before static analysis existed for PHP. These days it's better to use something that can be checked automatically: docblock @param and inline @var annotations.

== The PHP of tomorrow ==

todo

Union tags

Short functions

Match expressions

== Security ==

todo

XSS

Database injection

Permissions and roles

== Performance ==

todo

Loading too many rows into PHP models

== Testing ==

todo

QA

PHPUnit

TDD

Mocks, can't mock functions, static methods, mocking as a DSL, PHPUnit mocking tools

Pure functions, referential transparency, side-effects

Unit, functional, integration

Don't test the framework; don't test PHP

Makes sure the function or class lives up to its specification; make sure it will ''always'' live up to its specification, even in the future, to avoid regressions.

== Static analysis ==

<code>php -l</code>, CodeSniffer, Mess Detector, Psalm

== Database design ==

todo

== JavaScript ==

todo

classes, functions, components, tests

== CSS ==

todo

== HTML ==

todo

== Feedback ==

=== "Why do I have to refactor code that works?" ===

todo, Sadly, it's not enough for the code to live up to the current specification and requirements, it must also be protected against future changes, regressions. Adding tests is the best way for this. Lots of people might read and change the LimeSurvey code the next 5-10 years. The test suite creates a security layer to make sure the specification is fulfilled even as the code changes.

Tests are not a magical solution, however. It does not protect us against other degradation of the code quality, like classes gaining too much responsibility (too many methods, unrelated methods, too many properties).

=== "What's the correct ratio between integrity tests and unit tests?" ===

todo, Don't know. Different pros and cons.

* Unit-test can be run in parallel and are faster
* Unit-tests don't need setup and teardown

Cons of unit-tests is that they need a bigger effort on the side of the developer to make them possible, for example injecting the dependencies properly to enable mocking, or lifting side-effects up in the stack trace.

=== How to disagree ===

All rules can be broken. To break a rule, you should reason in terms of risk and the assumptions used in this guide.

'''Assumptions:'''

# Regressions are the biggest technical risk for LimeSurvey the last five years (2021)
# Automated tests are the best risk mitigation technique against regressions

'''Possible disagreement:'''

# A certain piece of code has very low ''probability'' of regressions (maybe we "know" no one else will every touch or change it?)
# Regression in a certain piece of code would have very low ''impact''

== Resources ==

todo

Books, links, videos

Code quality guide

2021-05-05T09:15:20Z

Olle: /* Types of classes in LimeSurvey */

DRAFT

== Prologue ==

# '''Be risk aware'''. Too good code can be a business risk (slow to write, maybe over-designed). Too sloppy code can also be a business risk (hard to maintain and understand). You have to find a balance that is adapted to the current situation and risk analysis, in which code quality becomes a '''risk mitigation''' technique among others.
# '''Be humble'''. LimeSurvey was made by developers from all over the world, with different age, education and experience. Your code might be read by a completely different team ten years from now, in the same way you are now reading code by developers that no longer work with us, but which work pays our rent.
# '''Performance matters sometimes''', and shouldn't be disregarded completely. In particular, database queries using the ORM and ActiveRecord can be problematic. Some surveys have thousands of questions and hundreds of thousands of responses. Fast response time is also important for a fluid user experience.
# '''It's harder to read code than to write code'''. Don't choose patterns that are easy or fast to write, but that are easy to read.
# Make your code '''communicate intent'''.
# It's easy to forget '''cross-cutting concerns''' like translation and security. Keep a mental note.
# '''Stress affects code quality''' and your risk behaviour. If your stress level is too high to write code with proper quality, take a step back and discuss it with your boss, or you'll push problems to the future.

== Quality ==

The purpose of this guide is to increase the quality of the LimeSurvey code-base. What is quality? Which aspects of quality can be measured? Which kind of company culture gives rise to appropriate code quality?

It's usually easier to get along what is "bad" code than what's "best" code. Blacklist instead of whitelist?

Quality attributes related to code quality:

* Readability
* Testability
* Maintainability
* Performance
* Security
* Reliability

Can not increase all at the same time - performance vs readability.

It's better to avoid emotional language when describing code quality, like "clean" or "dirty". Be precise, objective and suggest solutions.

Idiomatic code is more readable than non-idiomatic code. What's idiomatic depends on which context or domain you work in. We work in PHP and web application development, and have other idioms than in, say, functional or hardware-close programming.

Some code are "hot spots" - changed often. Those parts should require higher quality than other code.

== Risk ==

todo

data loss as most severe risk for LS

usability a business risk - hard to use or understand, people will choose another tool

risks relevant when fixing bugs

risks relevant when adding new features (lack of testing, wrong requirements, scope creep)

risks relevant when refactoring (regressions)

unit tests and QA as risk mitigation

partial deployment, alpha/beta/rc, risk communication

software rot, design pattern rot/grime, software evolution

rot = non-pattern related code

testing by community, bug fixing by community

== Modules ==

There's no inherit module functionality in PHP, but Yii has a module system. Libraries can be seen as a module system.

Examples of implicit modules in LimeSurvey:

* Front-end (survey taking)
* Back-end (survey design)
* Survey theme editing
* Expression manager
* Plugin system

In the future, they need to be separated and implemented more clearly as whatever Yii 3 module system is in use.

Some data models are common for all modules, e.g. surveys and users. Can have a "Common" module for such data.

todo, relation to Yii config system

== Classes ==

* Avoid empty OOP ceremony, like defining getters and setters for all properties. Might as well make them public, ''unless'' they have invariants that need to be upheld, e.g. "this number is always between 1 and 10" or "this string is maximum length 20".
* Almost always avoid static methods. They cannot be mocked. One exception is (possibly) factory methods (Foo::make(...)).
* Inject all dependencies. This will make sure the class can be unit-tested (unit-tests have several benefits over integrity tests - they can be run in parallel and don't require any setup and teardown)
* A second way to achieve testability is to factor out the methods that access the dependencies

todo, state vs behaviour, state vs dependencies

=== OOP design ===

Start from top-down, with domain, behaviour, interaction between objects, database design, pseudo-code if needed. Can also include scenarios, use-cases and UML diagrams.

Object reification - not only domain models, but also domain actions, relations and activities can be objects, e.g. a class ActivateSurvey or ExportSurvey.

Hierarchy depth should be kept reasonable shallow to avoid conflicts between methods, spooky action at a distance. Compare with Yii 3, where controllers no longer inherit anything.

Some people advocate for composition instead of inheritance. Lots of blog posts available for more info.

Multiple inheritance is done with traits in PHP. Use-case: ActiveRecords that support encryption, but not all.

=== Design pattern grime and software evolution ===

Design rot after time - how to keep it tight? (Grime.)

todo

design pattern rot --> lose behaviour relevant for pattern (active record without db connection)

design patter grime --> add behaviour irrelevant for pattern (active record that's also a singleton)

=== State ===

Heuristics to consider but not follow slavishly.

Keep a clear separation between classes with state and classes with no state.

Classes with state should not have dependencies with IO (it's OK to depend on classes in the same application layer, e.g. other DTO classes), and vice versa. ActiveRecord is an example which violates this principle.

class Survey
// Confusion - first params are domain state, last a resource
__construct(id, language, dbConnection)

If a method does not call "this", should it instead be outside the class? A separate class or function, maybe.

todo, elaborate

=== Types of classes ===

Different categories of classes:

* Entity (domain class; has state and validation behaviour)
* Resource (database connection, file, curl, logger; state is in the resource (open, closed))
* Builders (e.g. query builder, HTML message builder)
* Data-transfer object (no behaviour; pass to views to have better documentation and intent than associative arrays)
* Value classes (e.g. Email address to wrap email string around)
* Command object (e.g. SurveyActivator)
* Helper (no state; e.g. QuestionAttributeHelper to bake attributes into different formats used by the views)
* Wrapper

todo, immutability, possible with private properties that are set in the constructor,

todo: command-query separation for classes?

todo: dependencies between layers, dependencies to the framework

todo, pure vs effectful classes

=== Types of classes in LimeSurvey ===

* ActiveRecord, used to communicate with the database, and should not do ''anything'' else
* Controllers, used for glue code; should not contain business-logic (also CLI controllers)
* Helper functions (not classes, yet...), should be short and obey command-query separation (TODO: Long functions should be separated into command objects or service classes); todo: should not have any dependencies?
* Helper classes, similar to helper functions but have dependencies that need to be mocked during tests; should not have any state
* Service classes, contains logic related to a clear and separate task, like create or import survey
* Question render classes, contains logic related to how questions are rendered (TODO: Need better separation between state and logic and more clear design); similar to widgets
* Plugin classes, using the plugin event system
* Widgets, containing HTML logic for custom HTML widgets
* HTML helpers (Yii)
* Customizations to the Yii framework by inheritance
* Unit and functional test classes

A couple of classes contain only data, like LsDefaultDataSet.

todo, no difference between state property and dependency property in OOP

=== What is "glue code"? ===

todo

Putting the pieces together, e.g. service class A need data from model B, fetch it and run.

todo, add example

=== "Where do I cut?" ===

Separation of concerns, but which concerns and which type of separation? Command-query (function core, imperative shell) is one type of separation. Other separation between layers, e.g. logic layer and data persistency layer (similar in thought).

Other separation, that one class should have a clear purpose. A design pattern should only implement ''one'' pattern, not multiple, and not half a pattern.

There's a problem with "helper" or "manager" classes that they can grow indefinitely, but might be better than nothing. Example when moving business logic out of ActiveRecord class to a helper class it can sometimes hard to be more specific than "helper".

=== Size ===

A class should have a single and clear purpose; compare with [https://en.wikipedia.org/wiki/SOLID SOLID].

=== Class name ===

* ActiveRecord classes are named after the database table they are bound to, but with singular instead of plural. E.g. table "lime_users" have model "User".
* Command classes are named after what they ''do'' and imperatively, e.g. CreateSurvey
* Helper classes should probably be named as specific as possible when possible, to avoid them from growing too big
* Follow the naming tradition of the framework with regard to controllers, e.g. UserController or UserAdministrationController.
* Class properties of ActiveRecord classes will follow the naming of the database, using underscore instead of camel case (and ActiveRecord classes should have ''no'' other properties than those (excluding the database connection injected by the framework))

== Functions ==

Functions are one of the fundamental building blocks of programming, so it's important to get it right.

Functions that are part of a class are called "methods", if you want to be formal.

Different types of functions in PHP:

* Functions (not attached to a class)
* Methods (attached to class)
* Anonymous functions (does not capture scope automatically)
* Short functions (does capture scope automatically)

I'm using "function" as a word for all types of functions in PHP below.

<hr>

=== Size ===

* A function should be short enough to be completely readable on one screen, approx 60 lines at most
* A function should not have too many arguments; if you have five or more, consider making it a class instead
* If a function is growing too big, it might be better to create a class instead or split it into several functions (if both functions have '''common state''', a class might be better, unless you want to pass around '''explicit state''')

=== Contract ===

* A function has a contract with its surrounding environment:
** Pre-condition: What needs to be true before the function is executed
** Post-condition: What will be true after the function has returned
* The function contract can be checked with assertions (internal invariants) or exceptions (outside world); see below
* Another good way is to use unit-tests to make sure the function's contract remains stable through changes
* The first line in the docblock should be one sentence describing the relation between function arguments and its output<br>Example<br><syntaxhighlight lang="php">
/**
* Creates a random password of length $length (defaults to 12)
* @param int $length
* @return string
*/
function createPassword($lenght = 12)

/**
* Creates an HTML language drop down for survey with id $surveyId, marking $selectedLanguage as selected
* @param int $surveyId
* @param string $selectedLanguage
* @return string <select> HTML
*/
function createLanguageDropdown($surveyId, $selectedLanguage)

</syntaxhighlight>

=== Push side-effects up in the stack trace ===

This one is a bit abstract.

First, what is a '''side-effect'''? In short, it's anything that happens in a function that ''is not'' described by the ''relation'' between function arguments and output.

Another way to phrase it is, that a side-effect is anything that is not always the same for the given input to a function; a function without any side-effects will always return the same result if it gets the same input.

'''Examples:'''

<syntaxhighlight lang="php">
// gT accesses the file system and will return different result depending on what's in the translation files
function gT($sToTranslate, $sEscapeMode = 'html', $sLanguage = null);

// If $sText and $sEscapeMode is always the same, quoteText() will always return the same string.
function quoteText($sText, $sEscapeMode = 'html');
</syntaxhighlight>

A function with no side-effects is called '''pure'''. A function that is guaranteed to always return (no exceptions, no errors, no warnings, no division by zero) is called '''total'''.

It's a good thing if functions in a code-base ''either'' have side-effects, ''or'' return a result. Not both. This is called [https://en.wikipedia.org/wiki/Command%E2%80%93query_separation command-query separation].

Examples of side-effects:

* Database or file access
* Echo, or write to stdout or stderr
* Randomization

Why does this matter? Because side-effects make testing harder! '''If you have side-effects, you cannot create unit tests''', ''unless'' those side-effects can be mocked. If not, you need integrity tests with database setup or more. The more side-effects you have in a function, the more mocking is required to unit test it.

So, one solution to this is to move side-effects higher up in the stack trace, that is, move them to the calling code.

'''Example:'''

<syntaxhighlight lang="php">
function getSurveyInfo(int $surveyid, string $languagecode = '', boolean $force = false): array;
</syntaxhighlight>

Since this function takes $surveyid, we know it will probably query the database. Quering the database is a side-effect, and thus it requires a database scaffold for the test (or mocking, but the database connection is not injected, so there's no way to do it). One simple solution is to lift the side-effect out and pass in a Survey object instead:

<syntaxhighlight lang="php">
function getSurveyInfo(Survey $survey, string $languagecode = '', boolean $force = false): array;
</syntaxhighlight>

Much better! The side-effect of calling the database now happens ''before'' the function call. Now we can either mock a Survey object, or make an imitating stub for our test.

Reading the function body, there is in fact another database access, but since this is a relation to the Survey model, it could easily be moved out too. We've just made a function testable! Hooray!

This principle is rephrased in an architectural settings as [https://github.com/kbilsted/Functional-core-imperative-shell/blob/master/README.md functional core, imperative shell]. This architecture helps you get a good ratio between fast unit tests and slower integrity tests.

Moving side-effects up makes sure we can have a healthy ratio between integrity tests with scripted browser, and unit-tests; maybe around 20-80.

=== Function name ===

* The function name should tell you '''what''' it does; docs should tell you '''why''' (if this information is not obvious). '''How''' is described by the code itself (hopefully, but can in some cases be relevant to document).
* Function name can often be '''verb [+ adjective] + noun''', like "createFieldmap", "quoteText", "getRelativePath"
* Prefix with "is" for boolean functions

todo: difference between create, get, fetch, generate, ...

'''Good examples:'''

* createPassword() - One verb, one noun - clear
* isCaptchaEnabled() - Using "is" signifies it returns boolean; clear purpose
* getFullResponseTable() - Verb, adjective, noun - but is "full" needed here? Is there a non-full version of the same function?
* replaceExpressionCodes() - Pretty good, but it's obvious that more information is needed in the docblock to describe what "replace" means, and what an "expression code" is
* fixCKeditorText() - "fix" is a bit vague, but maybe best there is? Pray that docblock contains information!

'''Bad examples:'''

* languageDropdown() - No verb, doesn't tell you what it does
* rmdirr() - Two r's, looks like a typo, but the last "r" actually means "recursive"! Better: rmdir($recursive = false), rmdir or removeFolder.
* CSVUnquote() - Is CSV really the namespace? Why is the verb the second word?
* incompleteAnsFilterState() - One verb, but in the middle, or is "filter state" a noun?; why abbreviate "answer" to "ans"?
* reverseTranslateFieldNames() - Two verbs - did author mean "reverseTranslatedFieldNames"? Or "reverse and translate"? If so, it should be two functions, one for reverse and one for translate
* checkUploadedFileSizeAndRenderJson() - If you have an "and" in the function name, you should consider splitting it into two functions

'''Controversial'''

* gT() - An exception to descriptive function names; since this is used everywhere, the minimal name is motivated; maybe even name it "t()"? Still hard to read for someone who just started? But Yii uses t() too? Other frameworks use double underscore (Wordpress, Laravel) as function name.

<hr>

=== Function filename and namespace ===

If your function has dependencies or side-effects, it should be put into a class instead, in which the dependencies can be injected. Another alternative is to put the dependencies as argument in the function, although this muffles the relationship between input and output. Again, this is to increase testability.

Keep in mind that functions outside classes cannot be mocked, so only use them when you ''know'' you won't need to mock them.

todo, autoloading of functions and folder location

=== Assertions ===

NB: This is not assertions as used in unit-tests, but assertions as used to check invariants in production code.

Assertions can be used for mental checks. They are only used for internal logic - failed assertions are not supposed to be seen by the end user. For interaction with the outside world, like database or browser, exceptions should be used instead.

Assertions can be disabled in production mode and have then no runtime cost (since PHP 7).

'''Example:'''

<syntaxhighlight lang="php">
/**
* Translation helper function
*
* @param string $sToTranslate
* @param string $sEscapeMode Valid values are html (this is the default, js and unescaped)
* @param string $sLanguage
* @return string
*/
function gT($sToTranslate, $sEscapeMode = 'html', $sLanguage = null)
{
assert(is_string($sToTranslate));
assert(strlen($sToTranslate) > 0);
assert($sEscapeMode === 'html' || $sEscapeMode === 'js' || $sEscapeMode === 'unescaped');
return quoteText(Yii::t('', $sToTranslate, array(), null, $sLanguage), $sEscapeMode);
}
</syntaxhighlight>

<hr>

=== Exceptions ===

todo

todo: exception hierarchy

todo: what can be repaired after exception? transaction rollback

* Exceptions are used to check inputs from the outside world (browser, database, file system)
* Don't use exceptions for control flow, only when fatal errors happen that make further execution impossible
* Exceptions should have clear error messages that make them ''actionable'' - there should be a clear "next step" for the user or developer
* Never, ever, do an empty catch-block

==== Alternatives to exceptions ====

Some people consider exceptions being a hidden form of "goto" which confuses the control flow of the program. They propose different other solutions:

* Return a tuple, like <code>[$result, $errorMessage]</code> where $errorMessage is null at success
* Return <code>null</code> at failure
* Tagged union result type (not yet possible in latest PHP)
* Result object

The con being that you have to manually propagate the error, where an exception can happen from anywhere in the stack trace without any other function knowing about it.

=== If-statements ===

If-statements should not be too long or hard to understand. If they are, consider factor out the checks into separate functions.

<syntaxhighlight lang="php">
if ((empty($instance->oOptions->{$attribute}))
|| (
!empty($instance->oOptions->{$attribute})
&& (
$instance->oOptions->{$attribute} === 'inherit'
|| $instance->oOptions->{$attribute} === 'I'
// NB: Do NOT use === here, it won't work with Postgresql.
|| $instance->oOptions->{$attribute} == '-1'
)
)
) {
</syntaxhighlight>

Can be shortened by factoring out method <code>isInherit</code>:

<syntaxhighlight lang="php">
if (empty($instance->options->{$attribute})
|| $this->isInherit($instance-options->{$attribute})) {
}
/**
* Returns true if $value is set to inherit
* @param mixed|null $value
* @return boolean
*/
public function isInherit($value) {
return !empty($value)
&& (
$value === 'inherit'
|| $value === 'I'
// NB: Do NOT use === here, it won't work with Postgresql.
|| $value == '-1'
);
}
</syntaxhighlight>

And one more time by using a variable for the value:

<syntaxhighlight lang="php">
$value = $instance->options->{$attribute};
if (empty($value) || $this->isInherit($value)) {
}
</syntaxhighlight>

More clear, right? "If it's empty or set to inherit, do this and that."

=== Variables ===

Descriptive naming.

* Follow PSR-12 - no underscore, use camelCaseLikeThis
* Variables of ActiveRecord classes can have same name as the class, like "$survey" or "$question"
* Add -s for plural when it's a list of items: "$surveys", "$questions"
* Never include "array" or "list" in variable names - using plural is enough (for lists, not for associative arrays - see below)
* The ''context'' of the function helps with variable naming, e..g "$name" might be fine in a function about questions; this is extra helpful when functions are short!
* When a function is short, it's much easier to figure out variable meaning based on context
* $qid, $gid, and $sid are so established in the code-base that they could be considered OK
* The -data suffix means "blob of stuff", only use it when needed, like with $viewData
* Use $result when baking a return value; add its exact type as @var annotation (worst possible name, acceptable but anything with more meaning is better)

Not so good:

<syntaxhighlight lang="php">
$result = LabelSet::model()->findAll();
</syntaxhighlight>

Better with model name and -s for plural:

<syntaxhighlight lang="php">
$labelSets = LabelSet::model()->findAll();
</syntaxhighlight>

* Do not use Hungarian notation (prefix with "type"), but instead <code>/** @var */</code> annotations - these can be checked automatically and will then be enforced to be correct, unlike Hungarian notation which can "rot"

<syntaxhighlight lang="php">
/** string[] An array of strings with 0-n elements */
$allFields = [];
</syntaxhighlight>

Psalm can infer types if the function documentation is enough. The strictness can be adjusted. Not all variables will need @var annotation, the tool will warn you when it's confused.

* Data that is sent to views as associative arrays will be:

<syntaxhighlight lang="php">
/** @var array Can be basically anything :( Better would be data-transfer objects or more precise notation */
$data = [];
// Maybe more clear as $viewData? Discuss.
</syntaxhighlight>

You can be more precise when you specify which type of array you're writing:

<syntaxhighlight lang="php">
/** @var array<string, string> This means the array key is string, and the array value is also string */
$data = [];
$data['name'] = 'Olle';
$data['occupation'] = 'Developer';
$data['age'] = 38; // ERROR! Value must be string.
</syntaxhighlight>

For more info about array type notation, see the [https://psalm.dev/docs/annotating_code/type_syntax/array_types/ Psalm documentation].

Some smaller examples:

<syntaxhighlight lang="php">
$theme = App()->request->getPost('theme'); // Should be $themeType - $theme looks like a model/AR
$gridid === 'questionthemes-grid'; // Should be $gridId with capital "I", since it's two words in English
$delete = Yii::app()->request->getParam('delete'); // Tuff one - $delete is ok? Thoughts?
$files = json_decode(stripslashes($sJSON), true); // $file is a resource, $files an array of resources, this is $fileData perhaps?
$valid_extensions_array = explode(",", $aAttributes['allowed_filetypes']); // Should be $validExtensionTypes
$language = Yii::app()->session['survey_' . $surveyid]['s_lang']; // TODO: Should this be a value class? Then Language::make(...);
$surveyInfo = getSurveyInfo($surveyId, $language); // OK, BUT should be a separate DTO!
$fieldMap = createFieldMap($survey, 'short', false, false, $language); // Same, make a DTO
$cquestions = array(); // What's "c"? Method name is getChildQuestions and $questions is an argument - better with $childQuestions?
</syntaxhighlight>

Links:

[https://www.approxion.com/capital-offenses-how-to-handle-abbreviations-in-camelcase/ How to Handle Abbreviations in CamelCase]

[https://stackoverflow.com/questions/15526107/acronyms-in-camelcase Acronyms in CamelCase]

=== Looping ===

* The bodies of foreach-loops are often a good candidate to factor out into separate functions.

'''Example:'''

<syntaxhighlight lang="php">
foreach ($questions as $question) {
processQuestion($question);
}
</syntaxhighlight>

Note the variable naming from plural to singular.

* Loop indexing should be named i, j, k etc.

'''Example:'''

<syntaxhighlight lang="php">
for ($i = 0; $i < $length; $i++) {
for ($j = 0; $j < $otherLength; $j++) {
// ...
}
}
</syntaxhighlight>

<hr>

=== Function composition ===

todo, "doThisAndThat" --> "doThis(doThat())"

=== Cases ===

<syntaxhighlight lang="php">
/**
* This function generates an array containing the fieldcode, and matching data in the same order as the activate script
*
* @param Survey $survey Survey ActiveRecord model
* @param string $style 'short' (default) or 'full' - full creates extra information like default values
* @param boolean $force_refresh - Forces to really refresh the array, not just take the session copy
* @param bool|int $questionid Limit to a certain qid only (for question preview) - default is false
* @param string $sLanguage The language to use
* @param array $aDuplicateQIDs
* @return array
*/
function createFieldMap($survey, $style = 'short', $force_refresh = false, $questionid = false, $sLanguage = '', &$aDuplicateQIDs = array())
</syntaxhighlight>

'''Good:'''

* Name is verb and noun
* Each argument is documented (almost)

'''Bad:'''

* Returns "array", which can be anything. A separate class for "Fieldmap" would be better.
* Not clear if it should be "createFieldMap" or "createFieldmap" - is "fieldmap" one word or two?
* Very many boolean arguments. Should probably be a class with methods like <code>$fieldmapCreator->setForceRefresh(true);</code> instead.
* Too long.
* Doesn't elaborate on what "fieldmap" really is, and does not link to any documentation about it.
* Access super-global, which makes it hard to test. Should instead return a data-transfer object, like:<br><syntaxhighlight lang="php">
$_SESSION['fieldmap'] = createFieldMap(...);
</syntaxhighlight>
* Has no test
* Mixes Hungarian notation with non-Hungarian notation in the argument list

== Defensive programming and error handling ==

todo

* '''Fail hard, fail early'''. The earlier the program crashes when something is wrong, the lower is the probability that you'll end up with corrupt data in the database that will later require manual labor to correct.
* Fail with '''actionable information'''
* Check input to functions and throw <code>InvalidArgumentException</code> if it violates the function's pre-conditions
* Use assert for class-internal invariants
* Use assert to make assumptions explicit for the reader

== Documentation ==

=== PHPDoc ===

* All functions must have a proper docblock
* The first line of the docblock should describe the relation between ''all'' the input arguments and the output of the function in a single sentence
* Each parameter must have the correct type
* Don't use <code>array</code> as type if it's a list of object - instead, use <code>[]</code> like so: <code>Survey[]</code> for a list of surveys

=== Technical documentation ===

todo, UML, scenarios, use-cases

== The PHP of yesterday ==

Old idioms and habits that should be abandoned.

* Don't use associative arrays, almost never. Data-transfer objects have multiple benefits: they are clearly structured, can be documented, can enforce invariants. There's ''no'' performance overhead of objects compared to arrays in modern PHP.
* Objects are already passed by reference; arrays are value types
* Use <code>[]</code> instead of <code>array()</code>
* Hungarian notation was useful before static analysis existed for PHP. These days it's better to use something that can be checked automatically: docblock @param and inline @var annotations.

== The PHP of tomorrow ==

todo

Union tags

Short functions

Match expressions

== Security ==

todo

XSS

Database injection

Permissions and roles

== Performance ==

todo

Loading too many rows into PHP models

== Testing ==

todo

QA

PHPUnit

TDD

Mocks, can't mock functions, static methods, mocking as a DSL, PHPUnit mocking tools

Pure functions, referential transparency, side-effects

Unit, functional, integration

Don't test the framework; don't test PHP

Makes sure the function or class lives up to its specification; make sure it will ''always'' live up to its specification, even in the future, to avoid regressions.

== Static analysis ==

<code>php -l</code>, CodeSniffer, Mess Detector, Psalm

== Database design ==

todo

== JavaScript ==

todo

classes, functions, components, tests

== CSS ==

todo

== HTML ==

todo

== Feedback ==

=== "Why do I have to refactor code that works?" ===

todo, Sadly, it's not enough for the code to live up to the current specification and requirements, it must also be protected against future changes, regressions. Adding tests is the best way for this. Lots of people might read and change the LimeSurvey code the next 5-10 years. The test suite creates a security layer to make sure the specification is fulfilled even as the code changes.

Tests are not a magical solution, however. It does not protect us against other degradation of the code quality, like classes gaining too much responsibility (too many methods, unrelated methods, too many properties).

=== "What's the correct ratio between integrity tests and unit tests?" ===

todo, Don't know. Different pros and cons.

* Unit-test can be run in parallel and are faster
* Unit-tests don't need setup and teardown

Cons of unit-tests is that they need a bigger effort on the side of the developer to make them possible, for example injecting the dependencies properly to enable mocking, or lifting side-effects up in the stack trace.

=== How to disagree ===

All rules can be broken. To break a rule, you should reason in terms of risk and the assumptions used in this guide.

'''Assumptions:'''

# Regressions are the biggest technical risk for LimeSurvey the last five years (2021)
# Automated tests are the best risk mitigation technique against regressions

'''Possible disagreement:'''

# A certain piece of code has very low ''probability'' of regressions (maybe we "know" no one else will every touch or change it?)
# Regression in a certain piece of code would have very low ''impact''

== Resources ==

todo

Books, links, videos

Code quality guide

2021-05-05T09:13:25Z

Olle: /* Types of classes in LimeSurvey */

DRAFT

== Prologue ==

# '''Be risk aware'''. Too good code can be a business risk (slow to write, maybe over-designed). Too sloppy code can also be a business risk (hard to maintain and understand). You have to find a balance that is adapted to the current situation and risk analysis, in which code quality becomes a '''risk mitigation''' technique among others.
# '''Be humble'''. LimeSurvey was made by developers from all over the world, with different age, education and experience. Your code might be read by a completely different team ten years from now, in the same way you are now reading code by developers that no longer work with us, but which work pays our rent.
# '''Performance matters sometimes''', and shouldn't be disregarded completely. In particular, database queries using the ORM and ActiveRecord can be problematic. Some surveys have thousands of questions and hundreds of thousands of responses. Fast response time is also important for a fluid user experience.
# '''It's harder to read code than to write code'''. Don't choose patterns that are easy or fast to write, but that are easy to read.
# Make your code '''communicate intent'''.
# It's easy to forget '''cross-cutting concerns''' like translation and security. Keep a mental note.
# '''Stress affects code quality''' and your risk behaviour. If your stress level is too high to write code with proper quality, take a step back and discuss it with your boss, or you'll push problems to the future.

== Quality ==

The purpose of this guide is to increase the quality of the LimeSurvey code-base. What is quality? Which aspects of quality can be measured? Which kind of company culture gives rise to appropriate code quality?

It's usually easier to get along what is "bad" code than what's "best" code. Blacklist instead of whitelist?

Quality attributes related to code quality:

* Readability
* Testability
* Maintainability
* Performance
* Security
* Reliability

Can not increase all at the same time - performance vs readability.

It's better to avoid emotional language when describing code quality, like "clean" or "dirty". Be precise, objective and suggest solutions.

Idiomatic code is more readable than non-idiomatic code. What's idiomatic depends on which context or domain you work in. We work in PHP and web application development, and have other idioms than in, say, functional or hardware-close programming.

Some code are "hot spots" - changed often. Those parts should require higher quality than other code.

== Risk ==

todo

data loss as most severe risk for LS

usability a business risk - hard to use or understand, people will choose another tool

risks relevant when fixing bugs

risks relevant when adding new features (lack of testing, wrong requirements, scope creep)

risks relevant when refactoring (regressions)

unit tests and QA as risk mitigation

partial deployment, alpha/beta/rc, risk communication

software rot, design pattern rot/grime, software evolution

rot = non-pattern related code

testing by community, bug fixing by community

== Modules ==

There's no inherit module functionality in PHP, but Yii has a module system. Libraries can be seen as a module system.

Examples of implicit modules in LimeSurvey:

* Front-end (survey taking)
* Back-end (survey design)
* Survey theme editing
* Expression manager
* Plugin system

In the future, they need to be separated and implemented more clearly as whatever Yii 3 module system is in use.

Some data models are common for all modules, e.g. surveys and users. Can have a "Common" module for such data.

todo, relation to Yii config system

== Classes ==

* Avoid empty OOP ceremony, like defining getters and setters for all properties. Might as well make them public, ''unless'' they have invariants that need to be upheld, e.g. "this number is always between 1 and 10" or "this string is maximum length 20".
* Almost always avoid static methods. They cannot be mocked. One exception is (possibly) factory methods (Foo::make(...)).
* Inject all dependencies. This will make sure the class can be unit-tested (unit-tests have several benefits over integrity tests - they can be run in parallel and don't require any setup and teardown)
* A second way to achieve testability is to factor out the methods that access the dependencies

todo, state vs behaviour, state vs dependencies

=== OOP design ===

Start from top-down, with domain, behaviour, interaction between objects, database design, pseudo-code if needed. Can also include scenarios, use-cases and UML diagrams.

Object reification - not only domain models, but also domain actions, relations and activities can be objects, e.g. a class ActivateSurvey or ExportSurvey.

Hierarchy depth should be kept reasonable shallow to avoid conflicts between methods, spooky action at a distance. Compare with Yii 3, where controllers no longer inherit anything.

Some people advocate for composition instead of inheritance. Lots of blog posts available for more info.

Multiple inheritance is done with traits in PHP. Use-case: ActiveRecords that support encryption, but not all.

=== Design pattern grime and software evolution ===

Design rot after time - how to keep it tight? (Grime.)

todo

design pattern rot --> lose behaviour relevant for pattern (active record without db connection)

design patter grime --> add behaviour irrelevant for pattern (active record that's also a singleton)

=== State ===

Heuristics to consider but not follow slavishly.

Keep a clear separation between classes with state and classes with no state.

Classes with state should not have dependencies with IO (it's OK to depend on classes in the same application layer, e.g. other DTO classes), and vice versa. ActiveRecord is an example which violates this principle.

class Survey
// Confusion - first params are domain state, last a resource
__construct(id, language, dbConnection)

If a method does not call "this", should it instead be outside the class? A separate class or function, maybe.

todo, elaborate

=== Types of classes ===

Different categories of classes:

* Entity (domain class; has state and validation behaviour)
* Resource (database connection, file, curl, logger; state is in the resource (open, closed))
* Builders (e.g. query builder, HTML message builder)
* Data-transfer object (no behaviour; pass to views to have better documentation and intent than associative arrays)
* Value classes (e.g. Email address to wrap email string around)
* Command object (e.g. SurveyActivator)
* Helper (no state; e.g. QuestionAttributeHelper to bake attributes into different formats used by the views)
* Wrapper

todo, immutability, possible with private properties that are set in the constructor,

todo: command-query separation for classes?

todo: dependencies between layers, dependencies to the framework

todo, pure vs effectful classes

=== Types of classes in LimeSurvey ===

* ActiveRecord, used to communicate with the database, and should not do ''anything'' else
* Controllers, used for glue code; should not contain business-logic (also CLI controllers)
* Helper functions (not classes, yet...), should be short and obey command-query separation (TODO: Long functions should be separated into command objects or service classes); todo: should not have any dependencies?
* Helper classes, similar to helper functions but have dependencies that need to be mocked during tests; should not have any state
* Service classes, contains logic related to a clear and separate task, like create or import survey
* Question render classes, contains logic related to how questions are rendered (TODO: Need better separation between state and logic and more clear design); similar to widgets
* Plugin classes, using the plugin event system
* Widgets, containing HTML logic for custom HTML widgets
* HTML helpers
* Customizations to the Yii framework by inheritance
* Unit and functional test classes

A couple of classes contain only data, like LsDefaultDataSet.

todo, no difference between state property and dependency property in OOP

=== What is "glue code"? ===

todo

Putting the pieces together, e.g. service class A need data from model B, fetch it and run.

todo, add example

=== "Where do I cut?" ===

Separation of concerns, but which concerns and which type of separation? Command-query (function core, imperative shell) is one type of separation. Other separation between layers, e.g. logic layer and data persistency layer (similar in thought).

Other separation, that one class should have a clear purpose. A design pattern should only implement ''one'' pattern, not multiple, and not half a pattern.

There's a problem with "helper" or "manager" classes that they can grow indefinitely, but might be better than nothing. Example when moving business logic out of ActiveRecord class to a helper class it can sometimes hard to be more specific than "helper".

=== Size ===

A class should have a single and clear purpose; compare with [https://en.wikipedia.org/wiki/SOLID SOLID].

=== Class name ===

* ActiveRecord classes are named after the database table they are bound to, but with singular instead of plural. E.g. table "lime_users" have model "User".
* Command classes are named after what they ''do'' and imperatively, e.g. CreateSurvey
* Helper classes should probably be named as specific as possible when possible, to avoid them from growing too big
* Follow the naming tradition of the framework with regard to controllers, e.g. UserController or UserAdministrationController.
* Class properties of ActiveRecord classes will follow the naming of the database, using underscore instead of camel case (and ActiveRecord classes should have ''no'' other properties than those (excluding the database connection injected by the framework))

== Functions ==

Functions are one of the fundamental building blocks of programming, so it's important to get it right.

Functions that are part of a class are called "methods", if you want to be formal.

Different types of functions in PHP:

* Functions (not attached to a class)
* Methods (attached to class)
* Anonymous functions (does not capture scope automatically)
* Short functions (does capture scope automatically)

I'm using "function" as a word for all types of functions in PHP below.

<hr>

=== Size ===

* A function should be short enough to be completely readable on one screen, approx 60 lines at most
* A function should not have too many arguments; if you have five or more, consider making it a class instead
* If a function is growing too big, it might be better to create a class instead or split it into several functions (if both functions have '''common state''', a class might be better, unless you want to pass around '''explicit state''')

=== Contract ===

* A function has a contract with its surrounding environment:
** Pre-condition: What needs to be true before the function is executed
** Post-condition: What will be true after the function has returned
* The function contract can be checked with assertions (internal invariants) or exceptions (outside world); see below
* Another good way is to use unit-tests to make sure the function's contract remains stable through changes
* The first line in the docblock should be one sentence describing the relation between function arguments and its output<br>Example<br><syntaxhighlight lang="php">
/**
* Creates a random password of length $length (defaults to 12)
* @param int $length
* @return string
*/
function createPassword($lenght = 12)

/**
* Creates an HTML language drop down for survey with id $surveyId, marking $selectedLanguage as selected
* @param int $surveyId
* @param string $selectedLanguage
* @return string <select> HTML
*/
function createLanguageDropdown($surveyId, $selectedLanguage)

</syntaxhighlight>

=== Push side-effects up in the stack trace ===

This one is a bit abstract.

First, what is a '''side-effect'''? In short, it's anything that happens in a function that ''is not'' described by the ''relation'' between function arguments and output.

Another way to phrase it is, that a side-effect is anything that is not always the same for the given input to a function; a function without any side-effects will always return the same result if it gets the same input.

'''Examples:'''

<syntaxhighlight lang="php">
// gT accesses the file system and will return different result depending on what's in the translation files
function gT($sToTranslate, $sEscapeMode = 'html', $sLanguage = null);

// If $sText and $sEscapeMode is always the same, quoteText() will always return the same string.
function quoteText($sText, $sEscapeMode = 'html');
</syntaxhighlight>

A function with no side-effects is called '''pure'''. A function that is guaranteed to always return (no exceptions, no errors, no warnings, no division by zero) is called '''total'''.

It's a good thing if functions in a code-base ''either'' have side-effects, ''or'' return a result. Not both. This is called [https://en.wikipedia.org/wiki/Command%E2%80%93query_separation command-query separation].

Examples of side-effects:

* Database or file access
* Echo, or write to stdout or stderr
* Randomization

Why does this matter? Because side-effects make testing harder! '''If you have side-effects, you cannot create unit tests''', ''unless'' those side-effects can be mocked. If not, you need integrity tests with database setup or more. The more side-effects you have in a function, the more mocking is required to unit test it.

So, one solution to this is to move side-effects higher up in the stack trace, that is, move them to the calling code.

'''Example:'''

<syntaxhighlight lang="php">
function getSurveyInfo(int $surveyid, string $languagecode = '', boolean $force = false): array;
</syntaxhighlight>

Since this function takes $surveyid, we know it will probably query the database. Quering the database is a side-effect, and thus it requires a database scaffold for the test (or mocking, but the database connection is not injected, so there's no way to do it). One simple solution is to lift the side-effect out and pass in a Survey object instead:

<syntaxhighlight lang="php">
function getSurveyInfo(Survey $survey, string $languagecode = '', boolean $force = false): array;
</syntaxhighlight>

Much better! The side-effect of calling the database now happens ''before'' the function call. Now we can either mock a Survey object, or make an imitating stub for our test.

Reading the function body, there is in fact another database access, but since this is a relation to the Survey model, it could easily be moved out too. We've just made a function testable! Hooray!

This principle is rephrased in an architectural settings as [https://github.com/kbilsted/Functional-core-imperative-shell/blob/master/README.md functional core, imperative shell]. This architecture helps you get a good ratio between fast unit tests and slower integrity tests.

Moving side-effects up makes sure we can have a healthy ratio between integrity tests with scripted browser, and unit-tests; maybe around 20-80.

=== Function name ===

* The function name should tell you '''what''' it does; docs should tell you '''why''' (if this information is not obvious). '''How''' is described by the code itself (hopefully, but can in some cases be relevant to document).
* Function name can often be '''verb [+ adjective] + noun''', like "createFieldmap", "quoteText", "getRelativePath"
* Prefix with "is" for boolean functions

todo: difference between create, get, fetch, generate, ...

'''Good examples:'''

* createPassword() - One verb, one noun - clear
* isCaptchaEnabled() - Using "is" signifies it returns boolean; clear purpose
* getFullResponseTable() - Verb, adjective, noun - but is "full" needed here? Is there a non-full version of the same function?
* replaceExpressionCodes() - Pretty good, but it's obvious that more information is needed in the docblock to describe what "replace" means, and what an "expression code" is
* fixCKeditorText() - "fix" is a bit vague, but maybe best there is? Pray that docblock contains information!

'''Bad examples:'''

* languageDropdown() - No verb, doesn't tell you what it does
* rmdirr() - Two r's, looks like a typo, but the last "r" actually means "recursive"! Better: rmdir($recursive = false), rmdir or removeFolder.
* CSVUnquote() - Is CSV really the namespace? Why is the verb the second word?
* incompleteAnsFilterState() - One verb, but in the middle, or is "filter state" a noun?; why abbreviate "answer" to "ans"?
* reverseTranslateFieldNames() - Two verbs - did author mean "reverseTranslatedFieldNames"? Or "reverse and translate"? If so, it should be two functions, one for reverse and one for translate
* checkUploadedFileSizeAndRenderJson() - If you have an "and" in the function name, you should consider splitting it into two functions

'''Controversial'''

* gT() - An exception to descriptive function names; since this is used everywhere, the minimal name is motivated; maybe even name it "t()"? Still hard to read for someone who just started? But Yii uses t() too? Other frameworks use double underscore (Wordpress, Laravel) as function name.

<hr>

=== Function filename and namespace ===

If your function has dependencies or side-effects, it should be put into a class instead, in which the dependencies can be injected. Another alternative is to put the dependencies as argument in the function, although this muffles the relationship between input and output. Again, this is to increase testability.

Keep in mind that functions outside classes cannot be mocked, so only use them when you ''know'' you won't need to mock them.

todo, autoloading of functions and folder location

=== Assertions ===

NB: This is not assertions as used in unit-tests, but assertions as used to check invariants in production code.

Assertions can be used for mental checks. They are only used for internal logic - failed assertions are not supposed to be seen by the end user. For interaction with the outside world, like database or browser, exceptions should be used instead.

Assertions can be disabled in production mode and have then no runtime cost (since PHP 7).

'''Example:'''

<syntaxhighlight lang="php">
/**
* Translation helper function
*
* @param string $sToTranslate
* @param string $sEscapeMode Valid values are html (this is the default, js and unescaped)
* @param string $sLanguage
* @return string
*/
function gT($sToTranslate, $sEscapeMode = 'html', $sLanguage = null)
{
assert(is_string($sToTranslate));
assert(strlen($sToTranslate) > 0);
assert($sEscapeMode === 'html' || $sEscapeMode === 'js' || $sEscapeMode === 'unescaped');
return quoteText(Yii::t('', $sToTranslate, array(), null, $sLanguage), $sEscapeMode);
}
</syntaxhighlight>

<hr>

=== Exceptions ===

todo

todo: exception hierarchy

todo: what can be repaired after exception? transaction rollback

* Exceptions are used to check inputs from the outside world (browser, database, file system)
* Don't use exceptions for control flow, only when fatal errors happen that make further execution impossible
* Exceptions should have clear error messages that make them ''actionable'' - there should be a clear "next step" for the user or developer
* Never, ever, do an empty catch-block

==== Alternatives to exceptions ====

Some people consider exceptions being a hidden form of "goto" which confuses the control flow of the program. They propose different other solutions:

* Return a tuple, like <code>[$result, $errorMessage]</code> where $errorMessage is null at success
* Return <code>null</code> at failure
* Tagged union result type (not yet possible in latest PHP)
* Result object

The con being that you have to manually propagate the error, where an exception can happen from anywhere in the stack trace without any other function knowing about it.

=== If-statements ===

If-statements should not be too long or hard to understand. If they are, consider factor out the checks into separate functions.

<syntaxhighlight lang="php">
if ((empty($instance->oOptions->{$attribute}))
|| (
!empty($instance->oOptions->{$attribute})
&& (
$instance->oOptions->{$attribute} === 'inherit'
|| $instance->oOptions->{$attribute} === 'I'
// NB: Do NOT use === here, it won't work with Postgresql.
|| $instance->oOptions->{$attribute} == '-1'
)
)
) {
</syntaxhighlight>

Can be shortened by factoring out method <code>isInherit</code>:

<syntaxhighlight lang="php">
if (empty($instance->options->{$attribute})
|| $this->isInherit($instance-options->{$attribute})) {
}
/**
* Returns true if $value is set to inherit
* @param mixed|null $value
* @return boolean
*/
public function isInherit($value) {
return !empty($value)
&& (
$value === 'inherit'
|| $value === 'I'
// NB: Do NOT use === here, it won't work with Postgresql.
|| $value == '-1'
);
}
</syntaxhighlight>

And one more time by using a variable for the value:

<syntaxhighlight lang="php">
$value = $instance->options->{$attribute};
if (empty($value) || $this->isInherit($value)) {
}
</syntaxhighlight>

More clear, right? "If it's empty or set to inherit, do this and that."

=== Variables ===

Descriptive naming.

* Follow PSR-12 - no underscore, use camelCaseLikeThis
* Variables of ActiveRecord classes can have same name as the class, like "$survey" or "$question"
* Add -s for plural when it's a list of items: "$surveys", "$questions"
* Never include "array" or "list" in variable names - using plural is enough (for lists, not for associative arrays - see below)
* The ''context'' of the function helps with variable naming, e..g "$name" might be fine in a function about questions; this is extra helpful when functions are short!
* When a function is short, it's much easier to figure out variable meaning based on context
* $qid, $gid, and $sid are so established in the code-base that they could be considered OK
* The -data suffix means "blob of stuff", only use it when needed, like with $viewData
* Use $result when baking a return value; add its exact type as @var annotation (worst possible name, acceptable but anything with more meaning is better)

Not so good:

<syntaxhighlight lang="php">
$result = LabelSet::model()->findAll();
</syntaxhighlight>

Better with model name and -s for plural:

<syntaxhighlight lang="php">
$labelSets = LabelSet::model()->findAll();
</syntaxhighlight>

* Do not use Hungarian notation (prefix with "type"), but instead <code>/** @var */</code> annotations - these can be checked automatically and will then be enforced to be correct, unlike Hungarian notation which can "rot"

<syntaxhighlight lang="php">
/** string[] An array of strings with 0-n elements */
$allFields = [];
</syntaxhighlight>

Psalm can infer types if the function documentation is enough. The strictness can be adjusted. Not all variables will need @var annotation, the tool will warn you when it's confused.

* Data that is sent to views as associative arrays will be:

<syntaxhighlight lang="php">
/** @var array Can be basically anything :( Better would be data-transfer objects or more precise notation */
$data = [];
// Maybe more clear as $viewData? Discuss.
</syntaxhighlight>

You can be more precise when you specify which type of array you're writing:

<syntaxhighlight lang="php">
/** @var array<string, string> This means the array key is string, and the array value is also string */
$data = [];
$data['name'] = 'Olle';
$data['occupation'] = 'Developer';
$data['age'] = 38; // ERROR! Value must be string.
</syntaxhighlight>

For more info about array type notation, see the [https://psalm.dev/docs/annotating_code/type_syntax/array_types/ Psalm documentation].

Some smaller examples:

<syntaxhighlight lang="php">
$theme = App()->request->getPost('theme'); // Should be $themeType - $theme looks like a model/AR
$gridid === 'questionthemes-grid'; // Should be $gridId with capital "I", since it's two words in English
$delete = Yii::app()->request->getParam('delete'); // Tuff one - $delete is ok? Thoughts?
$files = json_decode(stripslashes($sJSON), true); // $file is a resource, $files an array of resources, this is $fileData perhaps?
$valid_extensions_array = explode(",", $aAttributes['allowed_filetypes']); // Should be $validExtensionTypes
$language = Yii::app()->session['survey_' . $surveyid]['s_lang']; // TODO: Should this be a value class? Then Language::make(...);
$surveyInfo = getSurveyInfo($surveyId, $language); // OK, BUT should be a separate DTO!
$fieldMap = createFieldMap($survey, 'short', false, false, $language); // Same, make a DTO
$cquestions = array(); // What's "c"? Method name is getChildQuestions and $questions is an argument - better with $childQuestions?
</syntaxhighlight>

Links:

[https://www.approxion.com/capital-offenses-how-to-handle-abbreviations-in-camelcase/ How to Handle Abbreviations in CamelCase]

[https://stackoverflow.com/questions/15526107/acronyms-in-camelcase Acronyms in CamelCase]

=== Looping ===

* The bodies of foreach-loops are often a good candidate to factor out into separate functions.

'''Example:'''

<syntaxhighlight lang="php">
foreach ($questions as $question) {
processQuestion($question);
}
</syntaxhighlight>

Note the variable naming from plural to singular.

* Loop indexing should be named i, j, k etc.

'''Example:'''

<syntaxhighlight lang="php">
for ($i = 0; $i < $length; $i++) {
for ($j = 0; $j < $otherLength; $j++) {
// ...
}
}
</syntaxhighlight>

<hr>

=== Function composition ===

todo, "doThisAndThat" --> "doThis(doThat())"

=== Cases ===

<syntaxhighlight lang="php">
/**
* This function generates an array containing the fieldcode, and matching data in the same order as the activate script
*
* @param Survey $survey Survey ActiveRecord model
* @param string $style 'short' (default) or 'full' - full creates extra information like default values
* @param boolean $force_refresh - Forces to really refresh the array, not just take the session copy
* @param bool|int $questionid Limit to a certain qid only (for question preview) - default is false
* @param string $sLanguage The language to use
* @param array $aDuplicateQIDs
* @return array
*/
function createFieldMap($survey, $style = 'short', $force_refresh = false, $questionid = false, $sLanguage = '', &$aDuplicateQIDs = array())
</syntaxhighlight>

'''Good:'''

* Name is verb and noun
* Each argument is documented (almost)

'''Bad:'''

* Returns "array", which can be anything. A separate class for "Fieldmap" would be better.
* Not clear if it should be "createFieldMap" or "createFieldmap" - is "fieldmap" one word or two?
* Very many boolean arguments. Should probably be a class with methods like <code>$fieldmapCreator->setForceRefresh(true);</code> instead.
* Too long.
* Doesn't elaborate on what "fieldmap" really is, and does not link to any documentation about it.
* Access super-global, which makes it hard to test. Should instead return a data-transfer object, like:<br><syntaxhighlight lang="php">
$_SESSION['fieldmap'] = createFieldMap(...);
</syntaxhighlight>
* Has no test
* Mixes Hungarian notation with non-Hungarian notation in the argument list

== Defensive programming and error handling ==

todo

* '''Fail hard, fail early'''. The earlier the program crashes when something is wrong, the lower is the probability that you'll end up with corrupt data in the database that will later require manual labor to correct.
* Fail with '''actionable information'''
* Check input to functions and throw <code>InvalidArgumentException</code> if it violates the function's pre-conditions
* Use assert for class-internal invariants
* Use assert to make assumptions explicit for the reader

== Documentation ==

=== PHPDoc ===

* All functions must have a proper docblock
* The first line of the docblock should describe the relation between ''all'' the input arguments and the output of the function in a single sentence
* Each parameter must have the correct type
* Don't use <code>array</code> as type if it's a list of object - instead, use <code>[]</code> like so: <code>Survey[]</code> for a list of surveys

=== Technical documentation ===

todo, UML, scenarios, use-cases

== The PHP of yesterday ==

Old idioms and habits that should be abandoned.

* Don't use associative arrays, almost never. Data-transfer objects have multiple benefits: they are clearly structured, can be documented, can enforce invariants. There's ''no'' performance overhead of objects compared to arrays in modern PHP.
* Objects are already passed by reference; arrays are value types
* Use <code>[]</code> instead of <code>array()</code>
* Hungarian notation was useful before static analysis existed for PHP. These days it's better to use something that can be checked automatically: docblock @param and inline @var annotations.

== The PHP of tomorrow ==

todo

Union tags

Short functions

Match expressions

== Security ==

todo

XSS

Database injection

Permissions and roles

== Performance ==

todo

Loading too many rows into PHP models

== Testing ==

todo

QA

PHPUnit

TDD

Mocks, can't mock functions, static methods, mocking as a DSL, PHPUnit mocking tools

Pure functions, referential transparency, side-effects

Unit, functional, integration

Don't test the framework; don't test PHP

Makes sure the function or class lives up to its specification; make sure it will ''always'' live up to its specification, even in the future, to avoid regressions.

== Static analysis ==

<code>php -l</code>, CodeSniffer, Mess Detector, Psalm

== Database design ==

todo

== JavaScript ==

todo

classes, functions, components, tests

== CSS ==

todo

== HTML ==

todo

== Feedback ==

=== "Why do I have to refactor code that works?" ===

todo, Sadly, it's not enough for the code to live up to the current specification and requirements, it must also be protected against future changes, regressions. Adding tests is the best way for this. Lots of people might read and change the LimeSurvey code the next 5-10 years. The test suite creates a security layer to make sure the specification is fulfilled even as the code changes.

Tests are not a magical solution, however. It does not protect us against other degradation of the code quality, like classes gaining too much responsibility (too many methods, unrelated methods, too many properties).

=== "What's the correct ratio between integrity tests and unit tests?" ===

todo, Don't know. Different pros and cons.

* Unit-test can be run in parallel and are faster
* Unit-tests don't need setup and teardown

Cons of unit-tests is that they need a bigger effort on the side of the developer to make them possible, for example injecting the dependencies properly to enable mocking, or lifting side-effects up in the stack trace.

=== How to disagree ===

All rules can be broken. To break a rule, you should reason in terms of risk and the assumptions used in this guide.

'''Assumptions:'''

# Regressions are the biggest technical risk for LimeSurvey the last five years (2021)
# Automated tests are the best risk mitigation technique against regressions

'''Possible disagreement:'''

# A certain piece of code has very low ''probability'' of regressions (maybe we "know" no one else will every touch or change it?)
# Regression in a certain piece of code would have very low ''impact''

== Resources ==

todo

Books, links, videos

Code quality guide

2021-05-05T09:09:09Z

Olle: /* Types of classes */

DRAFT

== Prologue ==

# '''Be risk aware'''. Too good code can be a business risk (slow to write, maybe over-designed). Too sloppy code can also be a business risk (hard to maintain and understand). You have to find a balance that is adapted to the current situation and risk analysis, in which code quality becomes a '''risk mitigation''' technique among others.
# '''Be humble'''. LimeSurvey was made by developers from all over the world, with different age, education and experience. Your code might be read by a completely different team ten years from now, in the same way you are now reading code by developers that no longer work with us, but which work pays our rent.
# '''Performance matters sometimes''', and shouldn't be disregarded completely. In particular, database queries using the ORM and ActiveRecord can be problematic. Some surveys have thousands of questions and hundreds of thousands of responses. Fast response time is also important for a fluid user experience.
# '''It's harder to read code than to write code'''. Don't choose patterns that are easy or fast to write, but that are easy to read.
# Make your code '''communicate intent'''.
# It's easy to forget '''cross-cutting concerns''' like translation and security. Keep a mental note.
# '''Stress affects code quality''' and your risk behaviour. If your stress level is too high to write code with proper quality, take a step back and discuss it with your boss, or you'll push problems to the future.

== Quality ==

The purpose of this guide is to increase the quality of the LimeSurvey code-base. What is quality? Which aspects of quality can be measured? Which kind of company culture gives rise to appropriate code quality?

It's usually easier to get along what is "bad" code than what's "best" code. Blacklist instead of whitelist?

Quality attributes related to code quality:

* Readability
* Testability
* Maintainability
* Performance
* Security
* Reliability

Can not increase all at the same time - performance vs readability.

It's better to avoid emotional language when describing code quality, like "clean" or "dirty". Be precise, objective and suggest solutions.

Idiomatic code is more readable than non-idiomatic code. What's idiomatic depends on which context or domain you work in. We work in PHP and web application development, and have other idioms than in, say, functional or hardware-close programming.

Some code are "hot spots" - changed often. Those parts should require higher quality than other code.

== Risk ==

todo

data loss as most severe risk for LS

usability a business risk - hard to use or understand, people will choose another tool

risks relevant when fixing bugs

risks relevant when adding new features (lack of testing, wrong requirements, scope creep)

risks relevant when refactoring (regressions)

unit tests and QA as risk mitigation

partial deployment, alpha/beta/rc, risk communication

software rot, design pattern rot/grime, software evolution

rot = non-pattern related code

testing by community, bug fixing by community

== Modules ==

There's no inherit module functionality in PHP, but Yii has a module system. Libraries can be seen as a module system.

Examples of implicit modules in LimeSurvey:

* Front-end (survey taking)
* Back-end (survey design)
* Survey theme editing
* Expression manager
* Plugin system

In the future, they need to be separated and implemented more clearly as whatever Yii 3 module system is in use.

Some data models are common for all modules, e.g. surveys and users. Can have a "Common" module for such data.

todo, relation to Yii config system

== Classes ==

* Avoid empty OOP ceremony, like defining getters and setters for all properties. Might as well make them public, ''unless'' they have invariants that need to be upheld, e.g. "this number is always between 1 and 10" or "this string is maximum length 20".
* Almost always avoid static methods. They cannot be mocked. One exception is (possibly) factory methods (Foo::make(...)).
* Inject all dependencies. This will make sure the class can be unit-tested (unit-tests have several benefits over integrity tests - they can be run in parallel and don't require any setup and teardown)
* A second way to achieve testability is to factor out the methods that access the dependencies

todo, state vs behaviour, state vs dependencies

=== OOP design ===

Start from top-down, with domain, behaviour, interaction between objects, database design, pseudo-code if needed. Can also include scenarios, use-cases and UML diagrams.

Object reification - not only domain models, but also domain actions, relations and activities can be objects, e.g. a class ActivateSurvey or ExportSurvey.

Hierarchy depth should be kept reasonable shallow to avoid conflicts between methods, spooky action at a distance. Compare with Yii 3, where controllers no longer inherit anything.

Some people advocate for composition instead of inheritance. Lots of blog posts available for more info.

Multiple inheritance is done with traits in PHP. Use-case: ActiveRecords that support encryption, but not all.

=== Design pattern grime and software evolution ===

Design rot after time - how to keep it tight? (Grime.)

todo

design pattern rot --> lose behaviour relevant for pattern (active record without db connection)

design patter grime --> add behaviour irrelevant for pattern (active record that's also a singleton)

=== State ===

Heuristics to consider but not follow slavishly.

Keep a clear separation between classes with state and classes with no state.

Classes with state should not have dependencies with IO (it's OK to depend on classes in the same application layer, e.g. other DTO classes), and vice versa. ActiveRecord is an example which violates this principle.

class Survey
// Confusion - first params are domain state, last a resource
__construct(id, language, dbConnection)

If a method does not call "this", should it instead be outside the class? A separate class or function, maybe.

todo, elaborate

=== Types of classes ===

Different categories of classes:

* Entity (domain class; has state and validation behaviour)
* Resource (database connection, file, curl, logger; state is in the resource (open, closed))
* Builders (e.g. query builder, HTML message builder)
* Data-transfer object (no behaviour; pass to views to have better documentation and intent than associative arrays)
* Value classes (e.g. Email address to wrap email string around)
* Command object (e.g. SurveyActivator)
* Helper (no state; e.g. QuestionAttributeHelper to bake attributes into different formats used by the views)
* Wrapper

todo, immutability, possible with private properties that are set in the constructor,

todo: command-query separation for classes?

todo: dependencies between layers, dependencies to the framework

todo, pure vs effectful classes

=== Types of classes in LimeSurvey ===

* ActiveRecord, used to communicate with the database, and should not do ''anything'' else
* Controllers, used for glue code; should not contain business-logic (also CLI controllers)
* Helper functions, should be short and obey command-query separation (TODO: Long functions should be separated into command objects or service classes); todo: should not have any dependencies?
* Helper classes, similar to helper functions but have dependencies that need to be mocked during tests; should not have any state
* Service classes, contains logic related to a clear and separate task, like create or import survey
* Question render classes, contains logic related to how questions are rendered (TODO: Need better separation between state and logic and more clear design); similar to widgets
* Plugin classes, using the plugin event system
* Widgets, containing HTML logic for custom HTML widgets
* HTML helpers
* Customizations to the Yii framework by inheritance
* Unit and functional test classes

A couple of classes contain only data, like LsDefaultDataSet.

todo, no difference between state property and dependency property in OOP

=== What is "glue code"? ===

todo

Putting the pieces together, e.g. service class A need data from model B, fetch it and run.

todo, add example

=== "Where do I cut?" ===

Separation of concerns, but which concerns and which type of separation? Command-query (function core, imperative shell) is one type of separation. Other separation between layers, e.g. logic layer and data persistency layer (similar in thought).

Other separation, that one class should have a clear purpose. A design pattern should only implement ''one'' pattern, not multiple, and not half a pattern.

There's a problem with "helper" or "manager" classes that they can grow indefinitely, but might be better than nothing. Example when moving business logic out of ActiveRecord class to a helper class it can sometimes hard to be more specific than "helper".

=== Size ===

A class should have a single and clear purpose; compare with [https://en.wikipedia.org/wiki/SOLID SOLID].

=== Class name ===

* ActiveRecord classes are named after the database table they are bound to, but with singular instead of plural. E.g. table "lime_users" have model "User".
* Command classes are named after what they ''do'' and imperatively, e.g. CreateSurvey
* Helper classes should probably be named as specific as possible when possible, to avoid them from growing too big
* Follow the naming tradition of the framework with regard to controllers, e.g. UserController or UserAdministrationController.
* Class properties of ActiveRecord classes will follow the naming of the database, using underscore instead of camel case (and ActiveRecord classes should have ''no'' other properties than those (excluding the database connection injected by the framework))

== Functions ==

Functions are one of the fundamental building blocks of programming, so it's important to get it right.

Functions that are part of a class are called "methods", if you want to be formal.

Different types of functions in PHP:

* Functions (not attached to a class)
* Methods (attached to class)
* Anonymous functions (does not capture scope automatically)
* Short functions (does capture scope automatically)

I'm using "function" as a word for all types of functions in PHP below.

<hr>

=== Size ===

* A function should be short enough to be completely readable on one screen, approx 60 lines at most
* A function should not have too many arguments; if you have five or more, consider making it a class instead
* If a function is growing too big, it might be better to create a class instead or split it into several functions (if both functions have '''common state''', a class might be better, unless you want to pass around '''explicit state''')

=== Contract ===

* A function has a contract with its surrounding environment:
** Pre-condition: What needs to be true before the function is executed
** Post-condition: What will be true after the function has returned
* The function contract can be checked with assertions (internal invariants) or exceptions (outside world); see below
* Another good way is to use unit-tests to make sure the function's contract remains stable through changes
* The first line in the docblock should be one sentence describing the relation between function arguments and its output<br>Example<br><syntaxhighlight lang="php">
/**
* Creates a random password of length $length (defaults to 12)
* @param int $length
* @return string
*/
function createPassword($lenght = 12)

/**
* Creates an HTML language drop down for survey with id $surveyId, marking $selectedLanguage as selected
* @param int $surveyId
* @param string $selectedLanguage
* @return string <select> HTML
*/
function createLanguageDropdown($surveyId, $selectedLanguage)

</syntaxhighlight>

=== Push side-effects up in the stack trace ===

This one is a bit abstract.

First, what is a '''side-effect'''? In short, it's anything that happens in a function that ''is not'' described by the ''relation'' between function arguments and output.

Another way to phrase it is, that a side-effect is anything that is not always the same for the given input to a function; a function without any side-effects will always return the same result if it gets the same input.

'''Examples:'''

<syntaxhighlight lang="php">
// gT accesses the file system and will return different result depending on what's in the translation files
function gT($sToTranslate, $sEscapeMode = 'html', $sLanguage = null);

// If $sText and $sEscapeMode is always the same, quoteText() will always return the same string.
function quoteText($sText, $sEscapeMode = 'html');
</syntaxhighlight>

A function with no side-effects is called '''pure'''. A function that is guaranteed to always return (no exceptions, no errors, no warnings, no division by zero) is called '''total'''.

It's a good thing if functions in a code-base ''either'' have side-effects, ''or'' return a result. Not both. This is called [https://en.wikipedia.org/wiki/Command%E2%80%93query_separation command-query separation].

Examples of side-effects:

* Database or file access
* Echo, or write to stdout or stderr
* Randomization

Why does this matter? Because side-effects make testing harder! '''If you have side-effects, you cannot create unit tests''', ''unless'' those side-effects can be mocked. If not, you need integrity tests with database setup or more. The more side-effects you have in a function, the more mocking is required to unit test it.

So, one solution to this is to move side-effects higher up in the stack trace, that is, move them to the calling code.

'''Example:'''

<syntaxhighlight lang="php">
function getSurveyInfo(int $surveyid, string $languagecode = '', boolean $force = false): array;
</syntaxhighlight>

Since this function takes $surveyid, we know it will probably query the database. Quering the database is a side-effect, and thus it requires a database scaffold for the test (or mocking, but the database connection is not injected, so there's no way to do it). One simple solution is to lift the side-effect out and pass in a Survey object instead:

<syntaxhighlight lang="php">
function getSurveyInfo(Survey $survey, string $languagecode = '', boolean $force = false): array;
</syntaxhighlight>

Much better! The side-effect of calling the database now happens ''before'' the function call. Now we can either mock a Survey object, or make an imitating stub for our test.

Reading the function body, there is in fact another database access, but since this is a relation to the Survey model, it could easily be moved out too. We've just made a function testable! Hooray!

This principle is rephrased in an architectural settings as [https://github.com/kbilsted/Functional-core-imperative-shell/blob/master/README.md functional core, imperative shell]. This architecture helps you get a good ratio between fast unit tests and slower integrity tests.

Moving side-effects up makes sure we can have a healthy ratio between integrity tests with scripted browser, and unit-tests; maybe around 20-80.

=== Function name ===

* The function name should tell you '''what''' it does; docs should tell you '''why''' (if this information is not obvious). '''How''' is described by the code itself (hopefully, but can in some cases be relevant to document).
* Function name can often be '''verb [+ adjective] + noun''', like "createFieldmap", "quoteText", "getRelativePath"
* Prefix with "is" for boolean functions

todo: difference between create, get, fetch, generate, ...

'''Good examples:'''

* createPassword() - One verb, one noun - clear
* isCaptchaEnabled() - Using "is" signifies it returns boolean; clear purpose
* getFullResponseTable() - Verb, adjective, noun - but is "full" needed here? Is there a non-full version of the same function?
* replaceExpressionCodes() - Pretty good, but it's obvious that more information is needed in the docblock to describe what "replace" means, and what an "expression code" is
* fixCKeditorText() - "fix" is a bit vague, but maybe best there is? Pray that docblock contains information!

'''Bad examples:'''

* languageDropdown() - No verb, doesn't tell you what it does
* rmdirr() - Two r's, looks like a typo, but the last "r" actually means "recursive"! Better: rmdir($recursive = false), rmdir or removeFolder.
* CSVUnquote() - Is CSV really the namespace? Why is the verb the second word?
* incompleteAnsFilterState() - One verb, but in the middle, or is "filter state" a noun?; why abbreviate "answer" to "ans"?
* reverseTranslateFieldNames() - Two verbs - did author mean "reverseTranslatedFieldNames"? Or "reverse and translate"? If so, it should be two functions, one for reverse and one for translate
* checkUploadedFileSizeAndRenderJson() - If you have an "and" in the function name, you should consider splitting it into two functions

'''Controversial'''

* gT() - An exception to descriptive function names; since this is used everywhere, the minimal name is motivated; maybe even name it "t()"? Still hard to read for someone who just started? But Yii uses t() too? Other frameworks use double underscore (Wordpress, Laravel) as function name.

<hr>

=== Function filename and namespace ===

If your function has dependencies or side-effects, it should be put into a class instead, in which the dependencies can be injected. Another alternative is to put the dependencies as argument in the function, although this muffles the relationship between input and output. Again, this is to increase testability.

Keep in mind that functions outside classes cannot be mocked, so only use them when you ''know'' you won't need to mock them.

todo, autoloading of functions and folder location

=== Assertions ===

NB: This is not assertions as used in unit-tests, but assertions as used to check invariants in production code.

Assertions can be used for mental checks. They are only used for internal logic - failed assertions are not supposed to be seen by the end user. For interaction with the outside world, like database or browser, exceptions should be used instead.

Assertions can be disabled in production mode and have then no runtime cost (since PHP 7).

'''Example:'''

<syntaxhighlight lang="php">
/**
* Translation helper function
*
* @param string $sToTranslate
* @param string $sEscapeMode Valid values are html (this is the default, js and unescaped)
* @param string $sLanguage
* @return string
*/
function gT($sToTranslate, $sEscapeMode = 'html', $sLanguage = null)
{
assert(is_string($sToTranslate));
assert(strlen($sToTranslate) > 0);
assert($sEscapeMode === 'html' || $sEscapeMode === 'js' || $sEscapeMode === 'unescaped');
return quoteText(Yii::t('', $sToTranslate, array(), null, $sLanguage), $sEscapeMode);
}
</syntaxhighlight>

<hr>

=== Exceptions ===

todo

todo: exception hierarchy

todo: what can be repaired after exception? transaction rollback

* Exceptions are used to check inputs from the outside world (browser, database, file system)
* Don't use exceptions for control flow, only when fatal errors happen that make further execution impossible
* Exceptions should have clear error messages that make them ''actionable'' - there should be a clear "next step" for the user or developer
* Never, ever, do an empty catch-block

==== Alternatives to exceptions ====

Some people consider exceptions being a hidden form of "goto" which confuses the control flow of the program. They propose different other solutions:

* Return a tuple, like <code>[$result, $errorMessage]</code> where $errorMessage is null at success
* Return <code>null</code> at failure
* Tagged union result type (not yet possible in latest PHP)
* Result object

The con being that you have to manually propagate the error, where an exception can happen from anywhere in the stack trace without any other function knowing about it.

=== If-statements ===

If-statements should not be too long or hard to understand. If they are, consider factor out the checks into separate functions.

<syntaxhighlight lang="php">
if ((empty($instance->oOptions->{$attribute}))
|| (
!empty($instance->oOptions->{$attribute})
&& (
$instance->oOptions->{$attribute} === 'inherit'
|| $instance->oOptions->{$attribute} === 'I'
// NB: Do NOT use === here, it won't work with Postgresql.
|| $instance->oOptions->{$attribute} == '-1'
)
)
) {
</syntaxhighlight>

Can be shortened by factoring out method <code>isInherit</code>:

<syntaxhighlight lang="php">
if (empty($instance->options->{$attribute})
|| $this->isInherit($instance-options->{$attribute})) {
}
/**
* Returns true if $value is set to inherit
* @param mixed|null $value
* @return boolean
*/
public function isInherit($value) {
return !empty($value)
&& (
$value === 'inherit'
|| $value === 'I'
// NB: Do NOT use === here, it won't work with Postgresql.
|| $value == '-1'
);
}
</syntaxhighlight>

And one more time by using a variable for the value:

<syntaxhighlight lang="php">
$value = $instance->options->{$attribute};
if (empty($value) || $this->isInherit($value)) {
}
</syntaxhighlight>

More clear, right? "If it's empty or set to inherit, do this and that."

=== Variables ===

Descriptive naming.

* Follow PSR-12 - no underscore, use camelCaseLikeThis
* Variables of ActiveRecord classes can have same name as the class, like "$survey" or "$question"
* Add -s for plural when it's a list of items: "$surveys", "$questions"
* Never include "array" or "list" in variable names - using plural is enough (for lists, not for associative arrays - see below)
* The ''context'' of the function helps with variable naming, e..g "$name" might be fine in a function about questions; this is extra helpful when functions are short!
* When a function is short, it's much easier to figure out variable meaning based on context
* $qid, $gid, and $sid are so established in the code-base that they could be considered OK
* The -data suffix means "blob of stuff", only use it when needed, like with $viewData
* Use $result when baking a return value; add its exact type as @var annotation (worst possible name, acceptable but anything with more meaning is better)

Not so good:

<syntaxhighlight lang="php">
$result = LabelSet::model()->findAll();
</syntaxhighlight>

Better with model name and -s for plural:

<syntaxhighlight lang="php">
$labelSets = LabelSet::model()->findAll();
</syntaxhighlight>

* Do not use Hungarian notation (prefix with "type"), but instead <code>/** @var */</code> annotations - these can be checked automatically and will then be enforced to be correct, unlike Hungarian notation which can "rot"

<syntaxhighlight lang="php">
/** string[] An array of strings with 0-n elements */
$allFields = [];
</syntaxhighlight>

Psalm can infer types if the function documentation is enough. The strictness can be adjusted. Not all variables will need @var annotation, the tool will warn you when it's confused.

* Data that is sent to views as associative arrays will be:

<syntaxhighlight lang="php">
/** @var array Can be basically anything :( Better would be data-transfer objects or more precise notation */
$data = [];
// Maybe more clear as $viewData? Discuss.
</syntaxhighlight>

You can be more precise when you specify which type of array you're writing:

<syntaxhighlight lang="php">
/** @var array<string, string> This means the array key is string, and the array value is also string */
$data = [];
$data['name'] = 'Olle';
$data['occupation'] = 'Developer';
$data['age'] = 38; // ERROR! Value must be string.
</syntaxhighlight>

For more info about array type notation, see the [https://psalm.dev/docs/annotating_code/type_syntax/array_types/ Psalm documentation].

Some smaller examples:

<syntaxhighlight lang="php">
$theme = App()->request->getPost('theme'); // Should be $themeType - $theme looks like a model/AR
$gridid === 'questionthemes-grid'; // Should be $gridId with capital "I", since it's two words in English
$delete = Yii::app()->request->getParam('delete'); // Tuff one - $delete is ok? Thoughts?
$files = json_decode(stripslashes($sJSON), true); // $file is a resource, $files an array of resources, this is $fileData perhaps?
$valid_extensions_array = explode(",", $aAttributes['allowed_filetypes']); // Should be $validExtensionTypes
$language = Yii::app()->session['survey_' . $surveyid]['s_lang']; // TODO: Should this be a value class? Then Language::make(...);
$surveyInfo = getSurveyInfo($surveyId, $language); // OK, BUT should be a separate DTO!
$fieldMap = createFieldMap($survey, 'short', false, false, $language); // Same, make a DTO
$cquestions = array(); // What's "c"? Method name is getChildQuestions and $questions is an argument - better with $childQuestions?
</syntaxhighlight>

Links:

[https://www.approxion.com/capital-offenses-how-to-handle-abbreviations-in-camelcase/ How to Handle Abbreviations in CamelCase]

[https://stackoverflow.com/questions/15526107/acronyms-in-camelcase Acronyms in CamelCase]

=== Looping ===

* The bodies of foreach-loops are often a good candidate to factor out into separate functions.

'''Example:'''

<syntaxhighlight lang="php">
foreach ($questions as $question) {
processQuestion($question);
}
</syntaxhighlight>

Note the variable naming from plural to singular.

* Loop indexing should be named i, j, k etc.

'''Example:'''

<syntaxhighlight lang="php">
for ($i = 0; $i < $length; $i++) {
for ($j = 0; $j < $otherLength; $j++) {
// ...
}
}
</syntaxhighlight>

<hr>

=== Function composition ===

todo, "doThisAndThat" --> "doThis(doThat())"

=== Cases ===

<syntaxhighlight lang="php">
/**
* This function generates an array containing the fieldcode, and matching data in the same order as the activate script
*
* @param Survey $survey Survey ActiveRecord model
* @param string $style 'short' (default) or 'full' - full creates extra information like default values
* @param boolean $force_refresh - Forces to really refresh the array, not just take the session copy
* @param bool|int $questionid Limit to a certain qid only (for question preview) - default is false
* @param string $sLanguage The language to use
* @param array $aDuplicateQIDs
* @return array
*/
function createFieldMap($survey, $style = 'short', $force_refresh = false, $questionid = false, $sLanguage = '', &$aDuplicateQIDs = array())
</syntaxhighlight>

'''Good:'''

* Name is verb and noun
* Each argument is documented (almost)

'''Bad:'''

* Returns "array", which can be anything. A separate class for "Fieldmap" would be better.
* Not clear if it should be "createFieldMap" or "createFieldmap" - is "fieldmap" one word or two?
* Very many boolean arguments. Should probably be a class with methods like <code>$fieldmapCreator->setForceRefresh(true);</code> instead.
* Too long.
* Doesn't elaborate on what "fieldmap" really is, and does not link to any documentation about it.
* Access super-global, which makes it hard to test. Should instead return a data-transfer object, like:<br><syntaxhighlight lang="php">
$_SESSION['fieldmap'] = createFieldMap(...);
</syntaxhighlight>
* Has no test
* Mixes Hungarian notation with non-Hungarian notation in the argument list

== Defensive programming and error handling ==

todo

* '''Fail hard, fail early'''. The earlier the program crashes when something is wrong, the lower is the probability that you'll end up with corrupt data in the database that will later require manual labor to correct.
* Fail with '''actionable information'''
* Check input to functions and throw <code>InvalidArgumentException</code> if it violates the function's pre-conditions
* Use assert for class-internal invariants
* Use assert to make assumptions explicit for the reader

== Documentation ==

=== PHPDoc ===

* All functions must have a proper docblock
* The first line of the docblock should describe the relation between ''all'' the input arguments and the output of the function in a single sentence
* Each parameter must have the correct type
* Don't use <code>array</code> as type if it's a list of object - instead, use <code>[]</code> like so: <code>Survey[]</code> for a list of surveys

=== Technical documentation ===

todo, UML, scenarios, use-cases

== The PHP of yesterday ==

Old idioms and habits that should be abandoned.

* Don't use associative arrays, almost never. Data-transfer objects have multiple benefits: they are clearly structured, can be documented, can enforce invariants. There's ''no'' performance overhead of objects compared to arrays in modern PHP.
* Objects are already passed by reference; arrays are value types
* Use <code>[]</code> instead of <code>array()</code>
* Hungarian notation was useful before static analysis existed for PHP. These days it's better to use something that can be checked automatically: docblock @param and inline @var annotations.

== The PHP of tomorrow ==

todo

Union tags

Short functions

Match expressions

== Security ==

todo

XSS

Database injection

Permissions and roles

== Performance ==

todo

Loading too many rows into PHP models

== Testing ==

todo

QA

PHPUnit

TDD

Mocks, can't mock functions, static methods, mocking as a DSL, PHPUnit mocking tools

Pure functions, referential transparency, side-effects

Unit, functional, integration

Don't test the framework; don't test PHP

Makes sure the function or class lives up to its specification; make sure it will ''always'' live up to its specification, even in the future, to avoid regressions.

== Static analysis ==

<code>php -l</code>, CodeSniffer, Mess Detector, Psalm

== Database design ==

todo

== JavaScript ==

todo

classes, functions, components, tests

== CSS ==

todo

== HTML ==

todo

== Feedback ==

=== "Why do I have to refactor code that works?" ===

todo, Sadly, it's not enough for the code to live up to the current specification and requirements, it must also be protected against future changes, regressions. Adding tests is the best way for this. Lots of people might read and change the LimeSurvey code the next 5-10 years. The test suite creates a security layer to make sure the specification is fulfilled even as the code changes.

Tests are not a magical solution, however. It does not protect us against other degradation of the code quality, like classes gaining too much responsibility (too many methods, unrelated methods, too many properties).

=== "What's the correct ratio between integrity tests and unit tests?" ===

todo, Don't know. Different pros and cons.

* Unit-test can be run in parallel and are faster
* Unit-tests don't need setup and teardown

Cons of unit-tests is that they need a bigger effort on the side of the developer to make them possible, for example injecting the dependencies properly to enable mocking, or lifting side-effects up in the stack trace.

=== How to disagree ===

All rules can be broken. To break a rule, you should reason in terms of risk and the assumptions used in this guide.

'''Assumptions:'''

# Regressions are the biggest technical risk for LimeSurvey the last five years (2021)
# Automated tests are the best risk mitigation technique against regressions

'''Possible disagreement:'''

# A certain piece of code has very low ''probability'' of regressions (maybe we "know" no one else will every touch or change it?)
# Regression in a certain piece of code would have very low ''impact''

== Resources ==

todo

Books, links, videos

Code quality guide

2021-04-30T11:46:10Z

Olle: /* Assertions */

DRAFT

== Prologue ==

# '''Be risk aware'''. Too good code can be a business risk (slow to write, maybe over-designed). Too sloppy code can also be a business risk (hard to maintain and understand). You have to find a balance that is adapted to the current situation and risk analysis, in which code quality becomes a '''risk mitigation''' technique among others.
# '''Be humble'''. LimeSurvey was made by developers from all over the world, with different age, education and experience. Your code might be read by a completely different team ten years from now, in the same way you are now reading code by developers that no longer work with us, but which work pays our rent.
# '''Performance matters sometimes''', and shouldn't be disregarded completely. In particular, database queries using the ORM and ActiveRecord can be problematic. Some surveys have thousands of questions and hundreds of thousands of responses. Fast response time is also important for a fluid user experience.
# '''It's harder to read code than to write code'''. Don't choose patterns that are easy or fast to write, but that are easy to read.
# Make your code '''communicate intent'''.
# It's easy to forget '''cross-cutting concerns''' like translation and security. Keep a mental note.
# '''Stress affects code quality''' and your risk behaviour. If your stress level is too high to write code with proper quality, take a step back and discuss it with your boss, or you'll push problems to the future.

== Quality ==

The purpose of this guide is to increase the quality of the LimeSurvey code-base. What is quality? Which aspects of quality can be measured? Which kind of company culture gives rise to appropriate code quality?

It's usually easier to get along what is "bad" code than what's "best" code. Blacklist instead of whitelist?

Quality attributes related to code quality:

* Readability
* Testability
* Maintainability
* Performance
* Security
* Reliability

Can not increase all at the same time - performance vs readability.

It's better to avoid emotional language when describing code quality, like "clean" or "dirty". Be precise, objective and suggest solutions.

Idiomatic code is more readable than non-idiomatic code. What's idiomatic depends on which context or domain you work in. We work in PHP and web application development, and have other idioms than in, say, functional or hardware-close programming.

Some code are "hot spots" - changed often. Those parts should require higher quality than other code.

== Risk ==

todo

data loss as most severe risk for LS

usability a business risk - hard to use or understand, people will choose another tool

risks relevant when fixing bugs

risks relevant when adding new features (lack of testing, wrong requirements, scope creep)

risks relevant when refactoring (regressions)

unit tests and QA as risk mitigation

partial deployment, alpha/beta/rc, risk communication

software rot, design pattern rot/grime, software evolution

rot = non-pattern related code

testing by community, bug fixing by community

== Modules ==

There's no inherit module functionality in PHP, but Yii has a module system. Libraries can be seen as a module system.

Examples of implicit modules in LimeSurvey:

* Front-end (survey taking)
* Back-end (survey design)
* Survey theme editing
* Expression manager
* Plugin system

In the future, they need to be separated and implemented more clearly as whatever Yii 3 module system is in use.

Some data models are common for all modules, e.g. surveys and users. Can have a "Common" module for such data.

todo, relation to Yii config system

== Classes ==

todo

* Avoid empty OOP ceremony, like defining getters and setters for all properties. Might as well make them public, ''unless'' they have invariants that need to be upheld, e.g. "this number is always between 1 and 10" or "this string is maximum length 20".
* Almost always avoid static methods. They cannot be mocked. One exception is (possibly) factory methods (Foo::make(...)).
* Inject all dependencies. This will make sure the class can be unit-tested (unit-tests have several benefits over integrity tests - they can be run in parallel and don't require any setup and teardown)
* A second way to achieve testability is to factor out the methods that access the dependencies

todo, state vs behaviour, state vs dependencies

=== OOP design ===

todo

Start from top-down, with domain, behaviour, interaction between objects, database design, pseudo-code if needed. Can also include scenarios, use-cases and UML diagrams.

Object reification - not only domain models, but also domain actions, relations and activities can be objects, e.g. a class ActivateSurvey or ExportSurvey.

Hierarchy depth.

Inheritance vs composition.

Multiple inheritance is done with traits. Use-case: ActiveRecords that support encryption, but not all.

=== Design pattern grime and software evolution ===

Design rot after time - how to keep it tight? (Grime.)

=== State ===

Keep a clear separation between classes with state and classes with no state.

todo, elaborate

=== Types of classes ===

Different categories of classes:

* Builders (e.g. query builder)
* Data-transfer object (no behaviour; pass to views to have better documentation and intent than associative arrays)
* Value classes (e.g. Email to wrap email string around)
* Command object (e.g. SurveyActivator)
* Helper (no state; e.g. QuestionAttributeHelper to bake attributes into different formats used by the views)
* Wrapper (also no state; e.g IOWrapper, to be able to mock file access)

todo, immutability, possible with private properties that are set in the constructor,

todo: command-query separation for classes?

todo: dependencies between layers, dependencies to the framework

todo, pure vs effectful classes

=== Types of classes in LimeSurvey ===

* ActiveRecord, used to communicate with the database, and should not do ''anything'' else
* Controllers, used for glue code; should not contain business-logic
* Commands, same as controllers but from CLI
* Helper functions, should be short and obey command-query separation (TODO: Long functions should be separated into command objects or service classes); todo: should not have any dependencies?
* Helper classes, similar to helper functions but have dependencies that need to be mocked during tests; should not have any state
* Service classes, contains logic related to a clear and separate task, like create or import survey
* Question render classes, contains logic related to how questions are rendered (TODO: Need better separation between state and logic and more clear design); similar to widgets
* Plugin classes, using the plugin event system
* Widgets, containing HTML logic for custom HTML widgets
* Customizations to the Yii framework by inheritance
* Unit and functional test classes

A couple of classes contain only data, like LsDefaultDataSet.

todo, no difference between state property and dependency property in OOP

=== What is "glue code"? ===

todo

Putting the pieces together, e.g. service class A need data from model B, fetch it and run.

todo, add example

=== "Where do I cut?" ===

Separation of concerns, but which concerns and which type of separation?

=== Size ===

A class should have a single and clear purpose; compare with [https://en.wikipedia.org/wiki/SOLID SOLID].

=== Class name ===

* ActiveRecord classes are named after the database table they are bound to, but with singular instead of plural. E.g. table "lime_users" have model "User".
* Services classes are named after what they ''do'', e.g. SurveyCreator
* Helper classes should probably be named as specific as possible when possible, to avoid them from growing too big
* Follow the naming tradition of the framework with regard to controllers, e.g. UserController or UserAdministrationController.

== Functions ==

Functions are one of the fundamental building blocks of programming, so it's important to get it right.

Functions that are part of a class are called "methods", if you want to be formal.

Different types of functions in PHP:

* Functions (not attached to a class)
* Methods (attached to class)
* Anonymous functions (does not capture scope automatically)
* Short functions (does capture scope automatically)

I'm using "function" as a word for all types of functions in PHP below.

<hr>

=== Size ===

* A function should be short enough to be completely readable on one screen, approx 60 lines at most
* A function should not have too many arguments; if you have five or more, consider making it a class instead
* If a function is growing too big, it might be better to create a class instead or split it into several functions (if both functions have '''common state''', a class might be better, unless you want to pass around '''explicit state''')

=== Contract ===

* A function has a contract with its surrounding environment:
** Pre-condition: What needs to be true before the function is executed
** Post-condition: What will be true after the function has returned
* The function contract can be checked with assertions (internal invariants) or exceptions (outside world); see below
* Another good way is to use unit-tests to make sure the function's contract remains stable through changes
* The first line in the docblock should be one sentence describing the relation between function arguments and its output<br>Example<br><syntaxhighlight lang="php">
/**
* Creates a random password of length $length (defaults to 12)
* @param int $length
* @return string
*/
function createPassword($lenght = 12)

/**
* Creates an HTML language drop down for survey with id $surveyId, marking $selectedLanguage as selected
* @param int $surveyId
* @param string $selectedLanguage
* @return string <select> HTML
*/
function createLanguageDropdown($surveyId, $selectedLanguage)

</syntaxhighlight>

=== Push side-effects up in the stack trace ===

This one is a bit abstract.

First, what is a '''side-effect'''? In short, it's anything that happens in a function that ''is not'' described by the ''relation'' between function arguments and output.

Another way to phrase it is, that a side-effect is anything that is not always the same for the given input to a function; a function without any side-effects will always return the same result if it gets the same input.

'''Examples:'''

<syntaxhighlight lang="php">
// gT accesses the file system and will return different result depending on what's in the translation files
function gT($sToTranslate, $sEscapeMode = 'html', $sLanguage = null);

// If $sText and $sEscapeMode is always the same, quoteText() will always return the same string.
function quoteText($sText, $sEscapeMode = 'html');
</syntaxhighlight>

A function with no side-effects is called '''pure'''. A function that is guaranteed to always return (no exceptions, no errors, no warnings, no division by zero) is called '''total'''.

It's a good thing if functions in a code-base ''either'' have side-effects, ''or'' return a result. Not both. This is called [https://en.wikipedia.org/wiki/Command%E2%80%93query_separation command-query separation].

Examples of side-effects:

* Database or file access
* Echo, or write to stdout or stderr
* Randomization

Why does this matter? Because side-effects make testing harder! '''If you have side-effects, you cannot create unit tests''', ''unless'' those side-effects can be mocked. If not, you need integrity tests with database setup or more. The more side-effects you have in a function, the more mocking is required to unit test it.

So, one solution to this is to move side-effects higher up in the stack trace, that is, move them to the calling code.

'''Example:'''

<syntaxhighlight lang="php">
function getSurveyInfo(int $surveyid, string $languagecode = '', boolean $force = false): array;
</syntaxhighlight>

Since this function takes $surveyid, we know it will probably query the database. Quering the database is a side-effect, and thus it requires a database scaffold for the test (or mocking, but the database connection is not injected, so there's no way to do it). One simple solution is to lift the side-effect out and pass in a Survey object instead:

<syntaxhighlight lang="php">
function getSurveyInfo(Survey $survey, string $languagecode = '', boolean $force = false): array;
</syntaxhighlight>

Much better! The side-effect of calling the database now happens ''before'' the function call. Now we can either mock a Survey object, or make an imitating stub for our test.

Reading the function body, there is in fact another database access, but since this is a relation to the Survey model, it could easily be moved out too. We've just made a function testable! Hooray!

This principle is rephrased in an architectural settings as [https://github.com/kbilsted/Functional-core-imperative-shell/blob/master/README.md functional core, imperative shell]. This architecture helps you get a good ratio between fast unit tests and slower integrity tests.

Moving side-effects up makes sure we can have a healthy ratio between integrity tests with scripted browser, and unit-tests; maybe around 20-80.

=== Function name ===

* The function name should tell you '''what''' it does; docs should tell you '''why''' (if this information is not obvious). '''How''' is described by the code itself (hopefully, but can in some cases be relevant to document).
* Function name can often be '''verb [+ adjective] + noun''', like "createFieldmap", "quoteText", "getRelativePath"
* Prefix with "is" for boolean functions

todo: difference between create, get, fetch, generate, ...

'''Good examples:'''

* createPassword() - One verb, one noun - clear
* isCaptchaEnabled() - Using "is" signifies it returns boolean; clear purpose
* getFullResponseTable() - Verb, adjective, noun - but is "full" needed here? Is there a non-full version of the same function?
* replaceExpressionCodes() - Pretty good, but it's obvious that more information is needed in the docblock to describe what "replace" means, and what an "expression code" is
* fixCKeditorText() - "fix" is a bit vague, but maybe best there is? Pray that docblock contains information!

'''Bad examples:'''

* languageDropdown() - No verb, doesn't tell you what it does
* rmdirr() - Two r's, looks like a typo, but the last "r" actually means "recursive"! Better: rmdir($recursive = false), rmdir or removeFolder.
* CSVUnquote() - Is CSV really the namespace? Why is the verb the second word?
* incompleteAnsFilterState() - One verb, but in the middle, or is "filter state" a noun?; why abbreviate "answer" to "ans"?
* reverseTranslateFieldNames() - Two verbs - did author mean "reverseTranslatedFieldNames"? Or "reverse and translate"? If so, it should be two functions, one for reverse and one for translate
* checkUploadedFileSizeAndRenderJson() - If you have an "and" in the function name, you should consider splitting it into two functions

'''Controversial'''

* gT() - An exception to descriptive function names; since this is used everywhere, the minimal name is motivated; maybe even name it "t()"? Still hard to read for someone who just started? But Yii uses t() too? Other frameworks use double underscore (Wordpress, Laravel) as function name.

<hr>

=== Function filename and namespace ===

If your function has dependencies or side-effects, it should be put into a class instead, in which the dependencies can be injected. Another alternative is to put the dependencies as argument in the function, although this muffles the relationship between input and output. Again, this is to increase testability.

Keep in mind that functions outside classes cannot be mocked, so only use them when you ''know'' you won't need to mock them.

todo, autoloading of functions and folder location

=== Assertions ===

NB: This is not assertions as used in unit-tests, but assertions as used to check invariants in production code.

Assertions can be used for mental checks. They are only used for internal logic - failed assertions are not supposed to be seen by the end user. For interaction with the outside world, like database or browser, exceptions should be used instead.

Assertions can be disabled in production mode and have then no runtime cost (since PHP 7).

'''Example:'''

<syntaxhighlight lang="php">
/**
* Translation helper function
*
* @param string $sToTranslate
* @param string $sEscapeMode Valid values are html (this is the default, js and unescaped)
* @param string $sLanguage
* @return string
*/
function gT($sToTranslate, $sEscapeMode = 'html', $sLanguage = null)
{
assert(is_string($sToTranslate));
assert(strlen($sToTranslate) > 0);
assert($sEscapeMode === 'html' || $sEscapeMode === 'js' || $sEscapeMode === 'unescaped');
return quoteText(Yii::t('', $sToTranslate, array(), null, $sLanguage), $sEscapeMode);
}
</syntaxhighlight>

<hr>

=== Exceptions ===

todo

todo: exception hierarchy

todo: what can be repaired after exception? transaction rollback

* Exceptions are used to check inputs from the outside world (browser, database, file system)
* Don't use exceptions for control flow, only when fatal errors happen that make further execution impossible
* Exceptions should have clear error messages that make them ''actionable'' - there should be a clear "next step" for the user or developer
* Never, ever, do an empty catch-block

==== Alternatives to exceptions ====

Some people consider exceptions being a hidden form of "goto" which confuses the control flow of the program. They propose different other solutions:

* Return a tuple, like <code>[$result, $errorMessage]</code> where $errorMessage is null at success
* Return <code>null</code> at failure
* Tagged union result type (not yet possible in latest PHP)
* Result object

The con being that you have to manually propagate the error, where an exception can happen from anywhere in the stack trace without any other function knowing about it.

=== If-statements ===

If-statements should not be too long or hard to understand. If they are, consider factor out the checks into separate functions.

<syntaxhighlight lang="php">
if ((empty($instance->oOptions->{$attribute}))
|| (
!empty($instance->oOptions->{$attribute})
&& (
$instance->oOptions->{$attribute} === 'inherit'
|| $instance->oOptions->{$attribute} === 'I'
// NB: Do NOT use === here, it won't work with Postgresql.
|| $instance->oOptions->{$attribute} == '-1'
)
)
) {
</syntaxhighlight>

Can be shortened by factoring out method <code>isInherit</code>:

<syntaxhighlight lang="php">
if (empty($instance->options->{$attribute})
|| $this->isInherit($instance-options->{$attribute})) {
}
/**
* Returns true if $value is set to inherit
* @param mixed|null $value
* @return boolean
*/
public function isInherit($value) {
return !empty($value)
&& (
$value === 'inherit'
|| $value === 'I'
// NB: Do NOT use === here, it won't work with Postgresql.
|| $value == '-1'
);
}
</syntaxhighlight>

And one more time by using a variable for the value:

<syntaxhighlight lang="php">
$value = $instance->options->{$attribute};
if (empty($value) || $this->isInherit($value)) {
}
</syntaxhighlight>

More clear, right? "If it's empty or set to inherit, do this and that."

=== Variables ===

Descriptive naming.

* Follow PSR-12 - no underscore, use camelCaseLikeThis
* Variables of ActiveRecord classes can have same name as the class, like "$survey" or "$question"
* Add -s for plural when it's a list of items: "$surveys", "$questions"
* Never include "array" or "list" in variable names - using plural is enough (for lists, not for associative arrays - see below)
* The ''context'' of the function helps with variable naming, e..g "$name" might be fine in a function about questions; this is extra helpful when functions are short!
* When a function is short, it's much easier to figure out variable meaning based on context
* $qid, $gid, and $sid are so established in the code-base that they could be considered OK
* The -data suffix means "blob of stuff", only use it when needed, like with $viewData
* Use $result when baking a return value; add its exact type as @var annotation (worst possible name, acceptable but anything with more meaning is better)

Not so good:

<syntaxhighlight lang="php">
$result = LabelSet::model()->findAll();
</syntaxhighlight>

Better with model name and -s for plural:

<syntaxhighlight lang="php">
$labelSets = LabelSet::model()->findAll();
</syntaxhighlight>

* Do not use Hungarian notation (prefix with "type"), but instead <code>/** @var */</code> annotations - these can be checked automatically and will then be enforced to be correct, unlike Hungarian notation which can "rot"

<syntaxhighlight lang="php">
/** string[] An array of strings with 0-n elements */
$allFields = [];
</syntaxhighlight>

Psalm can infer types if the function documentation is enough. The strictness can be adjusted. Not all variables will need @var annotation, the tool will warn you when it's confused.

* Data that is sent to views as associative arrays will be:

<syntaxhighlight lang="php">
/** @var array Can be basically anything :( Better would be data-transfer objects or more precise notation */
$data = [];
// Maybe more clear as $viewData? Discuss.
</syntaxhighlight>

You can be more precise when you specify which type of array you're writing:

<syntaxhighlight lang="php">
/** @var array<string, string> This means the array key is string, and the array value is also string */
$data = [];
$data['name'] = 'Olle';
$data['occupation'] = 'Developer';
$data['age'] = 38; // ERROR! Value must be string.
</syntaxhighlight>

For more info about array type notation, see the [https://psalm.dev/docs/annotating_code/type_syntax/array_types/ Psalm documentation].

Some smaller examples:

<syntaxhighlight lang="php">
$theme = App()->request->getPost('theme'); // Should be $themeType - $theme looks like a model/AR
$gridid === 'questionthemes-grid'; // Should be $gridId with capital "I", since it's two words in English
$delete = Yii::app()->request->getParam('delete'); // Tuff one - $delete is ok? Thoughts?
$files = json_decode(stripslashes($sJSON), true); // $file is a resource, $files an array of resources, this is $fileData perhaps?
$valid_extensions_array = explode(",", $aAttributes['allowed_filetypes']); // Should be $validExtensionTypes
$language = Yii::app()->session['survey_' . $surveyid]['s_lang']; // TODO: Should this be a value class? Then Language::make(...);
$surveyInfo = getSurveyInfo($surveyId, $language); // OK, BUT should be a separate DTO!
$fieldMap = createFieldMap($survey, 'short', false, false, $language); // Same, make a DTO
$cquestions = array(); // What's "c"? Method name is getChildQuestions and $questions is an argument - better with $childQuestions?
</syntaxhighlight>

Links:

[https://www.approxion.com/capital-offenses-how-to-handle-abbreviations-in-camelcase/ How to Handle Abbreviations in CamelCase]

[https://stackoverflow.com/questions/15526107/acronyms-in-camelcase Acronyms in CamelCase]

=== Looping ===

* The bodies of foreach-loops are often a good candidate to factor out into separate functions.

'''Example:'''

<syntaxhighlight lang="php">
foreach ($questions as $question) {
processQuestion($question);
}
</syntaxhighlight>

Note the variable naming from plural to singular.

* Loop indexing should be named i, j, k etc.

'''Example:'''

<syntaxhighlight lang="php">
for ($i = 0; $i < $length; $i++) {
for ($j = 0; $j < $otherLength; $j++) {
// ...
}
}
</syntaxhighlight>

<hr>

=== Function composition ===

todo, "doThisAndThat" --> "doThis(doThat())"

=== Cases ===

<syntaxhighlight lang="php">
/**
* This function generates an array containing the fieldcode, and matching data in the same order as the activate script
*
* @param Survey $survey Survey ActiveRecord model
* @param string $style 'short' (default) or 'full' - full creates extra information like default values
* @param boolean $force_refresh - Forces to really refresh the array, not just take the session copy
* @param bool|int $questionid Limit to a certain qid only (for question preview) - default is false
* @param string $sLanguage The language to use
* @param array $aDuplicateQIDs
* @return array
*/
function createFieldMap($survey, $style = 'short', $force_refresh = false, $questionid = false, $sLanguage = '', &$aDuplicateQIDs = array())
</syntaxhighlight>

'''Good:'''

* Name is verb and noun
* Each argument is documented (almost)

'''Bad:'''

* Returns "array", which can be anything. A separate class for "Fieldmap" would be better.
* Not clear if it should be "createFieldMap" or "createFieldmap" - is "fieldmap" one word or two?
* Very many boolean arguments. Should probably be a class with methods like <code>$fieldmapCreator->setForceRefresh(true);</code> instead.
* Too long.
* Doesn't elaborate on what "fieldmap" really is, and does not link to any documentation about it.
* Access super-global, which makes it hard to test. Should instead return a data-transfer object, like:<br><syntaxhighlight lang="php">
$_SESSION['fieldmap'] = createFieldMap(...);
</syntaxhighlight>
* Has no test
* Mixes Hungarian notation with non-Hungarian notation in the argument list

== Defensive programming and error handling ==

todo

* '''Fail hard, fail early'''. The earlier the program crashes when something is wrong, the lower is the probability that you'll end up with corrupt data in the database that will later require manual labor to correct.
* Fail with '''actionable information'''
* Check input to functions and throw <code>InvalidArgumentException</code> if it violates the function's pre-conditions
* Use assert for class-internal invariants
* Use assert to make assumptions explicit for the reader

== Documentation ==

=== PHPDoc ===

* All functions must have a proper docblock
* The first line of the docblock should describe the relation between ''all'' the input arguments and the output of the function in a single sentence
* Each parameter must have the correct type
* Don't use <code>array</code> as type if it's a list of object - instead, use <code>[]</code> like so: <code>Survey[]</code> for a list of surveys

=== Technical documentation ===

todo, UML, scenarios, use-cases

== The PHP of yesterday ==

Old idioms and habits that should be abandoned.

* Don't use associative arrays, almost never. Data-transfer objects have multiple benefits: they are clearly structured, can be documented, can enforce invariants. There's ''no'' performance overhead of objects compared to arrays in modern PHP.
* Objects are already passed by reference; arrays are value types
* Use <code>[]</code> instead of <code>array()</code>
* Hungarian notation was useful before static analysis existed for PHP. These days it's better to use something that can be checked automatically: docblock @param and inline @var annotations.

== The PHP of tomorrow ==

todo

Union tags

Short functions

Match expressions

== Security ==

todo

XSS

Database injection

Permissions and roles

== Performance ==

todo

Loading too many rows into PHP models

== Testing ==

todo

QA

PHPUnit

TDD

Mocks, can't mock functions, static methods, mocking as a DSL, PHPUnit mocking tools

Pure functions, referential transparency, side-effects

Unit, functional, integration

Don't test the framework; don't test PHP

Makes sure the function or class lives up to its specification; make sure it will ''always'' live up to its specification, even in the future, to avoid regressions.

== Static analysis ==

<code>php -l</code>, CodeSniffer, Mess Detector, Psalm

== Database design ==

todo

== JavaScript ==

todo

classes, functions, components, tests

== CSS ==

todo

== HTML ==

todo

== Feedback ==

=== "Why do I have to refactor code that works?" ===

todo, Sadly, it's not enough for the code to live up to the current specification and requirements, it must also be protected against future changes, regressions. Adding tests is the best way for this. Lots of people might read and change the LimeSurvey code the next 5-10 years. The test suite creates a security layer to make sure the specification is fulfilled even as the code changes.

Tests are not a magical solution, however. It does not protect us against other degradation of the code quality, like classes gaining too much responsibility (too many methods, unrelated methods, too many properties).

=== "What's the correct ratio between integrity tests and unit tests?" ===

todo, Don't know. Different pros and cons.

* Unit-test can be run in parallel and are faster
* Unit-tests don't need setup and teardown

Cons of unit-tests is that they need a bigger effort on the side of the developer to make them possible, for example injecting the dependencies properly to enable mocking, or lifting side-effects up in the stack trace.

=== How to disagree ===

All rules can be broken. To break a rule, you should reason in terms of risk and the assumptions used in this guide.

'''Assumptions:'''

# Regressions are the biggest technical risk for LimeSurvey the last five years (2021)
# Automated tests are the best risk mitigation technique against regressions

'''Possible disagreement:'''

# A certain piece of code has very low ''probability'' of regressions (maybe we "know" no one else will every touch or change it?)
# Regression in a certain piece of code would have very low ''impact''

== Resources ==

todo

Books, links, videos

Installation - LimeSurvey CE

2021-04-23T13:44:50Z

Olle:

<languages />
<translate>


__TOC__


<div class="simplebox"> Note: These installation instructions are for version 2.0 or later. Older instructions for 1.92 can be found [[Installation Version 1.92 or older|here]] and update instructions can be found [[Upgrading from a previous version|here]]. </div>

=General= 


The LimeSurvey project provides two ways to install LimeSurvey:
*On your webserver:<br />In this case, just follow the instructions on this page starting with step 1.


*On your local Windows PC:<br />You usually only want to install LimeSurvey on your local PC if you want to create surveys locally (mainly for speed or development/test reasons) and upload them later to your live LimeSurvey installation on a web server. For this purpose, we have prepared a special LimeSurvey package which includes the web server, the database, the LimeSurvey application, and [[Installation of the LimeSurvey XAMPP package|instructions how to install it]].

=Make sure you can use LimeSurvey on your website= 


Make sure your server meets the following additional requirements.


{{Note|The minimum set of requirements will also be checked during the installation process!}}


The minimum set of requirements:
* Minimum 250 MB disk space.
* MySQL 5.5.3 or later '''OR''' Microsoft SQL Server 2005 or later '''OR''' Postgres 9 or later.
* Minimum PHP 7.0 up to PHP 7.4 (PHP 8 is not yet supported, but work is ongoing); however, we recommend PHP 7.4 with the following modules/libraries enabled:
** [[Installation FAQ#Requirements page#What is the mbstring (Multibyte String Functions) library|mbstring (Multibyte String Functions)]] extension library.
** PDO database driver for MySQL (pdo_mysql or pdo_mysqli) or Postgres (pdo_pgsql) or MSSQL ([https://php.net/manual/en/ref.pdo-sqlsrv.php pdo_sqlsrv] for Windows and [http://www.php.net/manual/en/ref.pdo-dblib.php pdo_dblib] for Linux).
** Also, we assume in general that all PHP default libraries are enabled
*** hash
*** session
*** openssl or mcrypt
*** fileinfo
*** etc …


<div class="simplebox"> Note: If you are connecting from Linux to a MSSQL database on a Windows server using the dblib PDO driver, then the underlying FreeTDS needs to be set up correctly. Check out the [[Troubleshooting]] page for more information.</div>


Optional PHP Extensions:
* '''GD-Library''' '''with FreeType support''' installed is needed for captchas, nice charts in statistics or to upload images via the HTML editor - see [https://php.net/manual/image.setup.php PHP GD-Library Extension documentation]
* '''IMAP''' (pretty standard) is needed for the [[Email bounce tracking system|email bounce tracking system]] - see [https://php.net/manual/imap.setup.php PHP IMAP Extension documentation]
* '''LDAP''' installed is needed to import survey participants using LDAP - see [https://php.net/manual/en/book.ldap.php PHP LDAP Documentation]
* '''Zip''' (pretty standard) is needed for template upload, import of .zip archived resources, and excel export - see [https://php.net/manual/zip.setup.php PHP Zip Extension documentation]
* '''Zlib''' (pretty standard) is needed for the [[ComfortUpdate]] - see [https://php.net/manual/zlib.setup.php PHP Zlib Extension documentation]


In most cases, your web server provider or system administrator will be able to help you out with these optional components.


If you want to run Microsoft's IIS server, taking a look at [[Installation on XP with IIS]] might also help.

==Browser compatibility== 
'''For the survey-taking side''', we currently support IE11 (intranet-mode excluded) and all newer comparable browsers like Edge, FF, Chrome, Opera etc. with activated JavaScript.


'''For the administration part''', we currently support Edge and all newer comparable browsers like FF, Chrome, Opera etc. with activated JavaScript. <u>We do not support any Internet Explorer versions in the administration part anymore.</u>

===Screen sizes=== 
We support any reasonable screen size for survey taking (360px x 640px and up).
The minimum supported screen resolution for the LimeSurvey administration page is 1280px x 1024px.

==Hosting for LimeSurvey== 


LimeSurvey should work with most hosting companies that provide PHP and MySQL. If you want a ready-installed version of LimeSurvey, you could try [https://www.limesurvey.org/editions-and-prices/limesurvey-pro/editions-and-prices-professional LimeSurvey Cloud], else check out our [[LimeSurvey-compatible hosting companies|list of LimeSurvey-compatible hosting companies]].

=Download the LimeSurvey package= 


[https://www.limesurvey.org/en/downloads/category/25-latest-stable-release Download] the latest stable LimeSurvey zip package (there are also gzip, bz2 and 7zip packages available for your convenience) and save it to your local disk.

=Unpack the LimeSurvey package= 


Uncompress the zip file into a dedicated directory/folder using your preferred compression software. When you uncompress the file make sure that you uncompress the directory structure with the files (this is default behavior for most compression programs). The path name for the installation directory should not include '(' or ')' special characters, but it may include the '''space''' character.

=Collect information about your server= 


You will need to know the following things to install LimeSurvey on your web server correctly:
*Your intended website URL where your scripts will reside (e.g. ''http://my.domain.com/limesurvey'').
*The physical disk location on your server where your scripts will reside (e.g. ''/home/usr/htdocs/limesurvey'').
*The IP/net location of your database server (i.e. ''localhost'').
*If your database server uses a non-standard port, find out which port it is.
*Your user name and password for your database server.
*With most providers you can't let the script create the database, but have to do it yourself. If you are using such a provider, please create a database (for example ''limesurvey'') yourself.

=Upload the files to your web server= 


Using your FTP program (e.g. FileZilla), connect to your web server and create a directory to store your scripts. Then upload the files using the directory structure they are in. Make sure you '''upload the files in binary mode''' (check the settings of your FTP program). Please note that uploading in ASCII mode can lead to uncommon errors (e.g. 'class not found' error during installation), also images may not be uploaded correctly.

=Set directory permissions= 


For the script to work properly it needs certain access to some directories - this applies especially to Linux/*nix systems.
*The '''"/limesurvey/tmp"''' directory (and all its subdirectories and files) are used for imports & uploads and should be set to ''Read & Write'' for your webserver.
*The '''"/limesurvey/upload/"''' directory (and all its subdirectories and files) must also have ''Read & Write'' for your webserver in order to enable picture and media files upload.
*The '''"/limesurvey/application/config/"''' directory also needs ''Read & Write'' permissions for your webserver.
*The other directories can be set to ''Read Only''. You may wish in Linux/Unix to set the permissions on each file within the /limesurvey/admin directory to ''Read Only''.


{{Alert|If you are using Linux, then setting permissions depends on your webserver configuration. For example, if you use Apache HTTPD on CentOS, type '''chmod -R 755 <directory> ; chown -R apache <directory>'''. This will give everyone access to read, and your webserver will have the permission to write. Check the [https://www.linux.com/learn/tutorials/309527-understanding-linux-file-permissions following link] for more information on Linux permissions.}}

=Create a database user= 


LimeSurvey will create a database and the tables inside it. To be able to do this, it will need the user name and password of a database user. We generally recommend creating a database user with the following permissions:


- MySQL: SELECT, CREATE, INSERT, UPDATE, DELETE, ALTER, DROP, INDEX


- PostgreSQL: SELECT, INSERT, UPDATE, DELETE, TRUNCATE, TRIGGER


- Microsoft SQL Server: ''Unknown - if you can find out this information, please complete it''.

=Run the installation script= 


'''Go to "example.org/limesurvey/admin"'''. If you configured everything correctly, the LimeSurvey installer should be starting - just follow the instructions. You will be asked whether you wish to create the database and/or create the tables inside the database. LimeSurvey will then create the needed tables in the database.

=Connect to the administration script for the first time= 


You are done when the installation finishes! Open your browser and enter the URL to the LimeSurvey administration. Assuming you used 'limesurvey' as the directory name to store the files in, this will be something like "http://www.example.com/limesurvey/admin".


You should get a login screen. The default login credentials (if they have not been changed during the installation) are:


<syntaxhighlight lang='html' enclose="div">


User: admin
Password: password


</syntaxhighlight>


You will be prompted to change the default password after you logged in. Have fun!

=Further configuration= 

==Caching== 


LimeSurvey uses the Yii file cache by default, but it can be configured to use other cache engines. Possible other caches are:


* Memcached
* Redis
* WinCache
* XCache


Please see the [https://www.yiiframework.com/doc/api/1.1/CCache Yii documentation] for full description.


Since LimeSurvey 4.0.0 you also have the possibility to cache calculations in the ExpressionScript. This can provide a significant speed-up depending on survey complexity. To enable the emcache, add this in your config.php file (components array):


<syntaxhighlight lang="php">
'emcache' => array('class' => 'CFileCache'),
</syntaxhighlight>


As with the main Yii cache, other cache systems can be used.


{{Note| The emcache is not compatible with randomized surveys, and will be automatically turned off in such cases.}}

=What if I have problems...= 


Like all computer programs, most of the time things will work just like the instructions say, but sometimes they just won't. There are too many possible reasons for things not going according to plan to describe here. If you have trouble, first check out the [[Installation FAQ]]. If you don't find your answer there, please post your problem and any error messages in the [https://www.limesurvey.org/forum LimeSurvey forums], open a [https://www.limesurvey.org/contact-us support ticket], or join the [irc://irc.freenode.net/limesurvey|LimeSurvey IRC channel]:


<div class="simplebox"><center>'''[https://www.limesurvey.org/community-services/live-chat Direct link to the official LimeSurvey IRC Channel]'''</center></div>

</translate>

Code quality guide

2021-04-23T12:15:54Z

Olle: /* Types of classes */

DRAFT

== Prologue ==

# '''Be risk aware'''. Too good code can be a business risk (slow to write, maybe over-designed). Too sloppy code can also be a business risk (hard to maintain and understand). You have to find a balance that is adapted to the current situation and risk analysis, in which code quality becomes a '''risk mitigation''' technique among others.
# '''Be humble'''. LimeSurvey was made by developers from all over the world, with different age, education and experience. Your code might be read by a completely different team ten years from now, in the same way you are now reading code by developers that no longer work with us, but which work pays our rent.
# '''Performance matters sometimes''', and shouldn't be disregarded completely. In particular, database queries using the ORM and ActiveRecord can be problematic. Some surveys have thousands of questions and hundreds of thousands of responses. Fast response time is also important for a fluid user experience.
# '''It's harder to read code than to write code'''. Don't choose patterns that are easy or fast to write, but that are easy to read.
# Make your code '''communicate intent'''.
# It's easy to forget '''cross-cutting concerns''' like translation and security. Keep a mental note.
# '''Stress affects code quality''' and your risk behaviour. If your stress level is too high to write code with proper quality, take a step back and discuss it with your boss, or you'll push problems to the future.

== Quality ==

The purpose of this guide is to increase the quality of the LimeSurvey code-base. What is quality? Which aspects of quality can be measured? Which kind of company culture gives rise to appropriate code quality?

It's usually easier to get along what is "bad" code than what's "best" code. Blacklist instead of whitelist?

Quality attributes related to code quality:

* Readability
* Testability
* Maintainability
* Performance
* Security
* Reliability

Can not increase all at the same time - performance vs readability.

It's better to avoid emotional language when describing code quality, like "clean" or "dirty". Be precise, objective and suggest solutions.

Idiomatic code is more readable than non-idiomatic code. What's idiomatic depends on which context or domain you work in. We work in PHP and web application development, and have other idioms than in, say, functional or hardware-close programming.

Some code are "hot spots" - changed often. Those parts should require higher quality than other code.

== Risk ==

todo

data loss as most severe risk for LS

usability a business risk - hard to use or understand, people will choose another tool

risks relevant when fixing bugs

risks relevant when adding new features (lack of testing, wrong requirements, scope creep)

risks relevant when refactoring (regressions)

unit tests and QA as risk mitigation

partial deployment, alpha/beta/rc, risk communication

software rot, design pattern rot/grime, software evolution

rot = non-pattern related code

testing by community, bug fixing by community

== Modules ==

There's no inherit module functionality in PHP, but Yii has a module system. Libraries can be seen as a module system.

Examples of implicit modules in LimeSurvey:

* Front-end (survey taking)
* Back-end (survey design)
* Survey theme editing
* Expression manager
* Plugin system

In the future, they need to be separated and implemented more clearly as whatever Yii 3 module system is in use.

Some data models are common for all modules, e.g. surveys and users. Can have a "Common" module for such data.

todo, relation to Yii config system

== Classes ==

todo

* Avoid empty OOP ceremony, like defining getters and setters for all properties. Might as well make them public, ''unless'' they have invariants that need to be upheld, e.g. "this number is always between 1 and 10" or "this string is maximum length 20".
* Almost always avoid static methods. They cannot be mocked. One exception is (possibly) factory methods (Foo::make(...)).
* Inject all dependencies. This will make sure the class can be unit-tested (unit-tests have several benefits over integrity tests - they can be run in parallel and don't require any setup and teardown)
* A second way to achieve testability is to factor out the methods that access the dependencies

todo, state vs behaviour, state vs dependencies

=== OOP design ===

todo

Start from top-down, with domain, behaviour, interaction between objects, database design, pseudo-code if needed. Can also include scenarios, use-cases and UML diagrams.

Object reification - not only domain models, but also domain actions, relations and activities can be objects, e.g. a class ActivateSurvey or ExportSurvey.

Hierarchy depth.

Inheritance vs composition.

Multiple inheritance is done with traits. Use-case: ActiveRecords that support encryption, but not all.

=== Design pattern grime and software evolution ===

Design rot after time - how to keep it tight? (Grime.)

=== State ===

Keep a clear separation between classes with state and classes with no state.

todo, elaborate

=== Types of classes ===

Different categories of classes:

* Builders (e.g. query builder)
* Data-transfer object (no behaviour; pass to views to have better documentation and intent than associative arrays)
* Value classes (e.g. Email to wrap email string around)
* Command object (e.g. SurveyActivator)
* Helper (no state; e.g. QuestionAttributeHelper to bake attributes into different formats used by the views)
* Wrapper (also no state; e.g IOWrapper, to be able to mock file access)

todo, immutability, possible with private properties that are set in the constructor,

todo: command-query separation for classes?

todo: dependencies between layers, dependencies to the framework

todo, pure vs effectful classes

=== Types of classes in LimeSurvey ===

* ActiveRecord, used to communicate with the database, and should not do ''anything'' else
* Controllers, used for glue code; should not contain business-logic
* Commands, same as controllers but from CLI
* Helper functions, should be short and obey command-query separation (TODO: Long functions should be separated into command objects or service classes); todo: should not have any dependencies?
* Helper classes, similar to helper functions but have dependencies that need to be mocked during tests; should not have any state
* Service classes, contains logic related to a clear and separate task, like create or import survey
* Question render classes, contains logic related to how questions are rendered (TODO: Need better separation between state and logic and more clear design); similar to widgets
* Plugin classes, using the plugin event system
* Widgets, containing HTML logic for custom HTML widgets
* Customizations to the Yii framework by inheritance
* Unit and functional test classes

A couple of classes contain only data, like LsDefaultDataSet.

todo, no difference between state property and dependency property in OOP

=== What is "glue code"? ===

todo

Putting the pieces together, e.g. service class A need data from model B, fetch it and run.

todo, add example

=== "Where do I cut?" ===

Separation of concerns, but which concerns and which type of separation?

=== Size ===

A class should have a single and clear purpose; compare with [https://en.wikipedia.org/wiki/SOLID SOLID].

=== Class name ===

* ActiveRecord classes are named after the database table they are bound to, but with singular instead of plural. E.g. table "lime_users" have model "User".
* Services classes are named after what they ''do'', e.g. SurveyCreator
* Helper classes should probably be named as specific as possible when possible, to avoid them from growing too big
* Follow the naming tradition of the framework with regard to controllers, e.g. UserController or UserAdministrationController.

== Functions ==

Functions are one of the fundamental building blocks of programming, so it's important to get it right.

Functions that are part of a class are called "methods", if you want to be formal.

Different types of functions in PHP:

* Functions (not attached to a class)
* Methods (attached to class)
* Anonymous functions (does not capture scope automatically)
* Short functions (does capture scope automatically)

I'm using "function" as a word for all types of functions in PHP below.

<hr>

=== Size ===

* A function should be short enough to be completely readable on one screen, approx 60 lines at most
* A function should not have too many arguments; if you have five or more, consider making it a class instead
* If a function is growing too big, it might be better to create a class instead or split it into several functions (if both functions have '''common state''', a class might be better, unless you want to pass around '''explicit state''')

=== Contract ===

* A function has a contract with its surrounding environment:
** Pre-condition: What needs to be true before the function is executed
** Post-condition: What will be true after the function has returned
* The function contract can be checked with assertions (internal invariants) or exceptions (outside world); see below
* Another good way is to use unit-tests to make sure the function's contract remains stable through changes
* The first line in the docblock should be one sentence describing the relation between function arguments and its output<br>Example<br><syntaxhighlight lang="php">
/**
* Creates a random password of length $length (defaults to 12)
* @param int $length
* @return string
*/
function createPassword($lenght = 12)

/**
* Creates an HTML language drop down for survey with id $surveyId, marking $selectedLanguage as selected
* @param int $surveyId
* @param string $selectedLanguage
* @return string <select> HTML
*/
function createLanguageDropdown($surveyId, $selectedLanguage)

</syntaxhighlight>

=== Push side-effects up in the stack trace ===

This one is a bit abstract.

First, what is a '''side-effect'''? In short, it's anything that happens in a function that ''is not'' described by the ''relation'' between function arguments and output.

Another way to phrase it is, that a side-effect is anything that is not always the same for the given input to a function; a function without any side-effects will always return the same result if it gets the same input.

'''Examples:'''

<syntaxhighlight lang="php">
// gT accesses the file system and will return different result depending on what's in the translation files
function gT($sToTranslate, $sEscapeMode = 'html', $sLanguage = null);

// If $sText and $sEscapeMode is always the same, quoteText() will always return the same string.
function quoteText($sText, $sEscapeMode = 'html');
</syntaxhighlight>

A function with no side-effects is called '''pure'''. A function that is guaranteed to always return (no exceptions, no errors, no warnings, no division by zero) is called '''total'''. Another name for purity is [https://en.wikipedia.org/wiki/Referential_transparency referential transparency].

It's a good thing if functions in a code-base ''either'' have side-effects, ''or'' return a result. Not both. This is called [https://en.wikipedia.org/wiki/Command%E2%80%93query_separation command-query separation].

Examples of side-effects:

* Database or file access
* Echo, or write to stdout or stderr
* Randomization

Why does this matter? Because side-effects make testing harder! '''If you have side-effects, you cannot create unit tests''', ''unless'' those side-effects can be mocked. If not, you need integrity tests with database setup or more. The more side-effects you have in a function, the more mocking is required to unit test it.

So, one solution to this is to move side-effects higher up in the stack trace, that is, move them to the calling code.

'''Example:'''

<syntaxhighlight lang="php">
function getSurveyInfo(int $surveyid, string $languagecode = '', boolean $force = false): array;
</syntaxhighlight>

Since this function takes $surveyid, we know it will probably query the database. Quering the database is a side-effect, and thus it requires a database scaffold for the test (or mocking, but the database connection is not injected, so there's no way to do it). One simple solution is to lift the side-effect out and pass in a Survey object instead:

<syntaxhighlight lang="php">
function getSurveyInfo(Survey $survey, string $languagecode = '', boolean $force = false): array;
</syntaxhighlight>

Much better! The side-effect of calling the database now happens ''before'' the function call. Now we can either mock a Survey object, or make an imitating stub for our test.

Reading the function body, there is in fact another database access, but since this is a relation to the Survey model, it could easily be moved out too. We've just made a function testable! Hooray!

This principle is rephrased in an architectural settings as [https://github.com/kbilsted/Functional-core-imperative-shell/blob/master/README.md functional core, imperative shell]. This architecture helps you get a good ratio between fast unit tests and slower integrity tests.

=== Function name ===

* The function name should tell you '''what''' it does; docs should tell you '''why''' (if this information is not obvious). '''How''' is described by the code itself (hopefully, but can in some cases be relevant to document).
* Function name can often be '''verb [+ adjective] + noun''', like "createFieldmap", "quoteText", "getRelativePath"
* Prefix with "is" for boolean functions

todo: difference between create, get, fetch, generate, ...

'''Good examples:'''

* createPassword() - One verb, one noun - clear
* isCaptchaEnabled() - Using "is" signifies it returns boolean; clear purpose
* getFullResponseTable() - Verb, adjective, noun - but is "full" needed here? Is there a non-full version of the same function?
* replaceExpressionCodes() - Pretty good, but it's obvious that more information is needed in the docblock to describe what "replace" means, and what an "expression code" is
* fixCKeditorText() - "fix" is a bit vague, but maybe best there is? Pray that docblock contains information!

'''Bad examples:'''

* languageDropdown() - No verb, doesn't tell you what it does
* rmdirr() - Two r's, looks like a typo, but the last "r" actually means "recursive"! Better: rmdir($recursive = false), rmdir or removeFolder.
* CSVUnquote() - Is CSV really the namespace? Why is the verb the second word?
* incompleteAnsFilterState() - One verb, but in the middle, or is "filter state" a noun?; why abbreviate "answer" to "ans"?
* reverseTranslateFieldNames() - Two verbs - did author mean "reverseTranslatedFieldNames"? Or "reverse and translate"? If so, it should be two functions, one for reverse and one for translate
* checkUploadedFileSizeAndRenderJson() - If you have an "and" in the function name, you should consider splitting it into two functions

'''Controversial'''

* gT() - An exception to descriptive function names; since this is used everywhere, the minimal name is motivated; maybe even name it "t()"? Still hard to read for someone who just started? But Yii uses t() too? Other frameworks use double underscore (Wordpress, Laravel) as function name.

<hr>

=== Function filename and namespace ===

If your function has dependencies or side-effects, it should be put into a class instead, in which the dependencies can be injected. Another alternative is to put the dependencies as argument in the function, although this muffles the relationship between input and output. Again, this is to increase testability.

Keep in mind that functions outside classes cannot be mocked, so only use them when you ''know'' you won't need to mock them.

todo, autoloading of functions and folder location

=== Assertions ===

NB: This is not assertions as used in unit-tests, but assertions as used to check invariants in production code.

Assertions can be used for mental checks. They are only used for internal logic - failed assertions are not supposed to be seen by the end user. For interaction with the outside world, like database or browser, exceptions should be used instead.

Assertions can be disabled in production mode and have then no runtime cost.

'''Example:'''

<syntaxhighlight lang="php">
/**
* Translation helper function
*
* @param string $sToTranslate
* @param string $sEscapeMode Valid values are html (this is the default, js and unescaped)
* @param string $sLanguage
* @return string
*/
function gT($sToTranslate, $sEscapeMode = 'html', $sLanguage = null)
{
assert(is_string($sToTranslate));
assert(strlen($sToTranslate) > 0);
assert($sEscapeMode === 'html' || $sEscapeMode === 'js' || $sEscapeMode === 'unescaped');
return quoteText(Yii::t('', $sToTranslate, array(), null, $sLanguage), $sEscapeMode);
}
</syntaxhighlight>

<hr>

=== Exceptions ===

todo

todo: exception hierarchy

todo: what can be repaired after exception? transaction rollback

* Exceptions are used to check inputs from the outside world (browser, database, file system)
* Don't use exceptions for control flow, only when fatal errors happen that make further execution impossible
* Exceptions should have clear error messages that make them ''actionable'' - there should be a clear "next step" for the user or developer
* Never, ever, do an empty catch-block

==== Alternatives to exceptions ====

Some people consider exceptions being a hidden form of "goto" which confuses the control flow of the program. They propose different other solutions:

* Return a tuple, like <code>[$result, $errorMessage]</code> where $errorMessage is null at success
* Return <code>null</code> at failure
* Tagged union result type (not yet possible in latest PHP)
* Result object

The con being that you have to manually propagate the error, where an exception can happen from anywhere in the stack trace without any other function knowing about it.

=== If-statements ===

If-statements should not be too long or hard to understand. If they are, consider factor out the checks into separate functions.

<syntaxhighlight lang="php">
if ((empty($instance->oOptions->{$attribute}))
|| (
!empty($instance->oOptions->{$attribute})
&& (
$instance->oOptions->{$attribute} === 'inherit'
|| $instance->oOptions->{$attribute} === 'I'
// NB: Do NOT use === here, it won't work with Postgresql.
|| $instance->oOptions->{$attribute} == '-1'
)
)
) {
</syntaxhighlight>

Can be shortened by factoring out method <code>isInherit</code>:

<syntaxhighlight lang="php">
if (empty($instance->options->{$attribute})
|| $this->isInherit($instance-options->{$attribute})) {
}
/**
* Returns true if $value is set to inherit
* @param mixed|null $value
* @return boolean
*/
public function isInherit($value) {
return !empty($value)
&& (
$value === 'inherit'
|| $value === 'I'
// NB: Do NOT use === here, it won't work with Postgresql.
|| $value == '-1'
);
}
</syntaxhighlight>

And one more time by using a variable for the value:

<syntaxhighlight lang="php">
$value = $instance->options->{$attribute};
if (empty($value) || $this->isInherit($value)) {
}
</syntaxhighlight>

More clear, right? "If it's empty or set to inherit, do this and that."

=== Variables ===

Descriptive naming.

* Follow PSR-12 - no underscore, use camelCaseLikeThis
* Variables of ActiveRecord classes can have same name as the class, like "$survey" or "$question"
* Add -s for plural when it's an array: "$surveys", "$questions"
* Never include "array" or "list" in variable names - using plural is enough
* The ''context'' of the function helps with variable naming, e..g "$name" might be fine in a function about questions; this is extra helpful when functions are short!
* When a function is short, it's much easier to figure out variable meaning based on context
* $qid, $gid, and $sid are so established in the code-base that they could be considered OK
* The -data suffix means "blob of stuff", only use it when needed, like with $viewData
* Use $result when baking a return value; add its exact type as @var annotation (worst possible name, acceptable but anything with more meaning is better)

Not so good:

<syntaxhighlight lang="php">
$result = LabelSet::model()->findAll();
</syntaxhighlight>

Better with model name and -s for plural:

<syntaxhighlight lang="php">
$labelSets = LabelSet::model()->findAll();
</syntaxhighlight>

* Do not use Hungarian notation (prefix with "type"), but instead <code>/** @var */</code> annotations - these can be checked automatically and will then be enforced to be correct, unlike Hungarian notation which can "rot"

<syntaxhighlight lang="php">
/** string[] An array of strings with 0-n elements */
$allFields = [];
</syntaxhighlight>

Psalm can infer types if the function documentation is enough. The strictness can be adjusted. Not all variables will need @var annotation, the tool will warn you when it's confused.

* Data that is sent to views as associative arrays will be:

<syntaxhighlight lang="php">
/** @var array Can be basically anything :( Better would be data-transfer objects or more precise notation */
$data = [];
// Maybe more clear as $viewData? Discuss.
</syntaxhighlight>

You can be more precise when you specify which type of array you're writing:

<syntaxhighlight lang="php">
/** @var array<string, string> This means the array key is string, and the array value is also string */
$data = [];
$data['name'] = 'Olle';
$data['occupation'] = 'Developer';
$data['age'] = 38; // ERROR! Value must be string.
</syntaxhighlight>

For more info about array type notation, see the [https://psalm.dev/docs/annotating_code/type_syntax/array_types/ Psalm documentation].

Some smaller examples:

<syntaxhighlight lang="php">
$theme = App()->request->getPost('theme'); // Should be $themeType - $theme looks like a model/AR
$gridid === 'questionthemes-grid'; // Should be $gridId with capital "I", since it's two words in English
$delete = Yii::app()->request->getParam('delete'); // Tuff one - $delete is ok? Thoughts?
$files = json_decode(stripslashes($sJSON), true); // $file is a resource, $files an array of resources, this is $fileData perhaps?
$valid_extensions_array = explode(",", $aAttributes['allowed_filetypes']); // Should be $validExtensionTypes
$language = Yii::app()->session['survey_' . $surveyid]['s_lang']; // TODO: Should this be a value class? Then Language::make(...);
$surveyInfo = getSurveyInfo($surveyId, $language); // OK, BUT should be a separate DTO!
$fieldMap = createFieldMap($survey, 'short', false, false, $language); // Same, make a DTO
$cquestions = array(); // What's "c"? Method name is getChildQuestions and $questions is an argument - better with $childQuestions?
</syntaxhighlight>

=== Looping ===

* The bodies of foreach-loops are often a good candidate to factor out into separate functions.

'''Example:'''

<syntaxhighlight lang="php">
foreach ($questions as $question) {
processQuestion($question);
}
</syntaxhighlight>

Note the variable naming from plural to singular.

* Loop indexing should be named i, j, k etc.

'''Example:'''

<syntaxhighlight lang="php">
for ($i = 0; $i < $length; $i++) {
for ($j = 0; $j < $otherLength; $j++) {
// ...
}
}
</syntaxhighlight>

<hr>

=== Function composition ===

todo, "doThisAndThat" --> "doThis(doThat())"

=== Cases ===

<syntaxhighlight lang="php">
/**
* This function generates an array containing the fieldcode, and matching data in the same order as the activate script
*
* @param Survey $survey Survey ActiveRecord model
* @param string $style 'short' (default) or 'full' - full creates extra information like default values
* @param boolean $force_refresh - Forces to really refresh the array, not just take the session copy
* @param bool|int $questionid Limit to a certain qid only (for question preview) - default is false
* @param string $sLanguage The language to use
* @param array $aDuplicateQIDs
* @return array
*/
function createFieldMap($survey, $style = 'short', $force_refresh = false, $questionid = false, $sLanguage = '', &$aDuplicateQIDs = array())
</syntaxhighlight>

'''Good:'''

* Name is verb and noun
* Each argument is documented (almost)

'''Bad:'''

* Returns "array", which can be anything. A separate class for "Fieldmap" would be better.
* Not clear if it should be "createFieldMap" or "createFieldmap" - is "fieldmap" one word or two?
* Very many boolean arguments. Should probably be a class with methods like <code>$fieldmapCreator->setForceRefresh(true);</code> instead.
* Too long.
* Doesn't elaborate on what "fieldmap" really is, and does not link to any documentation about it.
* Access super-global, which makes it hard to test. Should instead return a data-transfer object, like:<br><syntaxhighlight lang="php">
$_SESSION['fieldmap'] = createFieldMap(...);
</syntaxhighlight>
* Has no test
* Mixes Hungarian notation with non-Hungarian notation in the argument list

== Defensive programming and error handling ==

todo

* '''Fail hard, fail early'''. The earlier the program crashes when something is wrong, the lower is the probability that you'll end up with corrupt data in the database that will later require manual labor to correct.
* Fail with '''actionable information'''
* Check input to functions and throw <code>InvalidArgumentException</code> if it violates the function's pre-conditions
* Use assert for class-internal invariants
* Use assert to make assumptions explicit for the reader

== Documentation ==

=== PHPDoc ===

* All functions must have a proper docblock
* The first line of the docblock should describe the relation between ''all'' the input arguments and the output of the function in a single sentence
* Each parameter must have the correct type
* Don't use <code>array</code> as type if it's a list of object - instead, use <code>[]</code> like so: <code>Survey[]</code> for a list of surveys

=== Technical documentation ===

todo, UML, scenarios, use-cases

== The PHP of yesterday ==

Old idioms and habits that should be abandoned.

* Don't use associative arrays, almost never. Data-transfer objects have multiple benefits: they are clearly structured, can be documented, can enforce invariants. There's ''no'' performance overhead of objects compared to arrays in modern PHP.
* Objects are already passed by reference; arrays are value types
* Use <code>[]</code> instead of <code>array()</code>
* Hungarian notation was useful before static analysis existed for PHP. These days it's better to use something that can be checked automatically: docblock @param and inline @var annotations.

== The PHP of tomorrow ==

todo

Union tags

Short functions

Match expressions

== Security ==

todo

XSS

Database injection

Permissions and roles

== Performance ==

todo

Loading too many rows into PHP models

== Testing ==

todo

QA

PHPUnit

TDD

Mocks, can't mock functions, static methods, mocking as a DSL, PHPUnit mocking tools

Pure functions, referential transparency, side-effects

Unit, functional, integration

Don't test the framework; don't test PHP

Makes sure the function or class lives up to its specification; make sure it will ''always'' live up to its specification, even in the future, to avoid regressions.

== Static analysis ==

<code>php -l</code>, CodeSniffer, Mess Detector, Psalm

== Database design ==

todo

== JavaScript ==

todo

classes, functions, components, tests

== CSS ==

todo

== HTML ==

todo

== Resources ==

todo

Books, links, videos

Code quality guide

2021-04-23T12:10:27Z

Olle: /* Types of classes */

DRAFT

== Prologue ==

# '''Be risk aware'''. Too good code can be a business risk (slow to write, maybe over-designed). Too sloppy code can also be a business risk (hard to maintain and understand). You have to find a balance that is adapted to the current situation and risk analysis, in which code quality becomes a '''risk mitigation''' technique among others.
# '''Be humble'''. LimeSurvey was made by developers from all over the world, with different age, education and experience. Your code might be read by a completely different team ten years from now, in the same way you are now reading code by developers that no longer work with us, but which work pays our rent.
# '''Performance matters sometimes''', and shouldn't be disregarded completely. In particular, database queries using the ORM and ActiveRecord can be problematic. Some surveys have thousands of questions and hundreds of thousands of responses. Fast response time is also important for a fluid user experience.
# '''It's harder to read code than to write code'''. Don't choose patterns that are easy or fast to write, but that are easy to read.
# Make your code '''communicate intent'''.
# It's easy to forget '''cross-cutting concerns''' like translation and security. Keep a mental note.
# '''Stress affects code quality''' and your risk behaviour. If your stress level is too high to write code with proper quality, take a step back and discuss it with your boss, or you'll push problems to the future.

== Quality ==

The purpose of this guide is to increase the quality of the LimeSurvey code-base. What is quality? Which aspects of quality can be measured? Which kind of company culture gives rise to appropriate code quality?

It's usually easier to get along what is "bad" code than what's "best" code. Blacklist instead of whitelist?

Quality attributes related to code quality:

* Readability
* Testability
* Maintainability
* Performance
* Security
* Reliability

Can not increase all at the same time - performance vs readability.

It's better to avoid emotional language when describing code quality, like "clean" or "dirty". Be precise, objective and suggest solutions.

Idiomatic code is more readable than non-idiomatic code. What's idiomatic depends on which context or domain you work in. We work in PHP and web application development, and have other idioms than in, say, functional or hardware-close programming.

Some code are "hot spots" - changed often. Those parts should require higher quality than other code.

== Risk ==

todo

data loss as most severe risk for LS

usability a business risk - hard to use or understand, people will choose another tool

risks relevant when fixing bugs

risks relevant when adding new features (lack of testing, wrong requirements, scope creep)

risks relevant when refactoring (regressions)

unit tests and QA as risk mitigation

partial deployment, alpha/beta/rc, risk communication

software rot, design pattern rot/grime, software evolution

rot = non-pattern related code

testing by community, bug fixing by community

== Modules ==

There's no inherit module functionality in PHP, but Yii has a module system. Libraries can be seen as a module system.

Examples of implicit modules in LimeSurvey:

* Front-end (survey taking)
* Back-end (survey design)
* Survey theme editing
* Expression manager
* Plugin system

In the future, they need to be separated and implemented more clearly as whatever Yii 3 module system is in use.

Some data models are common for all modules, e.g. surveys and users. Can have a "Common" module for such data.

todo, relation to Yii config system

== Classes ==

todo

* Avoid empty OOP ceremony, like defining getters and setters for all properties. Might as well make them public, ''unless'' they have invariants that need to be upheld, e.g. "this number is always between 1 and 10" or "this string is maximum length 20".
* Almost always avoid static methods. They cannot be mocked. One exception is (possibly) factory methods (Foo::make(...)).
* Inject all dependencies. This will make sure the class can be unit-tested (unit-tests have several benefits over integrity tests - they can be run in parallel and don't require any setup and teardown)
* A second way to achieve testability is to factor out the methods that access the dependencies

todo, state vs behaviour, state vs dependencies

=== OOP design ===

todo

Start from top-down, with domain, behaviour, interaction between objects, database design, pseudo-code if needed. Can also include scenarios, use-cases and UML diagrams.

Object reification - not only domain models, but also domain actions, relations and activities can be objects, e.g. a class ActivateSurvey or ExportSurvey.

Hierarchy depth.

Inheritance vs composition.

Multiple inheritance is done with traits. Use-case: ActiveRecords that support encryption, but not all.

=== Design pattern grime and software evolution ===

Design rot after time - how to keep it tight? (Grime.)

=== State ===

Keep a clear separation between classes with state and classes with no state.

todo, elaborate

=== Types of classes ===

Different categories of classes:

* Builders (e.g. query builder)
* Data-transfer object (no behaviour; pass to views to have better documentation and intent than associative arrays)
* Value classes (e.g. Email to wrap email string around)
* Command object (e.g. SurveyActivator)
* Helper (no state; e.g. QuestionAttributeHelper to bake attributes into different formats used by the views)
* Wrapper (also no state; e.g IOWrapper, to be able to mock file access)

todo, immutability, possible with private properties that are set in the constructor,

todo: command-query separation for classes?

todo: dependencies between layers, dependencies to the framework

=== Types of classes in LimeSurvey ===

* ActiveRecord, used to communicate with the database, and should not do ''anything'' else
* Controllers, used for glue code; should not contain business-logic
* Commands, same as controllers but from CLI
* Helper functions, should be short and obey command-query separation (TODO: Long functions should be separated into command objects or service classes); todo: should not have any dependencies?
* Helper classes, similar to helper functions but have dependencies that need to be mocked during tests; should not have any state
* Service classes, contains logic related to a clear and separate task, like create or import survey
* Question render classes, contains logic related to how questions are rendered (TODO: Need better separation between state and logic and more clear design); similar to widgets
* Plugin classes, using the plugin event system
* Widgets, containing HTML logic for custom HTML widgets
* Customizations to the Yii framework by inheritance
* Unit and functional test classes

A couple of classes contain only data, like LsDefaultDataSet.

todo, no difference between state property and dependency property in OOP

=== What is "glue code"? ===

todo

Putting the pieces together, e.g. service class A need data from model B, fetch it and run.

todo, add example

=== "Where do I cut?" ===

Separation of concerns, but which concerns and which type of separation?

=== Size ===

A class should have a single and clear purpose; compare with [https://en.wikipedia.org/wiki/SOLID SOLID].

=== Class name ===

* ActiveRecord classes are named after the database table they are bound to, but with singular instead of plural. E.g. table "lime_users" have model "User".
* Services classes are named after what they ''do'', e.g. SurveyCreator
* Helper classes should probably be named as specific as possible when possible, to avoid them from growing too big
* Follow the naming tradition of the framework with regard to controllers, e.g. UserController or UserAdministrationController.

== Functions ==

Functions are one of the fundamental building blocks of programming, so it's important to get it right.

Functions that are part of a class are called "methods", if you want to be formal.

Different types of functions in PHP:

* Functions (not attached to a class)
* Methods (attached to class)
* Anonymous functions (does not capture scope automatically)
* Short functions (does capture scope automatically)

I'm using "function" as a word for all types of functions in PHP below.

<hr>

=== Size ===

* A function should be short enough to be completely readable on one screen, approx 60 lines at most
* A function should not have too many arguments; if you have five or more, consider making it a class instead
* If a function is growing too big, it might be better to create a class instead or split it into several functions (if both functions have '''common state''', a class might be better, unless you want to pass around '''explicit state''')

=== Contract ===

* A function has a contract with its surrounding environment:
** Pre-condition: What needs to be true before the function is executed
** Post-condition: What will be true after the function has returned
* The function contract can be checked with assertions (internal invariants) or exceptions (outside world); see below
* Another good way is to use unit-tests to make sure the function's contract remains stable through changes
* The first line in the docblock should be one sentence describing the relation between function arguments and its output<br>Example<br><syntaxhighlight lang="php">
/**
* Creates a random password of length $length (defaults to 12)
* @param int $length
* @return string
*/
function createPassword($lenght = 12)

/**
* Creates an HTML language drop down for survey with id $surveyId, marking $selectedLanguage as selected
* @param int $surveyId
* @param string $selectedLanguage
* @return string <select> HTML
*/
function createLanguageDropdown($surveyId, $selectedLanguage)

</syntaxhighlight>

=== Push side-effects up in the stack trace ===

This one is a bit abstract.

First, what is a '''side-effect'''? In short, it's anything that happens in a function that ''is not'' described by the ''relation'' between function arguments and output.

Another way to phrase it is, that a side-effect is anything that is not always the same for the given input to a function; a function without any side-effects will always return the same result if it gets the same input.

'''Examples:'''

<syntaxhighlight lang="php">
// gT accesses the file system and will return different result depending on what's in the translation files
function gT($sToTranslate, $sEscapeMode = 'html', $sLanguage = null);

// If $sText and $sEscapeMode is always the same, quoteText() will always return the same string.
function quoteText($sText, $sEscapeMode = 'html');
</syntaxhighlight>

A function with no side-effects is called '''pure'''. A function that is guaranteed to always return (no exceptions, no errors, no warnings, no division by zero) is called '''total'''. Another name for purity is [https://en.wikipedia.org/wiki/Referential_transparency referential transparency].

It's a good thing if functions in a code-base ''either'' have side-effects, ''or'' return a result. Not both. This is called [https://en.wikipedia.org/wiki/Command%E2%80%93query_separation command-query separation].

Examples of side-effects:

* Database or file access
* Echo, or write to stdout or stderr
* Randomization

Why does this matter? Because side-effects make testing harder! '''If you have side-effects, you cannot create unit tests''', ''unless'' those side-effects can be mocked. If not, you need integrity tests with database setup or more. The more side-effects you have in a function, the more mocking is required to unit test it.

So, one solution to this is to move side-effects higher up in the stack trace, that is, move them to the calling code.

'''Example:'''

<syntaxhighlight lang="php">
function getSurveyInfo(int $surveyid, string $languagecode = '', boolean $force = false): array;
</syntaxhighlight>

Since this function takes $surveyid, we know it will probably query the database. Quering the database is a side-effect, and thus it requires a database scaffold for the test (or mocking, but the database connection is not injected, so there's no way to do it). One simple solution is to lift the side-effect out and pass in a Survey object instead:

<syntaxhighlight lang="php">
function getSurveyInfo(Survey $survey, string $languagecode = '', boolean $force = false): array;
</syntaxhighlight>

Much better! The side-effect of calling the database now happens ''before'' the function call. Now we can either mock a Survey object, or make an imitating stub for our test.

Reading the function body, there is in fact another database access, but since this is a relation to the Survey model, it could easily be moved out too. We've just made a function testable! Hooray!

This principle is rephrased in an architectural settings as [https://github.com/kbilsted/Functional-core-imperative-shell/blob/master/README.md functional core, imperative shell]. This architecture helps you get a good ratio between fast unit tests and slower integrity tests.

=== Function name ===

* The function name should tell you '''what''' it does; docs should tell you '''why''' (if this information is not obvious). '''How''' is described by the code itself (hopefully, but can in some cases be relevant to document).
* Function name can often be '''verb [+ adjective] + noun''', like "createFieldmap", "quoteText", "getRelativePath"
* Prefix with "is" for boolean functions

todo: difference between create, get, fetch, generate, ...

'''Good examples:'''

* createPassword() - One verb, one noun - clear
* isCaptchaEnabled() - Using "is" signifies it returns boolean; clear purpose
* getFullResponseTable() - Verb, adjective, noun - but is "full" needed here? Is there a non-full version of the same function?
* replaceExpressionCodes() - Pretty good, but it's obvious that more information is needed in the docblock to describe what "replace" means, and what an "expression code" is
* fixCKeditorText() - "fix" is a bit vague, but maybe best there is? Pray that docblock contains information!

'''Bad examples:'''

* languageDropdown() - No verb, doesn't tell you what it does
* rmdirr() - Two r's, looks like a typo, but the last "r" actually means "recursive"! Better: rmdir($recursive = false), rmdir or removeFolder.
* CSVUnquote() - Is CSV really the namespace? Why is the verb the second word?
* incompleteAnsFilterState() - One verb, but in the middle, or is "filter state" a noun?; why abbreviate "answer" to "ans"?
* reverseTranslateFieldNames() - Two verbs - did author mean "reverseTranslatedFieldNames"? Or "reverse and translate"? If so, it should be two functions, one for reverse and one for translate
* checkUploadedFileSizeAndRenderJson() - If you have an "and" in the function name, you should consider splitting it into two functions

'''Controversial'''

* gT() - An exception to descriptive function names; since this is used everywhere, the minimal name is motivated; maybe even name it "t()"? Still hard to read for someone who just started? But Yii uses t() too? Other frameworks use double underscore (Wordpress, Laravel) as function name.

<hr>

=== Function filename and namespace ===

If your function has dependencies or side-effects, it should be put into a class instead, in which the dependencies can be injected. Another alternative is to put the dependencies as argument in the function, although this muffles the relationship between input and output. Again, this is to increase testability.

Keep in mind that functions outside classes cannot be mocked, so only use them when you ''know'' you won't need to mock them.

todo, autoloading of functions and folder location

=== Assertions ===

NB: This is not assertions as used in unit-tests, but assertions as used to check invariants in production code.

Assertions can be used for mental checks. They are only used for internal logic - failed assertions are not supposed to be seen by the end user. For interaction with the outside world, like database or browser, exceptions should be used instead.

Assertions can be disabled in production mode and have then no runtime cost.

'''Example:'''

<syntaxhighlight lang="php">
/**
* Translation helper function
*
* @param string $sToTranslate
* @param string $sEscapeMode Valid values are html (this is the default, js and unescaped)
* @param string $sLanguage
* @return string
*/
function gT($sToTranslate, $sEscapeMode = 'html', $sLanguage = null)
{
assert(is_string($sToTranslate));
assert(strlen($sToTranslate) > 0);
assert($sEscapeMode === 'html' || $sEscapeMode === 'js' || $sEscapeMode === 'unescaped');
return quoteText(Yii::t('', $sToTranslate, array(), null, $sLanguage), $sEscapeMode);
}
</syntaxhighlight>

<hr>

=== Exceptions ===

todo

todo: exception hierarchy

todo: what can be repaired after exception? transaction rollback

* Exceptions are used to check inputs from the outside world (browser, database, file system)
* Don't use exceptions for control flow, only when fatal errors happen that make further execution impossible
* Exceptions should have clear error messages that make them ''actionable'' - there should be a clear "next step" for the user or developer
* Never, ever, do an empty catch-block

==== Alternatives to exceptions ====

Some people consider exceptions being a hidden form of "goto" which confuses the control flow of the program. They propose different other solutions:

* Return a tuple, like <code>[$result, $errorMessage]</code> where $errorMessage is null at success
* Return <code>null</code> at failure
* Tagged union result type (not yet possible in latest PHP)
* Result object

The con being that you have to manually propagate the error, where an exception can happen from anywhere in the stack trace without any other function knowing about it.

=== If-statements ===

If-statements should not be too long or hard to understand. If they are, consider factor out the checks into separate functions.

<syntaxhighlight lang="php">
if ((empty($instance->oOptions->{$attribute}))
|| (
!empty($instance->oOptions->{$attribute})
&& (
$instance->oOptions->{$attribute} === 'inherit'
|| $instance->oOptions->{$attribute} === 'I'
// NB: Do NOT use === here, it won't work with Postgresql.
|| $instance->oOptions->{$attribute} == '-1'
)
)
) {
</syntaxhighlight>

Can be shortened by factoring out method <code>isInherit</code>:

<syntaxhighlight lang="php">
if (empty($instance->options->{$attribute})
|| $this->isInherit($instance-options->{$attribute})) {
}
/**
* Returns true if $value is set to inherit
* @param mixed|null $value
* @return boolean
*/
public function isInherit($value) {
return !empty($value)
&& (
$value === 'inherit'
|| $value === 'I'
// NB: Do NOT use === here, it won't work with Postgresql.
|| $value == '-1'
);
}
</syntaxhighlight>

And one more time by using a variable for the value:

<syntaxhighlight lang="php">
$value = $instance->options->{$attribute};
if (empty($value) || $this->isInherit($value)) {
}
</syntaxhighlight>

More clear, right? "If it's empty or set to inherit, do this and that."

=== Variables ===

Descriptive naming.

* Follow PSR-12 - no underscore, use camelCaseLikeThis
* Variables of ActiveRecord classes can have same name as the class, like "$survey" or "$question"
* Add -s for plural when it's an array: "$surveys", "$questions"
* Never include "array" or "list" in variable names - using plural is enough
* The ''context'' of the function helps with variable naming, e..g "$name" might be fine in a function about questions; this is extra helpful when functions are short!
* When a function is short, it's much easier to figure out variable meaning based on context
* $qid, $gid, and $sid are so established in the code-base that they could be considered OK
* The -data suffix means "blob of stuff", only use it when needed, like with $viewData
* Use $result when baking a return value; add its exact type as @var annotation (worst possible name, acceptable but anything with more meaning is better)

Not so good:

<syntaxhighlight lang="php">
$result = LabelSet::model()->findAll();
</syntaxhighlight>

Better with model name and -s for plural:

<syntaxhighlight lang="php">
$labelSets = LabelSet::model()->findAll();
</syntaxhighlight>

* Do not use Hungarian notation (prefix with "type"), but instead <code>/** @var */</code> annotations - these can be checked automatically and will then be enforced to be correct, unlike Hungarian notation which can "rot"

<syntaxhighlight lang="php">
/** string[] An array of strings with 0-n elements */
$allFields = [];
</syntaxhighlight>

Psalm can infer types if the function documentation is enough. The strictness can be adjusted. Not all variables will need @var annotation, the tool will warn you when it's confused.

* Data that is sent to views as associative arrays will be:

<syntaxhighlight lang="php">
/** @var array Can be basically anything :( Better would be data-transfer objects or more precise notation */
$data = [];
// Maybe more clear as $viewData? Discuss.
</syntaxhighlight>

You can be more precise when you specify which type of array you're writing:

<syntaxhighlight lang="php">
/** @var array<string, string> This means the array key is string, and the array value is also string */
$data = [];
$data['name'] = 'Olle';
$data['occupation'] = 'Developer';
$data['age'] = 38; // ERROR! Value must be string.
</syntaxhighlight>

For more info about array type notation, see the [https://psalm.dev/docs/annotating_code/type_syntax/array_types/ Psalm documentation].

Some smaller examples:

<syntaxhighlight lang="php">
$theme = App()->request->getPost('theme'); // Should be $themeType - $theme looks like a model/AR
$gridid === 'questionthemes-grid'; // Should be $gridId with capital "I", since it's two words in English
$delete = Yii::app()->request->getParam('delete'); // Tuff one - $delete is ok? Thoughts?
$files = json_decode(stripslashes($sJSON), true); // $file is a resource, $files an array of resources, this is $fileData perhaps?
$valid_extensions_array = explode(",", $aAttributes['allowed_filetypes']); // Should be $validExtensionTypes
$language = Yii::app()->session['survey_' . $surveyid]['s_lang']; // TODO: Should this be a value class? Then Language::make(...);
$surveyInfo = getSurveyInfo($surveyId, $language); // OK, BUT should be a separate DTO!
$fieldMap = createFieldMap($survey, 'short', false, false, $language); // Same, make a DTO
$cquestions = array(); // What's "c"? Method name is getChildQuestions and $questions is an argument - better with $childQuestions?
</syntaxhighlight>

=== Looping ===

* The bodies of foreach-loops are often a good candidate to factor out into separate functions.

'''Example:'''

<syntaxhighlight lang="php">
foreach ($questions as $question) {
processQuestion($question);
}
</syntaxhighlight>

Note the variable naming from plural to singular.

* Loop indexing should be named i, j, k etc.

'''Example:'''

<syntaxhighlight lang="php">
for ($i = 0; $i < $length; $i++) {
for ($j = 0; $j < $otherLength; $j++) {
// ...
}
}
</syntaxhighlight>

<hr>

=== Function composition ===

todo, "doThisAndThat" --> "doThis(doThat())"

=== Cases ===

<syntaxhighlight lang="php">
/**
* This function generates an array containing the fieldcode, and matching data in the same order as the activate script
*
* @param Survey $survey Survey ActiveRecord model
* @param string $style 'short' (default) or 'full' - full creates extra information like default values
* @param boolean $force_refresh - Forces to really refresh the array, not just take the session copy
* @param bool|int $questionid Limit to a certain qid only (for question preview) - default is false
* @param string $sLanguage The language to use
* @param array $aDuplicateQIDs
* @return array
*/
function createFieldMap($survey, $style = 'short', $force_refresh = false, $questionid = false, $sLanguage = '', &$aDuplicateQIDs = array())
</syntaxhighlight>

'''Good:'''

* Name is verb and noun
* Each argument is documented (almost)

'''Bad:'''

* Returns "array", which can be anything. A separate class for "Fieldmap" would be better.
* Not clear if it should be "createFieldMap" or "createFieldmap" - is "fieldmap" one word or two?
* Very many boolean arguments. Should probably be a class with methods like <code>$fieldmapCreator->setForceRefresh(true);</code> instead.
* Too long.
* Doesn't elaborate on what "fieldmap" really is, and does not link to any documentation about it.
* Access super-global, which makes it hard to test. Should instead return a data-transfer object, like:<br><syntaxhighlight lang="php">
$_SESSION['fieldmap'] = createFieldMap(...);
</syntaxhighlight>
* Has no test
* Mixes Hungarian notation with non-Hungarian notation in the argument list

== Defensive programming and error handling ==

todo

* '''Fail hard, fail early'''. The earlier the program crashes when something is wrong, the lower is the probability that you'll end up with corrupt data in the database that will later require manual labor to correct.
* Fail with '''actionable information'''
* Check input to functions and throw <code>InvalidArgumentException</code> if it violates the function's pre-conditions
* Use assert for class-internal invariants
* Use assert to make assumptions explicit for the reader

== Documentation ==

=== PHPDoc ===

* All functions must have a proper docblock
* The first line of the docblock should describe the relation between ''all'' the input arguments and the output of the function in a single sentence
* Each parameter must have the correct type
* Don't use <code>array</code> as type if it's a list of object - instead, use <code>[]</code> like so: <code>Survey[]</code> for a list of surveys

=== Technical documentation ===

todo, UML, scenarios, use-cases

== The PHP of yesterday ==

Old idioms and habits that should be abandoned.

* Don't use associative arrays, almost never. Data-transfer objects have multiple benefits: they are clearly structured, can be documented, can enforce invariants. There's ''no'' performance overhead of objects compared to arrays in modern PHP.
* Objects are already passed by reference; arrays are value types
* Use <code>[]</code> instead of <code>array()</code>
* Hungarian notation was useful before static analysis existed for PHP. These days it's better to use something that can be checked automatically: docblock @param and inline @var annotations.

== The PHP of tomorrow ==

todo

Union tags

Short functions

Match expressions

== Security ==

todo

XSS

Database injection

Permissions and roles

== Performance ==

todo

Loading too many rows into PHP models

== Testing ==

todo

QA

PHPUnit

TDD

Mocks, can't mock functions, static methods, mocking as a DSL, PHPUnit mocking tools

Pure functions, referential transparency, side-effects

Unit, functional, integration

Don't test the framework; don't test PHP

Makes sure the function or class lives up to its specification; make sure it will ''always'' live up to its specification, even in the future, to avoid regressions.

== Static analysis ==

<code>php -l</code>, CodeSniffer, Mess Detector, Psalm

== Database design ==

todo

== JavaScript ==

todo

classes, functions, components, tests

== CSS ==

todo

== HTML ==

todo

== Resources ==

todo

Books, links, videos

Code quality guide

2021-04-21T15:24:20Z

Olle: /* Function filename and namespace */

DRAFT

== Prologue ==

# '''Be risk aware'''. Too good code can be a business risk (slow to write, maybe over-designed). Too sloppy code can also be a business risk (hard to maintain and understand). You have to find a balance that is adapted to the current situation and risk analysis, in which code quality becomes a '''risk mitigation''' technique among others.
# '''Be humble'''. LimeSurvey was made by developers from all over the world, with different age, education and experience. Your code might be read by a completely different team ten years from now, in the same way you are now reading code by developers that no longer work with us, but which work pays our rent.
# '''Performance matters sometimes''', and shouldn't be disregarded completely. In particular, database queries using the ORM and ActiveRecord can be problematic. Some surveys have thousands of questions and hundreds of thousands of responses. Fast response time is also important for a fluid user experience.
# '''It's harder to read code than to write code'''. Don't choose patterns that are easy or fast to write, but that are easy to read.
# Make your code '''communicate intent'''.
# It's easy to forget '''cross-cutting concerns''' like translation and security. Keep a mental note.
# '''Stress affects code quality''' and your risk behaviour. If your stress level is too high to write code with proper quality, take a step back and discuss it with your boss, or you'll push problems to the future.

== Quality ==

The purpose of this guide is to increase the quality of the LimeSurvey code-base. What is quality? Which aspects of quality can be measured? Which kind of company culture gives rise to appropriate code quality?

It's usually easier to get along what is "bad" code than what's "best" code. Blacklist instead of whitelist?

Quality attributes related to code quality:

* Readability
* Testability
* Maintainability
* Performance
* Security
* Reliability

Can not increase all at the same time - performance vs readability.

It's better to avoid emotional language when describing code quality, like "clean" or "dirty". Be precise, objective and suggest solutions.

Idiomatic code is more readable than non-idiomatic code. What's idiomatic depends on which context or domain you work in. We work in PHP and web application development, and have other idioms than in, say, functional or hardware-close programming.

Some code are "hot spots" - changed often. Those parts should require higher quality than other code.

== Risk ==

todo

data loss as most severe risk for LS

usability a business risk - hard to use or understand, people will choose another tool

risks relevant when fixing bugs

risks relevant when adding new features (lack of testing, wrong requirements, scope creep)

risks relevant when refactoring (regressions)

unit tests and QA as risk mitigation

partial deployment, alpha/beta/rc, risk communication

software rot, design pattern rot/grime, software evolution

rot = non-pattern related code

testing by community, bug fixing by community

== Modules ==

There's no inherit module functionality in PHP, but Yii has a module system. Libraries can be seen as a module system.

Examples of implicit modules in LimeSurvey:

* Front-end (survey taking)
* Back-end (survey design)
* Survey theme editing
* Expression manager
* Plugin system

In the future, they need to be separated and implemented more clearly as whatever Yii 3 module system is in use.

Some data models are common for all modules, e.g. surveys and users. Can have a "Common" module for such data.

todo, relation to Yii config system

== Classes ==

todo

* Avoid empty OOP ceremony, like defining getters and setters for all properties. Might as well make them public, ''unless'' they have invariants that need to be upheld, e.g. "this number is always between 1 and 10" or "this string is maximum length 20".
* Almost always avoid static methods. They cannot be mocked. One exception is (possibly) factory methods (Foo::make(...)).
* Inject all dependencies. This will make sure the class can be unit-tested (unit-tests have several benefits over integrity tests - they can be run in parallel and don't require any setup and teardown)
* A second way to achieve testability is to factor out the methods that access the dependencies

todo, state vs behaviour, state vs dependencies

=== OOP design ===

todo

Start from top-down, with domain, behaviour, interaction between objects, database design, pseudo-code if needed. Can also include scenarios, use-cases and UML diagrams.

Object reification - not only domain models, but also domain actions, relations and activities can be objects, e.g. a class ActivateSurvey or ExportSurvey.

Hierarchy depth.

Inheritance vs composition.

Multiple inheritance is done with traits. Use-case: ActiveRecords that support encryption, but not all.

=== Design pattern grime and software evolution ===

Design rot after time - how to keep it tight? (Grime.)

=== State ===

Keep a clear separation between classes with state and classes with no state.

todo, elaborate

=== Types of classes ===

Different categories of classes:

* Builders (e.g. query builder)
* Data-transfer object (no behaviour; pass to views to have better documentation and intent than associative arrays)
* Value classes (e.g. Email to wrap email string around)
* Command object (e.g. SurveyActivator)
* Helper (no state; e.g. QuestionAttributeHelper to bake attributes into different formats used by the views)
* Wrapper (also no state; e.g IOWrapper, to be able to mock file access)

todo, immutability, possible with private properties that are set in the constructor,

todo: command-query separation for classes?

=== Types of classes in LimeSurvey ===

* ActiveRecord, used to communicate with the database, and should not do ''anything'' else
* Controllers, used for glue code; should not contain business-logic
* Commands, same as controllers but from CLI
* Helper functions, should be short and obey command-query separation (TODO: Long functions should be separated into command objects or service classes); todo: should not have any dependencies?
* Helper classes, similar to helper functions but have dependencies that need to be mocked during tests; should not have any state
* Service classes, contains logic related to a clear and separate task, like create or import survey
* Question render classes, contains logic related to how questions are rendered (TODO: Need better separation between state and logic and more clear design); similar to widgets
* Plugin classes, using the plugin event system
* Widgets, containing HTML logic for custom HTML widgets
* Customizations to the Yii framework by inheritance
* Unit and functional test classes

A couple of classes contain only data, like LsDefaultDataSet.

todo, no difference between state property and dependency property in OOP

=== What is "glue code"? ===

todo

Putting the pieces together, e.g. service class A need data from model B, fetch it and run.

todo, add example

=== "Where do I cut?" ===

Separation of concerns, but which concerns and which type of separation?

=== Size ===

A class should have a single and clear purpose; compare with [https://en.wikipedia.org/wiki/SOLID SOLID].

=== Class name ===

* ActiveRecord classes are named after the database table they are bound to, but with singular instead of plural. E.g. table "lime_users" have model "User".
* Services classes are named after what they ''do'', e.g. SurveyCreator
* Helper classes should probably be named as specific as possible when possible, to avoid them from growing too big
* Follow the naming tradition of the framework with regard to controllers, e.g. UserController or UserAdministrationController.

== Functions ==

Functions are one of the fundamental building blocks of programming, so it's important to get it right.

Functions that are part of a class are called "methods", if you want to be formal.

Different types of functions in PHP:

* Functions (not attached to a class)
* Methods (attached to class)
* Anonymous functions (does not capture scope automatically)
* Short functions (does capture scope automatically)

I'm using "function" as a word for all types of functions in PHP below.

<hr>

=== Size ===

* A function should be short enough to be completely readable on one screen, approx 60 lines at most
* A function should not have too many arguments; if you have five or more, consider making it a class instead
* If a function is growing too big, it might be better to create a class instead or split it into several functions (if both functions have '''common state''', a class might be better, unless you want to pass around '''explicit state''')

=== Contract ===

* A function has a contract with its surrounding environment:
** Pre-condition: What needs to be true before the function is executed
** Post-condition: What will be true after the function has returned
* The function contract can be checked with assertions (internal invariants) or exceptions (outside world); see below
* Another good way is to use unit-tests to make sure the function's contract remains stable through changes
* The first line in the docblock should be one sentence describing the relation between function arguments and its output<br>Example<br><syntaxhighlight lang="php">
/**
* Creates a random password of length $length (defaults to 12)
* @param int $length
* @return string
*/
function createPassword($lenght = 12)

/**
* Creates an HTML language drop down for survey with id $surveyId, marking $selectedLanguage as selected
* @param int $surveyId
* @param string $selectedLanguage
* @return string <select> HTML
*/
function createLanguageDropdown($surveyId, $selectedLanguage)

</syntaxhighlight>

=== Push side-effects up in the stack trace ===

This one is a bit abstract.

First, what is a '''side-effect'''? In short, it's anything that happens in a function that ''is not'' described by the ''relation'' between function arguments and output.

Another way to phrase it is, that a side-effect is anything that is not always the same for the given input to a function; a function without any side-effects will always return the same result if it gets the same input.

'''Examples:'''

<syntaxhighlight lang="php">
// gT accesses the file system and will return different result depending on what's in the translation files
function gT($sToTranslate, $sEscapeMode = 'html', $sLanguage = null);

// If $sText and $sEscapeMode is always the same, quoteText() will always return the same string.
function quoteText($sText, $sEscapeMode = 'html');
</syntaxhighlight>

A function with no side-effects is called '''pure'''. A function that is guaranteed to always return (no exceptions, no errors, no warnings, no division by zero) is called '''total'''. Another name for purity is [https://en.wikipedia.org/wiki/Referential_transparency referential transparency].

It's a good thing if functions in a code-base ''either'' have side-effects, ''or'' return a result. Not both. This is called [https://en.wikipedia.org/wiki/Command%E2%80%93query_separation command-query separation].

Examples of side-effects:

* Database or file access
* Echo, or write to stdout or stderr
* Randomization

Why does this matter? Because side-effects make testing harder! '''If you have side-effects, you cannot create unit tests''', ''unless'' those side-effects can be mocked. If not, you need integrity tests with database setup or more. The more side-effects you have in a function, the more mocking is required to unit test it.

So, one solution to this is to move side-effects higher up in the stack trace, that is, move them to the calling code.

'''Example:'''

<syntaxhighlight lang="php">
function getSurveyInfo(int $surveyid, string $languagecode = '', boolean $force = false): array;
</syntaxhighlight>

Since this function takes $surveyid, we know it will probably query the database. Quering the database is a side-effect, and thus it requires a database scaffold for the test (or mocking, but the database connection is not injected, so there's no way to do it). One simple solution is to lift the side-effect out and pass in a Survey object instead:

<syntaxhighlight lang="php">
function getSurveyInfo(Survey $survey, string $languagecode = '', boolean $force = false): array;
</syntaxhighlight>

Much better! The side-effect of calling the database now happens ''before'' the function call. Now we can either mock a Survey object, or make an imitating stub for our test.

Reading the function body, there is in fact another database access, but since this is a relation to the Survey model, it could easily be moved out too. We've just made a function testable! Hooray!

This principle is rephrased in an architectural settings as [https://github.com/kbilsted/Functional-core-imperative-shell/blob/master/README.md functional core, imperative shell]. This architecture helps you get a good ratio between fast unit tests and slower integrity tests.

=== Function name ===

* The function name should tell you '''what''' it does; docs should tell you '''why''' (if this information is not obvious). '''How''' is described by the code itself (hopefully, but can in some cases be relevant to document).
* Function name can often be '''verb [+ adjective] + noun''', like "createFieldmap", "quoteText", "getRelativePath"
* Prefix with "is" for boolean functions

todo: difference between create, get, fetch, generate, ...

'''Good examples:'''

* gT() - An exception to descriptive function names; since this is used everywhere, the minimal name is motivated; maybe even name it "t()"?
* createPassword() - One verb, one noun - clear
* isCaptchaEnabled() - Using "is" signifies it returns boolean; clear purpose
* getFullResponseTable() - Verb, adjective, noun - but is "full" needed here? Is there a non-full version of the same function?
* replaceExpressionCodes() - Pretty good, but it's obvious that more information is needed in the docblock to describe what "replace" means, and what an "expression code" is
* fixCKeditorText() - "fix" is a bit vague, but maybe best there is? Pray that docblock contains information!

'''Bad examples:'''

* languageDropdown() - No verb, doesn't tell you what it does
* rmdirr() - Two r's, looks like a typo, but the last "r" actually means "recursive"!
* CSVUnquote() - Is CSV really the namespace? Why is the verb the second word?
* incompleteAnsFilterState() - One verb, but in the middle, or is "filter state" a noun?; why abbreviate "answer" to "ans"?
* reverseTranslateFieldNames() - Two verbs - did author mean "reverseTranslatedFieldNames"? Or "reverse and translate"? If so, it should be two functions, one for reverse and one for translate
* checkUploadedFileSizeAndRenderJson() - If you have an "and" in the function name, you should consider splitting it into two functions

<hr>

=== Function filename and namespace ===

If your function has dependencies or side-effects, it should be put into a class instead, in which the dependencies can be injected. Another alternative is to put the dependencies as argument in the function, although this muffles the relationship between input and output. Again, this is to increase testability.

Keep in mind that functions outside classes cannot be mocked, so only use them when you ''know'' you won't need to mock them.

todo, autoloading of functions and folder location

=== Assertions ===

NB: This is not assertions as used in unit-tests, but assertions as used to check invariants in production code.

Assertions can be used for mental checks. They are only used for internal logic - failed assertions are not supposed to be seen by the end user. For interaction with the outside world, like database or browser, exceptions should be used instead.

Assertions can be disabled in production mode and have then no runtime cost.

'''Example:'''

<syntaxhighlight lang="php">
/**
* Translation helper function
*
* @param string $sToTranslate
* @param string $sEscapeMode Valid values are html (this is the default, js and unescaped)
* @param string $sLanguage
* @return string
*/
function gT($sToTranslate, $sEscapeMode = 'html', $sLanguage = null)
{
assert(is_string($sToTranslate));
assert(strlen($sToTranslate) > 0);
assert($sEscapeMode === 'html' || $sEscapeMode === 'js' || $sEscapeMode === 'unescaped');
return quoteText(Yii::t('', $sToTranslate, array(), null, $sLanguage), $sEscapeMode);
}
</syntaxhighlight>

<hr>

=== Exceptions ===

todo

todo: exception hierarchy

todo: what can be repaired after exception? transaction rollback

* Exceptions are used to check inputs from the outside world (browser, database, file system)
* Don't use exceptions for control flow, only when fatal errors happen that make further execution impossible
* Exceptions should have clear error messages that make them ''actionable'' - there should be a clear "next step" for the user or developer
* Never, ever, do an empty catch-block

==== Alternatives to exceptions ====

Some people consider exceptions being a hidden form of "goto" which confuses the control flow of the program. They propose different other solutions:

* Return a tuple, like <code>[$result, $errorMessage]</code> where $errorMessage is null at success
* Return <code>null</code> at failure
* Tagged union result type (not yet possible in latest PHP)
* Result object

The con being that you have to manually propagate the error, where an exception can happen from anywhere in the stack trace without any other function knowing about it.

=== If-statements ===

If-statements should not be too long or hard to understand. If they are, consider factor out the checks into separate functions.

<syntaxhighlight lang="php">
if ((empty($instance->oOptions->{$attribute}))
|| (
!empty($instance->oOptions->{$attribute})
&& (
$instance->oOptions->{$attribute} === 'inherit'
|| $instance->oOptions->{$attribute} === 'I'
// NB: Do NOT use === here, it won't work with Postgresql.
|| $instance->oOptions->{$attribute} == '-1'
)
)
) {
</syntaxhighlight>

Can be shortened by factoring out method <code>isInherit</code>:

<syntaxhighlight lang="php">
if (empty($instance->options->{$attribute})
|| $this->isInherit($instance-options->{$attribute})) {
}
/**
* Returns true if $value is set to inherit
* @param mixed|null $value
* @return boolean
*/
public function isInherit($value) {
return !empty($value)
&& (
$value === 'inherit'
|| $value === 'I'
// NB: Do NOT use === here, it won't work with Postgresql.
|| $value == '-1'
);
}
</syntaxhighlight>

And one more time by using a variable for the value:

<syntaxhighlight lang="php">
$value = $instance->options->{$attribute};
if (empty($value) || $this->isInherit($value)) {
}
</syntaxhighlight>

More clear, right? "If it's empty or set to inherit, do this and that."

=== Variables ===

Descriptive naming.

* Follow PSR-12 - no underscore, use camelCaseLikeThis
* Variables of ActiveRecord classes can have same name as the class, like "$survey" or "$question"
* Add -s for plural when it's an array: "$surveys", "$questions"
* Never include "array" or "list" in variable names - using plural is enough
* The ''context'' of the function helps with variable naming, e..g "$name" might be fine in a function about questions; this is extra helpful when functions are short!
* When a function is short, it's much easier to figure out variable meaning based on context
* $qid, $gid, and $sid are so established in the code-base that they could be considered OK
* The -data suffix means "blob of stuff", only use it when needed, like with $viewData
* Use $result when baking a return value; add its exact type as @var annotation (worst possible name, acceptable but anything with more meaning is better)

Not so good:

<syntaxhighlight lang="php">
$result = LabelSet::model()->findAll();
</syntaxhighlight>

Better with model name and -s for plural:

<syntaxhighlight lang="php">
$labelSets = LabelSet::model()->findAll();
</syntaxhighlight>

* Do not use Hungarian notation (prefix with "type"), but instead <code>/** @var */</code> annotations - these can be checked automatically and will then be enforced to be correct, unlike Hungarian notation which can "rot"

<syntaxhighlight lang="php">
/** string[] An array of strings with 0-n elements */
$allFields = [];
</syntaxhighlight>

Psalm can infer types if the function documentation is enough. The strictness can be adjusted. Not all variables will need @var annotation, the tool will warn you when it's confused.

* Data that is sent to views as associative arrays will be:

<syntaxhighlight lang="php">
/** @var array Can be basically anything :( Better would be data-transfer objects or more precise notation */
$data = [];
// Maybe more clear as $viewData? Discuss.
</syntaxhighlight>

You can be more precise when you specify which type of array you're writing:

<syntaxhighlight lang="php">
/** @var array<string, string> This means the array key is string, and the array value is also string */
$data = [];
$data['name'] = 'Olle';
$data['occupation'] = 'Developer';
$data['age'] = 38; // ERROR! Value must be string.
</syntaxhighlight>

For more info about array type notation, see the [https://psalm.dev/docs/annotating_code/type_syntax/array_types/ Psalm documentation].

Some smaller examples:

<syntaxhighlight lang="php">
$theme = App()->request->getPost('theme'); // Should be $themeType - $theme looks like a model/AR
$gridid === 'questionthemes-grid'; // Should be $gridId with capital "I", since it's two words in English
$delete = Yii::app()->request->getParam('delete'); // Tuff one - $delete is ok? Thoughts?
$files = json_decode(stripslashes($sJSON), true); // $file is a resource, $files an array of resources, this is $fileData perhaps?
$valid_extensions_array = explode(",", $aAttributes['allowed_filetypes']); // Should be $validExtensionTypes
$language = Yii::app()->session['survey_' . $surveyid]['s_lang']; // TODO: Should this be a value class? Then Language::make(...);
$surveyInfo = getSurveyInfo($surveyId, $language); // OK, BUT should be a separate DTO!
$fieldMap = createFieldMap($survey, 'short', false, false, $language); // Same, make a DTO
$cquestions = array(); // What's "c"? Method name is getChildQuestions and $questions is an argument - better with $childQuestions?
</syntaxhighlight>

=== Looping ===

* The bodies of foreach-loops are often a good candidate to factor out into separate functions.

'''Example:'''

<syntaxhighlight lang="php">
foreach ($questions as $question) {
processQuestion($question);
}
</syntaxhighlight>

Note the variable naming from plural to singular.

* Loop indexing should be named i, j, k etc.

'''Example:'''

<syntaxhighlight lang="php">
for ($i = 0; $i < $length; $i++) {
for ($j = 0; $j < $otherLength; $j++) {
// ...
}
}
</syntaxhighlight>

<hr>

=== Function composition ===

todo, "doThisAndThat" --> "doThis(doThat())"

=== Cases ===

<syntaxhighlight lang="php">
/**
* This function generates an array containing the fieldcode, and matching data in the same order as the activate script
*
* @param Survey $survey Survey ActiveRecord model
* @param string $style 'short' (default) or 'full' - full creates extra information like default values
* @param boolean $force_refresh - Forces to really refresh the array, not just take the session copy
* @param bool|int $questionid Limit to a certain qid only (for question preview) - default is false
* @param string $sLanguage The language to use
* @param array $aDuplicateQIDs
* @return array
*/
function createFieldMap($survey, $style = 'short', $force_refresh = false, $questionid = false, $sLanguage = '', &$aDuplicateQIDs = array())
</syntaxhighlight>

'''Good:'''

* Name is verb and noun
* Each argument is documented (almost)

'''Bad:'''

* Returns "array", which can be anything. A separate class for "Fieldmap" would be better.
* Not clear if it should be "createFieldMap" or "createFieldmap" - is "fieldmap" one word or two?
* Very many boolean arguments. Should probably be a class with methods like <code>$fieldmapCreator->setForceRefresh(true);</code> instead.
* Too long.
* Doesn't elaborate on what "fieldmap" really is, and does not link to any documentation about it.
* Access super-global, which makes it hard to test. Should instead return a data-transfer object, like:<br><syntaxhighlight lang="php">
$_SESSION['fieldmap'] = createFieldMap(...);
</syntaxhighlight>
* Has no test
* Mixes Hungarian notation with non-Hungarian notation in the argument list

== Defensive programming and error handling ==

todo

* '''Fail hard, fail early'''. The earlier the program crashes when something is wrong, the lower is the probability that you'll end up with corrupt data in the database that will later require manual labor to correct.
* Fail with '''actionable information'''
* Check input to functions and throw <code>InvalidArgumentException</code> if it violates the function's pre-conditions
* Use assert for class-internal invariants
* Use assert to make assumptions explicit for the reader

== Documentation ==

=== PHPDoc ===

* All functions must have a proper docblock
* The first line of the docblock should describe the relation between ''all'' the input arguments and the output of the function in a single sentence
* Each parameter must have the correct type
* Don't use <code>array</code> as type if it's a list of object - instead, use <code>[]</code> like so: <code>Survey[]</code> for a list of surveys

=== Technical documentation ===

todo, UML, scenarios, use-cases

== The PHP of yesterday ==

Old idioms and habits that should be abandoned.

* Don't use associative arrays, almost never. Data-transfer objects have multiple benefits: they are clearly structured, can be documented, can enforce invariants. There's ''no'' performance overhead of objects compared to arrays in modern PHP.
* Objects are already passed by reference; arrays are value types
* Use <code>[]</code> instead of <code>array()</code>
* Hungarian notation was useful before static analysis existed for PHP. These days it's better to use something that can be checked automatically: docblock @param and inline @var annotations.

== The PHP of tomorrow ==

todo

Union tags

Short functions

Match expressions

== Security ==

todo

XSS

Database injection

Permissions and roles

== Performance ==

todo

Loading too many rows into PHP models

== Testing ==

todo

QA

PHPUnit

TDD

Mocks, can't mock functions, static methods, mocking as a DSL, PHPUnit mocking tools

Pure functions, referential transparency, side-effects

Unit, functional, integration

Don't test the framework; don't test PHP

Makes sure the function or class lives up to its specification; make sure it will ''always'' live up to its specification, even in the future, to avoid regressions.

== Static analysis ==

<code>php -l</code>, CodeSniffer, Mess Detector, Psalm

== Database design ==

todo

== JavaScript ==

todo

classes, functions, components, tests

== CSS ==

todo

== HTML ==

todo

== Resources ==

todo

Books, links, videos

Code quality guide

2021-04-21T13:08:04Z

Olle: /* Function filename and namespace */

DRAFT

== Prologue ==

# '''Be risk aware'''. Too good code can be a business risk (slow to write, maybe over-designed). Too sloppy code can also be a business risk (hard to maintain and understand). You have to find a balance that is adapted to the current situation and risk analysis, in which code quality becomes a '''risk mitigation''' technique among others.
# '''Be humble'''. LimeSurvey was made by developers from all over the world, with different age, education and experience. Your code might be read by a completely different team ten years from now, in the same way you are now reading code by developers that no longer work with us, but which work pays our rent.
# '''Performance matters sometimes''', and shouldn't be disregarded completely. In particular, database queries using the ORM and ActiveRecord can be problematic. Some surveys have thousands of questions and hundreds of thousands of responses. Fast response time is also important for a fluid user experience.
# '''It's harder to read code than to write code'''. Don't choose patterns that are easy or fast to write, but that are easy to read.
# Make your code '''communicate intent'''.
# It's easy to forget '''cross-cutting concerns''' like translation and security. Keep a mental note.
# '''Stress affects code quality''' and your risk behaviour. If your stress level is too high to write code with proper quality, take a step back and discuss it with your boss, or you'll push problems to the future.

== Quality ==

The purpose of this guide is to increase the quality of the LimeSurvey code-base. What is quality? Which aspects of quality can be measured? Which kind of company culture gives rise to appropriate code quality?

It's usually easier to get along what is "bad" code than what's "best" code. Blacklist instead of whitelist?

Quality attributes related to code quality:

* Readability
* Testability
* Maintainability
* Performance
* Security
* Reliability

Can not increase all at the same time - performance vs readability.

It's better to avoid emotional language when describing code quality, like "clean" or "dirty". Be precise, objective and suggest solutions.

Idiomatic code is more readable than non-idiomatic code. What's idiomatic depends on which context or domain you work in. We work in PHP and web application development, and have other idioms than in, say, functional or hardware-close programming.

Some code are "hot spots" - changed often. Those parts should require higher quality than other code.

== Risk ==

todo

data loss as most severe risk for LS

usability a business risk - hard to use or understand, people will choose another tool

risks relevant when fixing bugs

risks relevant when adding new features (lack of testing, wrong requirements, scope creep)

risks relevant when refactoring (regressions)

unit tests and QA as risk mitigation

partial deployment, alpha/beta/rc, risk communication

software rot, design pattern rot/grime, software evolution

rot = non-pattern related code

testing by community, bug fixing by community

== Modules ==

There's no inherit module functionality in PHP, but Yii has a module system. Libraries can be seen as a module system.

Examples of implicit modules in LimeSurvey:

* Front-end (survey taking)
* Back-end (survey design)
* Survey theme editing
* Expression manager
* Plugin system

In the future, they need to be separated and implemented more clearly as whatever Yii 3 module system is in use.

Some data models are common for all modules, e.g. surveys and users. Can have a "Common" module for such data.

todo, relation to Yii config system

== Classes ==

todo

* Avoid empty OOP ceremony, like defining getters and setters for all properties. Might as well make them public, ''unless'' they have invariants that need to be upheld, e.g. "this number is always between 1 and 10" or "this string is maximum length 20".
* Almost always avoid static methods. They cannot be mocked. One exception is (possibly) factory methods (Foo::make(...)).
* Inject all dependencies. This will make sure the class can be unit-tested (unit-tests have several benefits over integrity tests - they can be run in parallel and don't require any setup and teardown)
* A second way to achieve testability is to factor out the methods that access the dependencies

todo, state vs behaviour, state vs dependencies

=== OOP design ===

todo

Start from top-down, with domain, behaviour, interaction between objects, database design, pseudo-code if needed. Can also include scenarios, use-cases and UML diagrams.

Object reification - not only domain models, but also domain actions, relations and activities can be objects, e.g. a class ActivateSurvey or ExportSurvey.

Hierarchy depth.

Inheritance vs composition.

Multiple inheritance is done with traits. Use-case: ActiveRecords that support encryption, but not all.

=== Design pattern grime and software evolution ===

Design rot after time - how to keep it tight? (Grime.)

=== State ===

Keep a clear separation between classes with state and classes with no state.

todo, elaborate

=== Types of classes ===

Different categories of classes:

* Builders (e.g. query builder)
* Data-transfer object (no behaviour; pass to views to have better documentation and intent than associative arrays)
* Value classes (e.g. Email to wrap email string around)
* Command object (e.g. SurveyActivator)
* Helper (no state; e.g. QuestionAttributeHelper to bake attributes into different formats used by the views)
* Wrapper (also no state; e.g IOWrapper, to be able to mock file access)

todo, immutability, possible with private properties that are set in the constructor,

todo: command-query separation for classes?

=== Types of classes in LimeSurvey ===

* ActiveRecord, used to communicate with the database, and should not do ''anything'' else
* Controllers, used for glue code; should not contain business-logic
* Commands, same as controllers but from CLI
* Helper functions, should be short and obey command-query separation (TODO: Long functions should be separated into command objects or service classes); todo: should not have any dependencies?
* Helper classes, similar to helper functions but have dependencies that need to be mocked during tests; should not have any state
* Service classes, contains logic related to a clear and separate task, like create or import survey
* Question render classes, contains logic related to how questions are rendered (TODO: Need better separation between state and logic and more clear design); similar to widgets
* Plugin classes, using the plugin event system
* Widgets, containing HTML logic for custom HTML widgets
* Customizations to the Yii framework by inheritance
* Unit and functional test classes

A couple of classes contain only data, like LsDefaultDataSet.

todo, no difference between state property and dependency property in OOP

=== What is "glue code"? ===

todo

Putting the pieces together, e.g. service class A need data from model B, fetch it and run.

todo, add example

=== "Where do I cut?" ===

Separation of concerns, but which concerns and which type of separation?

=== Size ===

A class should have a single and clear purpose; compare with [https://en.wikipedia.org/wiki/SOLID SOLID].

=== Class name ===

* ActiveRecord classes are named after the database table they are bound to, but with singular instead of plural. E.g. table "lime_users" have model "User".
* Services classes are named after what they ''do'', e.g. SurveyCreator
* Helper classes should probably be named as specific as possible when possible, to avoid them from growing too big
* Follow the naming tradition of the framework with regard to controllers, e.g. UserController or UserAdministrationController.

== Functions ==

Functions are one of the fundamental building blocks of programming, so it's important to get it right.

Functions that are part of a class are called "methods", if you want to be formal.

Different types of functions in PHP:

* Functions (not attached to a class)
* Methods (attached to class)
* Anonymous functions (does not capture scope automatically)
* Short functions (does capture scope automatically)

I'm using "function" as a word for all types of functions in PHP below.

<hr>

=== Size ===

* A function should be short enough to be completely readable on one screen, approx 60 lines at most
* A function should not have too many arguments; if you have five or more, consider making it a class instead
* If a function is growing too big, it might be better to create a class instead or split it into several functions (if both functions have '''common state''', a class might be better, unless you want to pass around '''explicit state''')

=== Contract ===

* A function has a contract with its surrounding environment:
** Pre-condition: What needs to be true before the function is executed
** Post-condition: What will be true after the function has returned
* The function contract can be checked with assertions (internal invariants) or exceptions (outside world); see below
* Another good way is to use unit-tests to make sure the function's contract remains stable through changes
* The first line in the docblock should be one sentence describing the relation between function arguments and its output<br>Example<br><syntaxhighlight lang="php">
/**
* Creates a random password of length $length (defaults to 12)
* @param int $length
* @return string
*/
function createPassword($lenght = 12)

/**
* Creates an HTML language drop down for survey with id $surveyId, marking $selectedLanguage as selected
* @param int $surveyId
* @param string $selectedLanguage
* @return string <select> HTML
*/
function createLanguageDropdown($surveyId, $selectedLanguage)

</syntaxhighlight>

=== Push side-effects up in the stack trace ===

This one is a bit abstract.

First, what is a '''side-effect'''? In short, it's anything that happens in a function that ''is not'' described by the ''relation'' between function arguments and output.

Another way to phrase it is, that a side-effect is anything that is not always the same for the given input to a function; a function without any side-effects will always return the same result if it gets the same input.

'''Examples:'''

<syntaxhighlight lang="php">
// gT accesses the file system and will return different result depending on what's in the translation files
function gT($sToTranslate, $sEscapeMode = 'html', $sLanguage = null);

// If $sText and $sEscapeMode is always the same, quoteText() will always return the same string.
function quoteText($sText, $sEscapeMode = 'html');
</syntaxhighlight>

A function with no side-effects is called '''pure'''. A function that is guaranteed to always return (no exceptions, no errors, no warnings, no division by zero) is called '''total'''. Another name for purity is [https://en.wikipedia.org/wiki/Referential_transparency referential transparency].

It's a good thing if functions in a code-base ''either'' have side-effects, ''or'' return a result. Not both. This is called [https://en.wikipedia.org/wiki/Command%E2%80%93query_separation command-query separation].

Examples of side-effects:

* Database or file access
* Echo, or write to stdout or stderr
* Randomization

Why does this matter? Because side-effects make testing harder! '''If you have side-effects, you cannot create unit tests''', ''unless'' those side-effects can be mocked. If not, you need integrity tests with database setup or more. The more side-effects you have in a function, the more mocking is required to unit test it.

So, one solution to this is to move side-effects higher up in the stack trace, that is, move them to the calling code.

'''Example:'''

<syntaxhighlight lang="php">
function getSurveyInfo(int $surveyid, string $languagecode = '', boolean $force = false): array;
</syntaxhighlight>

Since this function takes $surveyid, we know it will probably query the database. Quering the database is a side-effect, and thus it requires a database scaffold for the test (or mocking, but the database connection is not injected, so there's no way to do it). One simple solution is to lift the side-effect out and pass in a Survey object instead:

<syntaxhighlight lang="php">
function getSurveyInfo(Survey $survey, string $languagecode = '', boolean $force = false): array;
</syntaxhighlight>

Much better! The side-effect of calling the database now happens ''before'' the function call. Now we can either mock a Survey object, or make an imitating stub for our test.

Reading the function body, there is in fact another database access, but since this is a relation to the Survey model, it could easily be moved out too. We've just made a function testable! Hooray!

This principle is rephrased in an architectural settings as [https://github.com/kbilsted/Functional-core-imperative-shell/blob/master/README.md functional core, imperative shell]. This architecture helps you get a good ratio between fast unit tests and slower integrity tests.

=== Function name ===

* The function name should tell you '''what''' it does; docs should tell you '''why''' (if this information is not obvious). '''How''' is described by the code itself (hopefully, but can in some cases be relevant to document).
* Function name can often be '''verb [+ adjective] + noun''', like "createFieldmap", "quoteText", "getRelativePath"
* Prefix with "is" for boolean functions

todo: difference between create, get, fetch, generate, ...

'''Good examples:'''

* gT() - An exception to descriptive function names; since this is used everywhere, the minimal name is motivated; maybe even name it "t()"?
* createPassword() - One verb, one noun - clear
* isCaptchaEnabled() - Using "is" signifies it returns boolean; clear purpose
* getFullResponseTable() - Verb, adjective, noun - but is "full" needed here? Is there a non-full version of the same function?
* replaceExpressionCodes() - Pretty good, but it's obvious that more information is needed in the docblock to describe what "replace" means, and what an "expression code" is
* fixCKeditorText() - "fix" is a bit vague, but maybe best there is? Pray that docblock contains information!

'''Bad examples:'''

* languageDropdown() - No verb, doesn't tell you what it does
* rmdirr() - Two r's, looks like a typo, but the last "r" actually means "recursive"!
* CSVUnquote() - Is CSV really the namespace? Why is the verb the second word?
* incompleteAnsFilterState() - One verb, but in the middle, or is "filter state" a noun?; why abbreviate "answer" to "ans"?
* reverseTranslateFieldNames() - Two verbs - did author mean "reverseTranslatedFieldNames"? Or "reverse and translate"? If so, it should be two functions, one for reverse and one for translate
* checkUploadedFileSizeAndRenderJson() - If you have an "and" in the function name, you should consider splitting it into two functions

<hr>

=== Function filename and namespace ===

If your function has dependencies, it should be put into a class instead, in which the dependencies can be injected. Another alternative is to put the dependencies as argument in the function, although this muffles the relationship between input and output. Again, this is to increase testability.

Keep in mind that functions outside classes cannot be mocked, so only use them when you ''know'' you won't need to mock them.

todo, autoloading of functions and folder location

=== Assertions ===

NB: This is not assertions as used in unit-tests, but assertions as used to check invariants in production code.

Assertions can be used for mental checks. They are only used for internal logic - failed assertions are not supposed to be seen by the end user. For interaction with the outside world, like database or browser, exceptions should be used instead.

Assertions can be disabled in production mode and have then no runtime cost.

'''Example:'''

<syntaxhighlight lang="php">
/**
* Translation helper function
*
* @param string $sToTranslate
* @param string $sEscapeMode Valid values are html (this is the default, js and unescaped)
* @param string $sLanguage
* @return string
*/
function gT($sToTranslate, $sEscapeMode = 'html', $sLanguage = null)
{
assert(is_string($sToTranslate));
assert(strlen($sToTranslate) > 0);
assert($sEscapeMode === 'html' || $sEscapeMode === 'js' || $sEscapeMode === 'unescaped');
return quoteText(Yii::t('', $sToTranslate, array(), null, $sLanguage), $sEscapeMode);
}
</syntaxhighlight>

<hr>

=== Exceptions ===

todo

todo: exception hierarchy

todo: what can be repaired after exception? transaction rollback

* Exceptions are used to check inputs from the outside world (browser, database, file system)
* Don't use exceptions for control flow, only when fatal errors happen that make further execution impossible
* Exceptions should have clear error messages that make them ''actionable'' - there should be a clear "next step" for the user or developer
* Never, ever, do an empty catch-block

==== Alternatives to exceptions ====

Some people consider exceptions being a hidden form of "goto" which confuses the control flow of the program. They propose different other solutions:

* Return a tuple, like <code>[$result, $errorMessage]</code> where $errorMessage is null at success
* Return <code>null</code> at failure
* Tagged union result type (not yet possible in latest PHP)
* Result object

The con being that you have to manually propagate the error, where an exception can happen from anywhere in the stack trace without any other function knowing about it.

=== If-statements ===

If-statements should not be too long or hard to understand. If they are, consider factor out the checks into separate functions.

<syntaxhighlight lang="php">
if ((empty($instance->oOptions->{$attribute}))
|| (
!empty($instance->oOptions->{$attribute})
&& (
$instance->oOptions->{$attribute} === 'inherit'
|| $instance->oOptions->{$attribute} === 'I'
// NB: Do NOT use === here, it won't work with Postgresql.
|| $instance->oOptions->{$attribute} == '-1'
)
)
) {
</syntaxhighlight>

Can be shortened by factoring out method <code>isInherit</code>:

<syntaxhighlight lang="php">
if (empty($instance->options->{$attribute})
|| $this->isInherit($instance-options->{$attribute})) {
}
/**
* Returns true if $value is set to inherit
* @param mixed|null $value
* @return boolean
*/
public function isInherit($value) {
return !empty($value)
&& (
$value === 'inherit'
|| $value === 'I'
// NB: Do NOT use === here, it won't work with Postgresql.
|| $value == '-1'
);
}
</syntaxhighlight>

And one more time by using a variable for the value:

<syntaxhighlight lang="php">
$value = $instance->options->{$attribute};
if (empty($value) || $this->isInherit($value)) {
}
</syntaxhighlight>

More clear, right? "If it's empty or set to inherit, do this and that."

=== Variables ===

Descriptive naming.

* Follow PSR-12 - no underscore, use camelCaseLikeThis
* Variables of ActiveRecord classes can have same name as the class, like "$survey" or "$question"
* Add -s for plural when it's an array: "$surveys", "$questions"
* Never include "array" or "list" in variable names - using plural is enough
* The ''context'' of the function helps with variable naming, e..g "$name" might be fine in a function about questions; this is extra helpful when functions are short!
* When a function is short, it's much easier to figure out variable meaning based on context
* $qid, $gid, and $sid are so established in the code-base that they could be considered OK
* The -data suffix means "blob of stuff", only use it when needed, like with $viewData
* Use $result when baking a return value; add its exact type as @var annotation (worst possible name, acceptable but anything with more meaning is better)

Not so good:

<syntaxhighlight lang="php">
$result = LabelSet::model()->findAll();
</syntaxhighlight>

Better with model name and -s for plural:

<syntaxhighlight lang="php">
$labelSets = LabelSet::model()->findAll();
</syntaxhighlight>

* Do not use Hungarian notation (prefix with "type"), but instead <code>/** @var */</code> annotations - these can be checked automatically and will then be enforced to be correct, unlike Hungarian notation which can "rot"

<syntaxhighlight lang="php">
/** string[] An array of strings with 0-n elements */
$allFields = [];
</syntaxhighlight>

Psalm can infer types if the function documentation is enough. The strictness can be adjusted. Not all variables will need @var annotation, the tool will warn you when it's confused.

* Data that is sent to views as associative arrays will be:

<syntaxhighlight lang="php">
/** @var array Can be basically anything :( Better would be data-transfer objects or more precise notation */
$data = [];
// Maybe more clear as $viewData? Discuss.
</syntaxhighlight>

You can be more precise when you specify which type of array you're writing:

<syntaxhighlight lang="php">
/** @var array<string, string> This means the array key is string, and the array value is also string */
$data = [];
$data['name'] = 'Olle';
$data['occupation'] = 'Developer';
$data['age'] = 38; // ERROR! Value must be string.
</syntaxhighlight>

For more info about array type notation, see the [https://psalm.dev/docs/annotating_code/type_syntax/array_types/ Psalm documentation].

Some smaller examples:

<syntaxhighlight lang="php">
$theme = App()->request->getPost('theme'); // Should be $themeType - $theme looks like a model/AR
$gridid === 'questionthemes-grid'; // Should be $gridId with capital "I", since it's two words in English
$delete = Yii::app()->request->getParam('delete'); // Tuff one - $delete is ok? Thoughts?
$files = json_decode(stripslashes($sJSON), true); // $file is a resource, $files an array of resources, this is $fileData perhaps?
$valid_extensions_array = explode(",", $aAttributes['allowed_filetypes']); // Should be $validExtensionTypes
$language = Yii::app()->session['survey_' . $surveyid]['s_lang']; // TODO: Should this be a value class? Then Language::make(...);
$surveyInfo = getSurveyInfo($surveyId, $language); // OK, BUT should be a separate DTO!
$fieldMap = createFieldMap($survey, 'short', false, false, $language); // Same, make a DTO
$cquestions = array(); // What's "c"? Method name is getChildQuestions and $questions is an argument - better with $childQuestions?
</syntaxhighlight>

=== Looping ===

* The bodies of foreach-loops are often a good candidate to factor out into separate functions.

'''Example:'''

<syntaxhighlight lang="php">
foreach ($questions as $question) {
processQuestion($question);
}
</syntaxhighlight>

Note the variable naming from plural to singular.

* Loop indexing should be named i, j, k etc.

'''Example:'''

<syntaxhighlight lang="php">
for ($i = 0; $i < $length; $i++) {
for ($j = 0; $j < $otherLength; $j++) {
// ...
}
}
</syntaxhighlight>

<hr>

=== Function composition ===

todo, "doThisAndThat" --> "doThis(doThat())"

=== Cases ===

<syntaxhighlight lang="php">
/**
* This function generates an array containing the fieldcode, and matching data in the same order as the activate script
*
* @param Survey $survey Survey ActiveRecord model
* @param string $style 'short' (default) or 'full' - full creates extra information like default values
* @param boolean $force_refresh - Forces to really refresh the array, not just take the session copy
* @param bool|int $questionid Limit to a certain qid only (for question preview) - default is false
* @param string $sLanguage The language to use
* @param array $aDuplicateQIDs
* @return array
*/
function createFieldMap($survey, $style = 'short', $force_refresh = false, $questionid = false, $sLanguage = '', &$aDuplicateQIDs = array())
</syntaxhighlight>

'''Good:'''

* Name is verb and noun
* Each argument is documented (almost)

'''Bad:'''

* Returns "array", which can be anything. A separate class for "Fieldmap" would be better.
* Not clear if it should be "createFieldMap" or "createFieldmap" - is "fieldmap" one word or two?
* Very many boolean arguments. Should probably be a class with methods like <code>$fieldmapCreator->setForceRefresh(true);</code> instead.
* Too long.
* Doesn't elaborate on what "fieldmap" really is, and does not link to any documentation about it.
* Access super-global, which makes it hard to test. Should instead return a data-transfer object, like:<br><syntaxhighlight lang="php">
$_SESSION['fieldmap'] = createFieldMap(...);
</syntaxhighlight>
* Has no test
* Mixes Hungarian notation with non-Hungarian notation in the argument list

== Defensive programming and error handling ==

todo

* '''Fail hard, fail early'''. The earlier the program crashes when something is wrong, the lower is the probability that you'll end up with corrupt data in the database that will later require manual labor to correct.
* Fail with '''actionable information'''
* Check input to functions and throw <code>InvalidArgumentException</code> if it violates the function's pre-conditions
* Use assert for class-internal invariants
* Use assert to make assumptions explicit for the reader

== Documentation ==

=== PHPDoc ===

* All functions must have a proper docblock
* The first line of the docblock should describe the relation between ''all'' the input arguments and the output of the function in a single sentence
* Each parameter must have the correct type
* Don't use <code>array</code> as type if it's a list of object - instead, use <code>[]</code> like so: <code>Survey[]</code> for a list of surveys

=== Technical documentation ===

todo, UML, scenarios, use-cases

== The PHP of yesterday ==

Old idioms and habits that should be abandoned.

* Don't use associative arrays, almost never. Data-transfer objects have multiple benefits: they are clearly structured, can be documented, can enforce invariants. There's ''no'' performance overhead of objects compared to arrays in modern PHP.
* Objects are already passed by reference; arrays are value types
* Use <code>[]</code> instead of <code>array()</code>
* Hungarian notation was useful before static analysis existed for PHP. These days it's better to use something that can be checked automatically: docblock @param and inline @var annotations.

== The PHP of tomorrow ==

todo

Union tags

Short functions

Match expressions

== Security ==

todo

XSS

Database injection

Permissions and roles

== Performance ==

todo

Loading too many rows into PHP models

== Testing ==

todo

QA

PHPUnit

TDD

Mocks, can't mock functions, static methods, mocking as a DSL, PHPUnit mocking tools

Pure functions, referential transparency, side-effects

Unit, functional, integration

Don't test the framework; don't test PHP

Makes sure the function or class lives up to its specification; make sure it will ''always'' live up to its specification, even in the future, to avoid regressions.

== Static analysis ==

<code>php -l</code>, CodeSniffer, Mess Detector, Psalm

== Database design ==

todo

== JavaScript ==

todo

classes, functions, components, tests

== CSS ==

todo

== HTML ==

todo

== Resources ==

todo

Books, links, videos

Code quality guide

2021-04-21T13:07:49Z

Olle: /* Function filename and namespace */

DRAFT

== Prologue ==

# '''Be risk aware'''. Too good code can be a business risk (slow to write, maybe over-designed). Too sloppy code can also be a business risk (hard to maintain and understand). You have to find a balance that is adapted to the current situation and risk analysis, in which code quality becomes a '''risk mitigation''' technique among others.
# '''Be humble'''. LimeSurvey was made by developers from all over the world, with different age, education and experience. Your code might be read by a completely different team ten years from now, in the same way you are now reading code by developers that no longer work with us, but which work pays our rent.
# '''Performance matters sometimes''', and shouldn't be disregarded completely. In particular, database queries using the ORM and ActiveRecord can be problematic. Some surveys have thousands of questions and hundreds of thousands of responses. Fast response time is also important for a fluid user experience.
# '''It's harder to read code than to write code'''. Don't choose patterns that are easy or fast to write, but that are easy to read.
# Make your code '''communicate intent'''.
# It's easy to forget '''cross-cutting concerns''' like translation and security. Keep a mental note.
# '''Stress affects code quality''' and your risk behaviour. If your stress level is too high to write code with proper quality, take a step back and discuss it with your boss, or you'll push problems to the future.

== Quality ==

The purpose of this guide is to increase the quality of the LimeSurvey code-base. What is quality? Which aspects of quality can be measured? Which kind of company culture gives rise to appropriate code quality?

It's usually easier to get along what is "bad" code than what's "best" code. Blacklist instead of whitelist?

Quality attributes related to code quality:

* Readability
* Testability
* Maintainability
* Performance
* Security
* Reliability

Can not increase all at the same time - performance vs readability.

It's better to avoid emotional language when describing code quality, like "clean" or "dirty". Be precise, objective and suggest solutions.

Idiomatic code is more readable than non-idiomatic code. What's idiomatic depends on which context or domain you work in. We work in PHP and web application development, and have other idioms than in, say, functional or hardware-close programming.

Some code are "hot spots" - changed often. Those parts should require higher quality than other code.

== Risk ==

todo

data loss as most severe risk for LS

usability a business risk - hard to use or understand, people will choose another tool

risks relevant when fixing bugs

risks relevant when adding new features (lack of testing, wrong requirements, scope creep)

risks relevant when refactoring (regressions)

unit tests and QA as risk mitigation

partial deployment, alpha/beta/rc, risk communication

software rot, design pattern rot/grime, software evolution

rot = non-pattern related code

testing by community, bug fixing by community

== Modules ==

There's no inherit module functionality in PHP, but Yii has a module system. Libraries can be seen as a module system.

Examples of implicit modules in LimeSurvey:

* Front-end (survey taking)
* Back-end (survey design)
* Survey theme editing
* Expression manager
* Plugin system

In the future, they need to be separated and implemented more clearly as whatever Yii 3 module system is in use.

Some data models are common for all modules, e.g. surveys and users. Can have a "Common" module for such data.

todo, relation to Yii config system

== Classes ==

todo

* Avoid empty OOP ceremony, like defining getters and setters for all properties. Might as well make them public, ''unless'' they have invariants that need to be upheld, e.g. "this number is always between 1 and 10" or "this string is maximum length 20".
* Almost always avoid static methods. They cannot be mocked. One exception is (possibly) factory methods (Foo::make(...)).
* Inject all dependencies. This will make sure the class can be unit-tested (unit-tests have several benefits over integrity tests - they can be run in parallel and don't require any setup and teardown)
* A second way to achieve testability is to factor out the methods that access the dependencies

todo, state vs behaviour, state vs dependencies

=== OOP design ===

todo

Start from top-down, with domain, behaviour, interaction between objects, database design, pseudo-code if needed. Can also include scenarios, use-cases and UML diagrams.

Object reification - not only domain models, but also domain actions, relations and activities can be objects, e.g. a class ActivateSurvey or ExportSurvey.

Hierarchy depth.

Inheritance vs composition.

Multiple inheritance is done with traits. Use-case: ActiveRecords that support encryption, but not all.

=== Design pattern grime and software evolution ===

Design rot after time - how to keep it tight? (Grime.)

=== State ===

Keep a clear separation between classes with state and classes with no state.

todo, elaborate

=== Types of classes ===

Different categories of classes:

* Builders (e.g. query builder)
* Data-transfer object (no behaviour; pass to views to have better documentation and intent than associative arrays)
* Value classes (e.g. Email to wrap email string around)
* Command object (e.g. SurveyActivator)
* Helper (no state; e.g. QuestionAttributeHelper to bake attributes into different formats used by the views)
* Wrapper (also no state; e.g IOWrapper, to be able to mock file access)

todo, immutability, possible with private properties that are set in the constructor,

todo: command-query separation for classes?

=== Types of classes in LimeSurvey ===

* ActiveRecord, used to communicate with the database, and should not do ''anything'' else
* Controllers, used for glue code; should not contain business-logic
* Commands, same as controllers but from CLI
* Helper functions, should be short and obey command-query separation (TODO: Long functions should be separated into command objects or service classes); todo: should not have any dependencies?
* Helper classes, similar to helper functions but have dependencies that need to be mocked during tests; should not have any state
* Service classes, contains logic related to a clear and separate task, like create or import survey
* Question render classes, contains logic related to how questions are rendered (TODO: Need better separation between state and logic and more clear design); similar to widgets
* Plugin classes, using the plugin event system
* Widgets, containing HTML logic for custom HTML widgets
* Customizations to the Yii framework by inheritance
* Unit and functional test classes

A couple of classes contain only data, like LsDefaultDataSet.

todo, no difference between state property and dependency property in OOP

=== What is "glue code"? ===

todo

Putting the pieces together, e.g. service class A need data from model B, fetch it and run.

todo, add example

=== "Where do I cut?" ===

Separation of concerns, but which concerns and which type of separation?

=== Size ===

A class should have a single and clear purpose; compare with [https://en.wikipedia.org/wiki/SOLID SOLID].

=== Class name ===

* ActiveRecord classes are named after the database table they are bound to, but with singular instead of plural. E.g. table "lime_users" have model "User".
* Services classes are named after what they ''do'', e.g. SurveyCreator
* Helper classes should probably be named as specific as possible when possible, to avoid them from growing too big
* Follow the naming tradition of the framework with regard to controllers, e.g. UserController or UserAdministrationController.

== Functions ==

Functions are one of the fundamental building blocks of programming, so it's important to get it right.

Functions that are part of a class are called "methods", if you want to be formal.

Different types of functions in PHP:

* Functions (not attached to a class)
* Methods (attached to class)
* Anonymous functions (does not capture scope automatically)
* Short functions (does capture scope automatically)

I'm using "function" as a word for all types of functions in PHP below.

<hr>

=== Size ===

* A function should be short enough to be completely readable on one screen, approx 60 lines at most
* A function should not have too many arguments; if you have five or more, consider making it a class instead
* If a function is growing too big, it might be better to create a class instead or split it into several functions (if both functions have '''common state''', a class might be better, unless you want to pass around '''explicit state''')

=== Contract ===

* A function has a contract with its surrounding environment:
** Pre-condition: What needs to be true before the function is executed
** Post-condition: What will be true after the function has returned
* The function contract can be checked with assertions (internal invariants) or exceptions (outside world); see below
* Another good way is to use unit-tests to make sure the function's contract remains stable through changes
* The first line in the docblock should be one sentence describing the relation between function arguments and its output<br>Example<br><syntaxhighlight lang="php">
/**
* Creates a random password of length $length (defaults to 12)
* @param int $length
* @return string
*/
function createPassword($lenght = 12)

/**
* Creates an HTML language drop down for survey with id $surveyId, marking $selectedLanguage as selected
* @param int $surveyId
* @param string $selectedLanguage
* @return string <select> HTML
*/
function createLanguageDropdown($surveyId, $selectedLanguage)

</syntaxhighlight>

=== Push side-effects up in the stack trace ===

This one is a bit abstract.

First, what is a '''side-effect'''? In short, it's anything that happens in a function that ''is not'' described by the ''relation'' between function arguments and output.

Another way to phrase it is, that a side-effect is anything that is not always the same for the given input to a function; a function without any side-effects will always return the same result if it gets the same input.

'''Examples:'''

<syntaxhighlight lang="php">
// gT accesses the file system and will return different result depending on what's in the translation files
function gT($sToTranslate, $sEscapeMode = 'html', $sLanguage = null);

// If $sText and $sEscapeMode is always the same, quoteText() will always return the same string.
function quoteText($sText, $sEscapeMode = 'html');
</syntaxhighlight>

A function with no side-effects is called '''pure'''. A function that is guaranteed to always return (no exceptions, no errors, no warnings, no division by zero) is called '''total'''. Another name for purity is [https://en.wikipedia.org/wiki/Referential_transparency referential transparency].

It's a good thing if functions in a code-base ''either'' have side-effects, ''or'' return a result. Not both. This is called [https://en.wikipedia.org/wiki/Command%E2%80%93query_separation command-query separation].

Examples of side-effects:

* Database or file access
* Echo, or write to stdout or stderr
* Randomization

Why does this matter? Because side-effects make testing harder! '''If you have side-effects, you cannot create unit tests''', ''unless'' those side-effects can be mocked. If not, you need integrity tests with database setup or more. The more side-effects you have in a function, the more mocking is required to unit test it.

So, one solution to this is to move side-effects higher up in the stack trace, that is, move them to the calling code.

'''Example:'''

<syntaxhighlight lang="php">
function getSurveyInfo(int $surveyid, string $languagecode = '', boolean $force = false): array;
</syntaxhighlight>

Since this function takes $surveyid, we know it will probably query the database. Quering the database is a side-effect, and thus it requires a database scaffold for the test (or mocking, but the database connection is not injected, so there's no way to do it). One simple solution is to lift the side-effect out and pass in a Survey object instead:

<syntaxhighlight lang="php">
function getSurveyInfo(Survey $survey, string $languagecode = '', boolean $force = false): array;
</syntaxhighlight>

Much better! The side-effect of calling the database now happens ''before'' the function call. Now we can either mock a Survey object, or make an imitating stub for our test.

Reading the function body, there is in fact another database access, but since this is a relation to the Survey model, it could easily be moved out too. We've just made a function testable! Hooray!

This principle is rephrased in an architectural settings as [https://github.com/kbilsted/Functional-core-imperative-shell/blob/master/README.md functional core, imperative shell]. This architecture helps you get a good ratio between fast unit tests and slower integrity tests.

=== Function name ===

* The function name should tell you '''what''' it does; docs should tell you '''why''' (if this information is not obvious). '''How''' is described by the code itself (hopefully, but can in some cases be relevant to document).
* Function name can often be '''verb [+ adjective] + noun''', like "createFieldmap", "quoteText", "getRelativePath"
* Prefix with "is" for boolean functions

todo: difference between create, get, fetch, generate, ...

'''Good examples:'''

* gT() - An exception to descriptive function names; since this is used everywhere, the minimal name is motivated; maybe even name it "t()"?
* createPassword() - One verb, one noun - clear
* isCaptchaEnabled() - Using "is" signifies it returns boolean; clear purpose
* getFullResponseTable() - Verb, adjective, noun - but is "full" needed here? Is there a non-full version of the same function?
* replaceExpressionCodes() - Pretty good, but it's obvious that more information is needed in the docblock to describe what "replace" means, and what an "expression code" is
* fixCKeditorText() - "fix" is a bit vague, but maybe best there is? Pray that docblock contains information!

'''Bad examples:'''

* languageDropdown() - No verb, doesn't tell you what it does
* rmdirr() - Two r's, looks like a typo, but the last "r" actually means "recursive"!
* CSVUnquote() - Is CSV really the namespace? Why is the verb the second word?
* incompleteAnsFilterState() - One verb, but in the middle, or is "filter state" a noun?; why abbreviate "answer" to "ans"?
* reverseTranslateFieldNames() - Two verbs - did author mean "reverseTranslatedFieldNames"? Or "reverse and translate"? If so, it should be two functions, one for reverse and one for translate
* checkUploadedFileSizeAndRenderJson() - If you have an "and" in the function name, you should consider splitting it into two functions

<hr>

=== Function filename and namespace ===

If your function has dependencies, it should be put into a class instead, in which the dependencies can be injected. Another alternative is to put the dependencies as argument in the function, although this muffles the relationship between input and output. Again, this is to increase testability.

Keep in mind that functions outside classes cannot be mocked, so only use them when you ''know'' you won't need to mock it.

todo, autoloading of functions and folder location

=== Assertions ===

NB: This is not assertions as used in unit-tests, but assertions as used to check invariants in production code.

Assertions can be used for mental checks. They are only used for internal logic - failed assertions are not supposed to be seen by the end user. For interaction with the outside world, like database or browser, exceptions should be used instead.

Assertions can be disabled in production mode and have then no runtime cost.

'''Example:'''

<syntaxhighlight lang="php">
/**
* Translation helper function
*
* @param string $sToTranslate
* @param string $sEscapeMode Valid values are html (this is the default, js and unescaped)
* @param string $sLanguage
* @return string
*/
function gT($sToTranslate, $sEscapeMode = 'html', $sLanguage = null)
{
assert(is_string($sToTranslate));
assert(strlen($sToTranslate) > 0);
assert($sEscapeMode === 'html' || $sEscapeMode === 'js' || $sEscapeMode === 'unescaped');
return quoteText(Yii::t('', $sToTranslate, array(), null, $sLanguage), $sEscapeMode);
}
</syntaxhighlight>

<hr>

=== Exceptions ===

todo

todo: exception hierarchy

todo: what can be repaired after exception? transaction rollback

* Exceptions are used to check inputs from the outside world (browser, database, file system)
* Don't use exceptions for control flow, only when fatal errors happen that make further execution impossible
* Exceptions should have clear error messages that make them ''actionable'' - there should be a clear "next step" for the user or developer
* Never, ever, do an empty catch-block

==== Alternatives to exceptions ====

Some people consider exceptions being a hidden form of "goto" which confuses the control flow of the program. They propose different other solutions:

* Return a tuple, like <code>[$result, $errorMessage]</code> where $errorMessage is null at success
* Return <code>null</code> at failure
* Tagged union result type (not yet possible in latest PHP)
* Result object

The con being that you have to manually propagate the error, where an exception can happen from anywhere in the stack trace without any other function knowing about it.

=== If-statements ===

If-statements should not be too long or hard to understand. If they are, consider factor out the checks into separate functions.

<syntaxhighlight lang="php">
if ((empty($instance->oOptions->{$attribute}))
|| (
!empty($instance->oOptions->{$attribute})
&& (
$instance->oOptions->{$attribute} === 'inherit'
|| $instance->oOptions->{$attribute} === 'I'
// NB: Do NOT use === here, it won't work with Postgresql.
|| $instance->oOptions->{$attribute} == '-1'
)
)
) {
</syntaxhighlight>

Can be shortened by factoring out method <code>isInherit</code>:

<syntaxhighlight lang="php">
if (empty($instance->options->{$attribute})
|| $this->isInherit($instance-options->{$attribute})) {
}
/**
* Returns true if $value is set to inherit
* @param mixed|null $value
* @return boolean
*/
public function isInherit($value) {
return !empty($value)
&& (
$value === 'inherit'
|| $value === 'I'
// NB: Do NOT use === here, it won't work with Postgresql.
|| $value == '-1'
);
}
</syntaxhighlight>

And one more time by using a variable for the value:

<syntaxhighlight lang="php">
$value = $instance->options->{$attribute};
if (empty($value) || $this->isInherit($value)) {
}
</syntaxhighlight>

More clear, right? "If it's empty or set to inherit, do this and that."

=== Variables ===

Descriptive naming.

* Follow PSR-12 - no underscore, use camelCaseLikeThis
* Variables of ActiveRecord classes can have same name as the class, like "$survey" or "$question"
* Add -s for plural when it's an array: "$surveys", "$questions"
* Never include "array" or "list" in variable names - using plural is enough
* The ''context'' of the function helps with variable naming, e..g "$name" might be fine in a function about questions; this is extra helpful when functions are short!
* When a function is short, it's much easier to figure out variable meaning based on context
* $qid, $gid, and $sid are so established in the code-base that they could be considered OK
* The -data suffix means "blob of stuff", only use it when needed, like with $viewData
* Use $result when baking a return value; add its exact type as @var annotation (worst possible name, acceptable but anything with more meaning is better)

Not so good:

<syntaxhighlight lang="php">
$result = LabelSet::model()->findAll();
</syntaxhighlight>

Better with model name and -s for plural:

<syntaxhighlight lang="php">
$labelSets = LabelSet::model()->findAll();
</syntaxhighlight>

* Do not use Hungarian notation (prefix with "type"), but instead <code>/** @var */</code> annotations - these can be checked automatically and will then be enforced to be correct, unlike Hungarian notation which can "rot"

<syntaxhighlight lang="php">
/** string[] An array of strings with 0-n elements */
$allFields = [];
</syntaxhighlight>

Psalm can infer types if the function documentation is enough. The strictness can be adjusted. Not all variables will need @var annotation, the tool will warn you when it's confused.

* Data that is sent to views as associative arrays will be:

<syntaxhighlight lang="php">
/** @var array Can be basically anything :( Better would be data-transfer objects or more precise notation */
$data = [];
// Maybe more clear as $viewData? Discuss.
</syntaxhighlight>

You can be more precise when you specify which type of array you're writing:

<syntaxhighlight lang="php">
/** @var array<string, string> This means the array key is string, and the array value is also string */
$data = [];
$data['name'] = 'Olle';
$data['occupation'] = 'Developer';
$data['age'] = 38; // ERROR! Value must be string.
</syntaxhighlight>

For more info about array type notation, see the [https://psalm.dev/docs/annotating_code/type_syntax/array_types/ Psalm documentation].

Some smaller examples:

<syntaxhighlight lang="php">
$theme = App()->request->getPost('theme'); // Should be $themeType - $theme looks like a model/AR
$gridid === 'questionthemes-grid'; // Should be $gridId with capital "I", since it's two words in English
$delete = Yii::app()->request->getParam('delete'); // Tuff one - $delete is ok? Thoughts?
$files = json_decode(stripslashes($sJSON), true); // $file is a resource, $files an array of resources, this is $fileData perhaps?
$valid_extensions_array = explode(",", $aAttributes['allowed_filetypes']); // Should be $validExtensionTypes
$language = Yii::app()->session['survey_' . $surveyid]['s_lang']; // TODO: Should this be a value class? Then Language::make(...);
$surveyInfo = getSurveyInfo($surveyId, $language); // OK, BUT should be a separate DTO!
$fieldMap = createFieldMap($survey, 'short', false, false, $language); // Same, make a DTO
$cquestions = array(); // What's "c"? Method name is getChildQuestions and $questions is an argument - better with $childQuestions?
</syntaxhighlight>

=== Looping ===

* The bodies of foreach-loops are often a good candidate to factor out into separate functions.

'''Example:'''

<syntaxhighlight lang="php">
foreach ($questions as $question) {
processQuestion($question);
}
</syntaxhighlight>

Note the variable naming from plural to singular.

* Loop indexing should be named i, j, k etc.

'''Example:'''

<syntaxhighlight lang="php">
for ($i = 0; $i < $length; $i++) {
for ($j = 0; $j < $otherLength; $j++) {
// ...
}
}
</syntaxhighlight>

<hr>

=== Function composition ===

todo, "doThisAndThat" --> "doThis(doThat())"

=== Cases ===

<syntaxhighlight lang="php">
/**
* This function generates an array containing the fieldcode, and matching data in the same order as the activate script
*
* @param Survey $survey Survey ActiveRecord model
* @param string $style 'short' (default) or 'full' - full creates extra information like default values
* @param boolean $force_refresh - Forces to really refresh the array, not just take the session copy
* @param bool|int $questionid Limit to a certain qid only (for question preview) - default is false
* @param string $sLanguage The language to use
* @param array $aDuplicateQIDs
* @return array
*/
function createFieldMap($survey, $style = 'short', $force_refresh = false, $questionid = false, $sLanguage = '', &$aDuplicateQIDs = array())
</syntaxhighlight>

'''Good:'''

* Name is verb and noun
* Each argument is documented (almost)

'''Bad:'''

* Returns "array", which can be anything. A separate class for "Fieldmap" would be better.
* Not clear if it should be "createFieldMap" or "createFieldmap" - is "fieldmap" one word or two?
* Very many boolean arguments. Should probably be a class with methods like <code>$fieldmapCreator->setForceRefresh(true);</code> instead.
* Too long.
* Doesn't elaborate on what "fieldmap" really is, and does not link to any documentation about it.
* Access super-global, which makes it hard to test. Should instead return a data-transfer object, like:<br><syntaxhighlight lang="php">
$_SESSION['fieldmap'] = createFieldMap(...);
</syntaxhighlight>
* Has no test
* Mixes Hungarian notation with non-Hungarian notation in the argument list

== Defensive programming and error handling ==

todo

* '''Fail hard, fail early'''. The earlier the program crashes when something is wrong, the lower is the probability that you'll end up with corrupt data in the database that will later require manual labor to correct.
* Fail with '''actionable information'''
* Check input to functions and throw <code>InvalidArgumentException</code> if it violates the function's pre-conditions
* Use assert for class-internal invariants
* Use assert to make assumptions explicit for the reader

== Documentation ==

=== PHPDoc ===

* All functions must have a proper docblock
* The first line of the docblock should describe the relation between ''all'' the input arguments and the output of the function in a single sentence
* Each parameter must have the correct type
* Don't use <code>array</code> as type if it's a list of object - instead, use <code>[]</code> like so: <code>Survey[]</code> for a list of surveys

=== Technical documentation ===

todo, UML, scenarios, use-cases

== The PHP of yesterday ==

Old idioms and habits that should be abandoned.

* Don't use associative arrays, almost never. Data-transfer objects have multiple benefits: they are clearly structured, can be documented, can enforce invariants. There's ''no'' performance overhead of objects compared to arrays in modern PHP.
* Objects are already passed by reference; arrays are value types
* Use <code>[]</code> instead of <code>array()</code>
* Hungarian notation was useful before static analysis existed for PHP. These days it's better to use something that can be checked automatically: docblock @param and inline @var annotations.

== The PHP of tomorrow ==

todo

Union tags

Short functions

Match expressions

== Security ==

todo

XSS

Database injection

Permissions and roles

== Performance ==

todo

Loading too many rows into PHP models

== Testing ==

todo

QA

PHPUnit

TDD

Mocks, can't mock functions, static methods, mocking as a DSL, PHPUnit mocking tools

Pure functions, referential transparency, side-effects

Unit, functional, integration

Don't test the framework; don't test PHP

Makes sure the function or class lives up to its specification; make sure it will ''always'' live up to its specification, even in the future, to avoid regressions.

== Static analysis ==

<code>php -l</code>, CodeSniffer, Mess Detector, Psalm

== Database design ==

todo

== JavaScript ==

todo

classes, functions, components, tests

== CSS ==

todo

== HTML ==

todo

== Resources ==

todo

Books, links, videos

Code quality guide

2021-04-21T13:07:13Z

Olle: /* Function name */

DRAFT

== Prologue ==

# '''Be risk aware'''. Too good code can be a business risk (slow to write, maybe over-designed). Too sloppy code can also be a business risk (hard to maintain and understand). You have to find a balance that is adapted to the current situation and risk analysis, in which code quality becomes a '''risk mitigation''' technique among others.
# '''Be humble'''. LimeSurvey was made by developers from all over the world, with different age, education and experience. Your code might be read by a completely different team ten years from now, in the same way you are now reading code by developers that no longer work with us, but which work pays our rent.
# '''Performance matters sometimes''', and shouldn't be disregarded completely. In particular, database queries using the ORM and ActiveRecord can be problematic. Some surveys have thousands of questions and hundreds of thousands of responses. Fast response time is also important for a fluid user experience.
# '''It's harder to read code than to write code'''. Don't choose patterns that are easy or fast to write, but that are easy to read.
# Make your code '''communicate intent'''.
# It's easy to forget '''cross-cutting concerns''' like translation and security. Keep a mental note.
# '''Stress affects code quality''' and your risk behaviour. If your stress level is too high to write code with proper quality, take a step back and discuss it with your boss, or you'll push problems to the future.

== Quality ==

The purpose of this guide is to increase the quality of the LimeSurvey code-base. What is quality? Which aspects of quality can be measured? Which kind of company culture gives rise to appropriate code quality?

It's usually easier to get along what is "bad" code than what's "best" code. Blacklist instead of whitelist?

Quality attributes related to code quality:

* Readability
* Testability
* Maintainability
* Performance
* Security
* Reliability

Can not increase all at the same time - performance vs readability.

It's better to avoid emotional language when describing code quality, like "clean" or "dirty". Be precise, objective and suggest solutions.

Idiomatic code is more readable than non-idiomatic code. What's idiomatic depends on which context or domain you work in. We work in PHP and web application development, and have other idioms than in, say, functional or hardware-close programming.

Some code are "hot spots" - changed often. Those parts should require higher quality than other code.

== Risk ==

todo

data loss as most severe risk for LS

usability a business risk - hard to use or understand, people will choose another tool

risks relevant when fixing bugs

risks relevant when adding new features (lack of testing, wrong requirements, scope creep)

risks relevant when refactoring (regressions)

unit tests and QA as risk mitigation

partial deployment, alpha/beta/rc, risk communication

software rot, design pattern rot/grime, software evolution

rot = non-pattern related code

testing by community, bug fixing by community

== Modules ==

There's no inherit module functionality in PHP, but Yii has a module system. Libraries can be seen as a module system.

Examples of implicit modules in LimeSurvey:

* Front-end (survey taking)
* Back-end (survey design)
* Survey theme editing
* Expression manager
* Plugin system

In the future, they need to be separated and implemented more clearly as whatever Yii 3 module system is in use.

Some data models are common for all modules, e.g. surveys and users. Can have a "Common" module for such data.

todo, relation to Yii config system

== Classes ==

todo

* Avoid empty OOP ceremony, like defining getters and setters for all properties. Might as well make them public, ''unless'' they have invariants that need to be upheld, e.g. "this number is always between 1 and 10" or "this string is maximum length 20".
* Almost always avoid static methods. They cannot be mocked. One exception is (possibly) factory methods (Foo::make(...)).
* Inject all dependencies. This will make sure the class can be unit-tested (unit-tests have several benefits over integrity tests - they can be run in parallel and don't require any setup and teardown)
* A second way to achieve testability is to factor out the methods that access the dependencies

todo, state vs behaviour, state vs dependencies

=== OOP design ===

todo

Start from top-down, with domain, behaviour, interaction between objects, database design, pseudo-code if needed. Can also include scenarios, use-cases and UML diagrams.

Object reification - not only domain models, but also domain actions, relations and activities can be objects, e.g. a class ActivateSurvey or ExportSurvey.

Hierarchy depth.

Inheritance vs composition.

Multiple inheritance is done with traits. Use-case: ActiveRecords that support encryption, but not all.

=== Design pattern grime and software evolution ===

Design rot after time - how to keep it tight? (Grime.)

=== State ===

Keep a clear separation between classes with state and classes with no state.

todo, elaborate

=== Types of classes ===

Different categories of classes:

* Builders (e.g. query builder)
* Data-transfer object (no behaviour; pass to views to have better documentation and intent than associative arrays)
* Value classes (e.g. Email to wrap email string around)
* Command object (e.g. SurveyActivator)
* Helper (no state; e.g. QuestionAttributeHelper to bake attributes into different formats used by the views)
* Wrapper (also no state; e.g IOWrapper, to be able to mock file access)

todo, immutability, possible with private properties that are set in the constructor,

todo: command-query separation for classes?

=== Types of classes in LimeSurvey ===

* ActiveRecord, used to communicate with the database, and should not do ''anything'' else
* Controllers, used for glue code; should not contain business-logic
* Commands, same as controllers but from CLI
* Helper functions, should be short and obey command-query separation (TODO: Long functions should be separated into command objects or service classes); todo: should not have any dependencies?
* Helper classes, similar to helper functions but have dependencies that need to be mocked during tests; should not have any state
* Service classes, contains logic related to a clear and separate task, like create or import survey
* Question render classes, contains logic related to how questions are rendered (TODO: Need better separation between state and logic and more clear design); similar to widgets
* Plugin classes, using the plugin event system
* Widgets, containing HTML logic for custom HTML widgets
* Customizations to the Yii framework by inheritance
* Unit and functional test classes

A couple of classes contain only data, like LsDefaultDataSet.

todo, no difference between state property and dependency property in OOP

=== What is "glue code"? ===

todo

Putting the pieces together, e.g. service class A need data from model B, fetch it and run.

todo, add example

=== "Where do I cut?" ===

Separation of concerns, but which concerns and which type of separation?

=== Size ===

A class should have a single and clear purpose; compare with [https://en.wikipedia.org/wiki/SOLID SOLID].

=== Class name ===

* ActiveRecord classes are named after the database table they are bound to, but with singular instead of plural. E.g. table "lime_users" have model "User".
* Services classes are named after what they ''do'', e.g. SurveyCreator
* Helper classes should probably be named as specific as possible when possible, to avoid them from growing too big
* Follow the naming tradition of the framework with regard to controllers, e.g. UserController or UserAdministrationController.

== Functions ==

Functions are one of the fundamental building blocks of programming, so it's important to get it right.

Functions that are part of a class are called "methods", if you want to be formal.

Different types of functions in PHP:

* Functions (not attached to a class)
* Methods (attached to class)
* Anonymous functions (does not capture scope automatically)
* Short functions (does capture scope automatically)

I'm using "function" as a word for all types of functions in PHP below.

<hr>

=== Size ===

* A function should be short enough to be completely readable on one screen, approx 60 lines at most
* A function should not have too many arguments; if you have five or more, consider making it a class instead
* If a function is growing too big, it might be better to create a class instead or split it into several functions (if both functions have '''common state''', a class might be better, unless you want to pass around '''explicit state''')

=== Contract ===

* A function has a contract with its surrounding environment:
** Pre-condition: What needs to be true before the function is executed
** Post-condition: What will be true after the function has returned
* The function contract can be checked with assertions (internal invariants) or exceptions (outside world); see below
* Another good way is to use unit-tests to make sure the function's contract remains stable through changes
* The first line in the docblock should be one sentence describing the relation between function arguments and its output<br>Example<br><syntaxhighlight lang="php">
/**
* Creates a random password of length $length (defaults to 12)
* @param int $length
* @return string
*/
function createPassword($lenght = 12)

/**
* Creates an HTML language drop down for survey with id $surveyId, marking $selectedLanguage as selected
* @param int $surveyId
* @param string $selectedLanguage
* @return string <select> HTML
*/
function createLanguageDropdown($surveyId, $selectedLanguage)

</syntaxhighlight>

=== Push side-effects up in the stack trace ===

This one is a bit abstract.

First, what is a '''side-effect'''? In short, it's anything that happens in a function that ''is not'' described by the ''relation'' between function arguments and output.

Another way to phrase it is, that a side-effect is anything that is not always the same for the given input to a function; a function without any side-effects will always return the same result if it gets the same input.

'''Examples:'''

<syntaxhighlight lang="php">
// gT accesses the file system and will return different result depending on what's in the translation files
function gT($sToTranslate, $sEscapeMode = 'html', $sLanguage = null);

// If $sText and $sEscapeMode is always the same, quoteText() will always return the same string.
function quoteText($sText, $sEscapeMode = 'html');
</syntaxhighlight>

A function with no side-effects is called '''pure'''. A function that is guaranteed to always return (no exceptions, no errors, no warnings, no division by zero) is called '''total'''. Another name for purity is [https://en.wikipedia.org/wiki/Referential_transparency referential transparency].

It's a good thing if functions in a code-base ''either'' have side-effects, ''or'' return a result. Not both. This is called [https://en.wikipedia.org/wiki/Command%E2%80%93query_separation command-query separation].

Examples of side-effects:

* Database or file access
* Echo, or write to stdout or stderr
* Randomization

Why does this matter? Because side-effects make testing harder! '''If you have side-effects, you cannot create unit tests''', ''unless'' those side-effects can be mocked. If not, you need integrity tests with database setup or more. The more side-effects you have in a function, the more mocking is required to unit test it.

So, one solution to this is to move side-effects higher up in the stack trace, that is, move them to the calling code.

'''Example:'''

<syntaxhighlight lang="php">
function getSurveyInfo(int $surveyid, string $languagecode = '', boolean $force = false): array;
</syntaxhighlight>

Since this function takes $surveyid, we know it will probably query the database. Quering the database is a side-effect, and thus it requires a database scaffold for the test (or mocking, but the database connection is not injected, so there's no way to do it). One simple solution is to lift the side-effect out and pass in a Survey object instead:

<syntaxhighlight lang="php">
function getSurveyInfo(Survey $survey, string $languagecode = '', boolean $force = false): array;
</syntaxhighlight>

Much better! The side-effect of calling the database now happens ''before'' the function call. Now we can either mock a Survey object, or make an imitating stub for our test.

Reading the function body, there is in fact another database access, but since this is a relation to the Survey model, it could easily be moved out too. We've just made a function testable! Hooray!

This principle is rephrased in an architectural settings as [https://github.com/kbilsted/Functional-core-imperative-shell/blob/master/README.md functional core, imperative shell]. This architecture helps you get a good ratio between fast unit tests and slower integrity tests.

=== Function name ===

* The function name should tell you '''what''' it does; docs should tell you '''why''' (if this information is not obvious). '''How''' is described by the code itself (hopefully, but can in some cases be relevant to document).
* Function name can often be '''verb [+ adjective] + noun''', like "createFieldmap", "quoteText", "getRelativePath"
* Prefix with "is" for boolean functions

todo: difference between create, get, fetch, generate, ...

'''Good examples:'''

* gT() - An exception to descriptive function names; since this is used everywhere, the minimal name is motivated; maybe even name it "t()"?
* createPassword() - One verb, one noun - clear
* isCaptchaEnabled() - Using "is" signifies it returns boolean; clear purpose
* getFullResponseTable() - Verb, adjective, noun - but is "full" needed here? Is there a non-full version of the same function?
* replaceExpressionCodes() - Pretty good, but it's obvious that more information is needed in the docblock to describe what "replace" means, and what an "expression code" is
* fixCKeditorText() - "fix" is a bit vague, but maybe best there is? Pray that docblock contains information!

'''Bad examples:'''

* languageDropdown() - No verb, doesn't tell you what it does
* rmdirr() - Two r's, looks like a typo, but the last "r" actually means "recursive"!
* CSVUnquote() - Is CSV really the namespace? Why is the verb the second word?
* incompleteAnsFilterState() - One verb, but in the middle, or is "filter state" a noun?; why abbreviate "answer" to "ans"?
* reverseTranslateFieldNames() - Two verbs - did author mean "reverseTranslatedFieldNames"? Or "reverse and translate"? If so, it should be two functions, one for reverse and one for translate
* checkUploadedFileSizeAndRenderJson() - If you have an "and" in the function name, you should consider splitting it into two functions

<hr>

=== Function filename and namespace ===

If your function has dependencies, it should be put into a class instead, in which the dependencies can be injected. Another alternative is to put the dependencies as argument in the function, although this muffles the relationship between input and output. Again, this is to increase testability.

todo, autoloading of functions and folder location

=== Assertions ===

NB: This is not assertions as used in unit-tests, but assertions as used to check invariants in production code.

Assertions can be used for mental checks. They are only used for internal logic - failed assertions are not supposed to be seen by the end user. For interaction with the outside world, like database or browser, exceptions should be used instead.

Assertions can be disabled in production mode and have then no runtime cost.

'''Example:'''

<syntaxhighlight lang="php">
/**
* Translation helper function
*
* @param string $sToTranslate
* @param string $sEscapeMode Valid values are html (this is the default, js and unescaped)
* @param string $sLanguage
* @return string
*/
function gT($sToTranslate, $sEscapeMode = 'html', $sLanguage = null)
{
assert(is_string($sToTranslate));
assert(strlen($sToTranslate) > 0);
assert($sEscapeMode === 'html' || $sEscapeMode === 'js' || $sEscapeMode === 'unescaped');
return quoteText(Yii::t('', $sToTranslate, array(), null, $sLanguage), $sEscapeMode);
}
</syntaxhighlight>

<hr>

=== Exceptions ===

todo

todo: exception hierarchy

todo: what can be repaired after exception? transaction rollback

* Exceptions are used to check inputs from the outside world (browser, database, file system)
* Don't use exceptions for control flow, only when fatal errors happen that make further execution impossible
* Exceptions should have clear error messages that make them ''actionable'' - there should be a clear "next step" for the user or developer
* Never, ever, do an empty catch-block

==== Alternatives to exceptions ====

Some people consider exceptions being a hidden form of "goto" which confuses the control flow of the program. They propose different other solutions:

* Return a tuple, like <code>[$result, $errorMessage]</code> where $errorMessage is null at success
* Return <code>null</code> at failure
* Tagged union result type (not yet possible in latest PHP)
* Result object

The con being that you have to manually propagate the error, where an exception can happen from anywhere in the stack trace without any other function knowing about it.

=== If-statements ===

If-statements should not be too long or hard to understand. If they are, consider factor out the checks into separate functions.

<syntaxhighlight lang="php">
if ((empty($instance->oOptions->{$attribute}))
|| (
!empty($instance->oOptions->{$attribute})
&& (
$instance->oOptions->{$attribute} === 'inherit'
|| $instance->oOptions->{$attribute} === 'I'
// NB: Do NOT use === here, it won't work with Postgresql.
|| $instance->oOptions->{$attribute} == '-1'
)
)
) {
</syntaxhighlight>

Can be shortened by factoring out method <code>isInherit</code>:

<syntaxhighlight lang="php">
if (empty($instance->options->{$attribute})
|| $this->isInherit($instance-options->{$attribute})) {
}
/**
* Returns true if $value is set to inherit
* @param mixed|null $value
* @return boolean
*/
public function isInherit($value) {
return !empty($value)
&& (
$value === 'inherit'
|| $value === 'I'
// NB: Do NOT use === here, it won't work with Postgresql.
|| $value == '-1'
);
}
</syntaxhighlight>

And one more time by using a variable for the value:

<syntaxhighlight lang="php">
$value = $instance->options->{$attribute};
if (empty($value) || $this->isInherit($value)) {
}
</syntaxhighlight>

More clear, right? "If it's empty or set to inherit, do this and that."

=== Variables ===

Descriptive naming.

* Follow PSR-12 - no underscore, use camelCaseLikeThis
* Variables of ActiveRecord classes can have same name as the class, like "$survey" or "$question"
* Add -s for plural when it's an array: "$surveys", "$questions"
* Never include "array" or "list" in variable names - using plural is enough
* The ''context'' of the function helps with variable naming, e..g "$name" might be fine in a function about questions; this is extra helpful when functions are short!
* When a function is short, it's much easier to figure out variable meaning based on context
* $qid, $gid, and $sid are so established in the code-base that they could be considered OK
* The -data suffix means "blob of stuff", only use it when needed, like with $viewData
* Use $result when baking a return value; add its exact type as @var annotation (worst possible name, acceptable but anything with more meaning is better)

Not so good:

<syntaxhighlight lang="php">
$result = LabelSet::model()->findAll();
</syntaxhighlight>

Better with model name and -s for plural:

<syntaxhighlight lang="php">
$labelSets = LabelSet::model()->findAll();
</syntaxhighlight>

* Do not use Hungarian notation (prefix with "type"), but instead <code>/** @var */</code> annotations - these can be checked automatically and will then be enforced to be correct, unlike Hungarian notation which can "rot"

<syntaxhighlight lang="php">
/** string[] An array of strings with 0-n elements */
$allFields = [];
</syntaxhighlight>

Psalm can infer types if the function documentation is enough. The strictness can be adjusted. Not all variables will need @var annotation, the tool will warn you when it's confused.

* Data that is sent to views as associative arrays will be:

<syntaxhighlight lang="php">
/** @var array Can be basically anything :( Better would be data-transfer objects or more precise notation */
$data = [];
// Maybe more clear as $viewData? Discuss.
</syntaxhighlight>

You can be more precise when you specify which type of array you're writing:

<syntaxhighlight lang="php">
/** @var array<string, string> This means the array key is string, and the array value is also string */
$data = [];
$data['name'] = 'Olle';
$data['occupation'] = 'Developer';
$data['age'] = 38; // ERROR! Value must be string.
</syntaxhighlight>

For more info about array type notation, see the [https://psalm.dev/docs/annotating_code/type_syntax/array_types/ Psalm documentation].

Some smaller examples:

<syntaxhighlight lang="php">
$theme = App()->request->getPost('theme'); // Should be $themeType - $theme looks like a model/AR
$gridid === 'questionthemes-grid'; // Should be $gridId with capital "I", since it's two words in English
$delete = Yii::app()->request->getParam('delete'); // Tuff one - $delete is ok? Thoughts?
$files = json_decode(stripslashes($sJSON), true); // $file is a resource, $files an array of resources, this is $fileData perhaps?
$valid_extensions_array = explode(",", $aAttributes['allowed_filetypes']); // Should be $validExtensionTypes
$language = Yii::app()->session['survey_' . $surveyid]['s_lang']; // TODO: Should this be a value class? Then Language::make(...);
$surveyInfo = getSurveyInfo($surveyId, $language); // OK, BUT should be a separate DTO!
$fieldMap = createFieldMap($survey, 'short', false, false, $language); // Same, make a DTO
$cquestions = array(); // What's "c"? Method name is getChildQuestions and $questions is an argument - better with $childQuestions?
</syntaxhighlight>

=== Looping ===

* The bodies of foreach-loops are often a good candidate to factor out into separate functions.

'''Example:'''

<syntaxhighlight lang="php">
foreach ($questions as $question) {
processQuestion($question);
}
</syntaxhighlight>

Note the variable naming from plural to singular.

* Loop indexing should be named i, j, k etc.

'''Example:'''

<syntaxhighlight lang="php">
for ($i = 0; $i < $length; $i++) {
for ($j = 0; $j < $otherLength; $j++) {
// ...
}
}
</syntaxhighlight>

<hr>

=== Function composition ===

todo, "doThisAndThat" --> "doThis(doThat())"

=== Cases ===

<syntaxhighlight lang="php">
/**
* This function generates an array containing the fieldcode, and matching data in the same order as the activate script
*
* @param Survey $survey Survey ActiveRecord model
* @param string $style 'short' (default) or 'full' - full creates extra information like default values
* @param boolean $force_refresh - Forces to really refresh the array, not just take the session copy
* @param bool|int $questionid Limit to a certain qid only (for question preview) - default is false
* @param string $sLanguage The language to use
* @param array $aDuplicateQIDs
* @return array
*/
function createFieldMap($survey, $style = 'short', $force_refresh = false, $questionid = false, $sLanguage = '', &$aDuplicateQIDs = array())
</syntaxhighlight>

'''Good:'''

* Name is verb and noun
* Each argument is documented (almost)

'''Bad:'''

* Returns "array", which can be anything. A separate class for "Fieldmap" would be better.
* Not clear if it should be "createFieldMap" or "createFieldmap" - is "fieldmap" one word or two?
* Very many boolean arguments. Should probably be a class with methods like <code>$fieldmapCreator->setForceRefresh(true);</code> instead.
* Too long.
* Doesn't elaborate on what "fieldmap" really is, and does not link to any documentation about it.
* Access super-global, which makes it hard to test. Should instead return a data-transfer object, like:<br><syntaxhighlight lang="php">
$_SESSION['fieldmap'] = createFieldMap(...);
</syntaxhighlight>
* Has no test
* Mixes Hungarian notation with non-Hungarian notation in the argument list

== Defensive programming and error handling ==

todo

* '''Fail hard, fail early'''. The earlier the program crashes when something is wrong, the lower is the probability that you'll end up with corrupt data in the database that will later require manual labor to correct.
* Fail with '''actionable information'''
* Check input to functions and throw <code>InvalidArgumentException</code> if it violates the function's pre-conditions
* Use assert for class-internal invariants
* Use assert to make assumptions explicit for the reader

== Documentation ==

=== PHPDoc ===

* All functions must have a proper docblock
* The first line of the docblock should describe the relation between ''all'' the input arguments and the output of the function in a single sentence
* Each parameter must have the correct type
* Don't use <code>array</code> as type if it's a list of object - instead, use <code>[]</code> like so: <code>Survey[]</code> for a list of surveys

=== Technical documentation ===

todo, UML, scenarios, use-cases

== The PHP of yesterday ==

Old idioms and habits that should be abandoned.

* Don't use associative arrays, almost never. Data-transfer objects have multiple benefits: they are clearly structured, can be documented, can enforce invariants. There's ''no'' performance overhead of objects compared to arrays in modern PHP.
* Objects are already passed by reference; arrays are value types
* Use <code>[]</code> instead of <code>array()</code>
* Hungarian notation was useful before static analysis existed for PHP. These days it's better to use something that can be checked automatically: docblock @param and inline @var annotations.

== The PHP of tomorrow ==

todo

Union tags

Short functions

Match expressions

== Security ==

todo

XSS

Database injection

Permissions and roles

== Performance ==

todo

Loading too many rows into PHP models

== Testing ==

todo

QA

PHPUnit

TDD

Mocks, can't mock functions, static methods, mocking as a DSL, PHPUnit mocking tools

Pure functions, referential transparency, side-effects

Unit, functional, integration

Don't test the framework; don't test PHP

Makes sure the function or class lives up to its specification; make sure it will ''always'' live up to its specification, even in the future, to avoid regressions.

== Static analysis ==

<code>php -l</code>, CodeSniffer, Mess Detector, Psalm

== Database design ==

todo

== JavaScript ==

todo

classes, functions, components, tests

== CSS ==

todo

== HTML ==

todo

== Resources ==

todo

Books, links, videos

Code quality guide

2021-04-21T13:03:30Z

Olle: /* Class name */

DRAFT

== Prologue ==

# '''Be risk aware'''. Too good code can be a business risk (slow to write, maybe over-designed). Too sloppy code can also be a business risk (hard to maintain and understand). You have to find a balance that is adapted to the current situation and risk analysis, in which code quality becomes a '''risk mitigation''' technique among others.
# '''Be humble'''. LimeSurvey was made by developers from all over the world, with different age, education and experience. Your code might be read by a completely different team ten years from now, in the same way you are now reading code by developers that no longer work with us, but which work pays our rent.
# '''Performance matters sometimes''', and shouldn't be disregarded completely. In particular, database queries using the ORM and ActiveRecord can be problematic. Some surveys have thousands of questions and hundreds of thousands of responses. Fast response time is also important for a fluid user experience.
# '''It's harder to read code than to write code'''. Don't choose patterns that are easy or fast to write, but that are easy to read.
# Make your code '''communicate intent'''.
# It's easy to forget '''cross-cutting concerns''' like translation and security. Keep a mental note.
# '''Stress affects code quality''' and your risk behaviour. If your stress level is too high to write code with proper quality, take a step back and discuss it with your boss, or you'll push problems to the future.

== Quality ==

The purpose of this guide is to increase the quality of the LimeSurvey code-base. What is quality? Which aspects of quality can be measured? Which kind of company culture gives rise to appropriate code quality?

It's usually easier to get along what is "bad" code than what's "best" code. Blacklist instead of whitelist?

Quality attributes related to code quality:

* Readability
* Testability
* Maintainability
* Performance
* Security
* Reliability

Can not increase all at the same time - performance vs readability.

It's better to avoid emotional language when describing code quality, like "clean" or "dirty". Be precise, objective and suggest solutions.

Idiomatic code is more readable than non-idiomatic code. What's idiomatic depends on which context or domain you work in. We work in PHP and web application development, and have other idioms than in, say, functional or hardware-close programming.

Some code are "hot spots" - changed often. Those parts should require higher quality than other code.

== Risk ==

todo

data loss as most severe risk for LS

usability a business risk - hard to use or understand, people will choose another tool

risks relevant when fixing bugs

risks relevant when adding new features (lack of testing, wrong requirements, scope creep)

risks relevant when refactoring (regressions)

unit tests and QA as risk mitigation

partial deployment, alpha/beta/rc, risk communication

software rot, design pattern rot/grime, software evolution

rot = non-pattern related code

testing by community, bug fixing by community

== Modules ==

There's no inherit module functionality in PHP, but Yii has a module system. Libraries can be seen as a module system.

Examples of implicit modules in LimeSurvey:

* Front-end (survey taking)
* Back-end (survey design)
* Survey theme editing
* Expression manager
* Plugin system

In the future, they need to be separated and implemented more clearly as whatever Yii 3 module system is in use.

Some data models are common for all modules, e.g. surveys and users. Can have a "Common" module for such data.

todo, relation to Yii config system

== Classes ==

todo

* Avoid empty OOP ceremony, like defining getters and setters for all properties. Might as well make them public, ''unless'' they have invariants that need to be upheld, e.g. "this number is always between 1 and 10" or "this string is maximum length 20".
* Almost always avoid static methods. They cannot be mocked. One exception is (possibly) factory methods (Foo::make(...)).
* Inject all dependencies. This will make sure the class can be unit-tested (unit-tests have several benefits over integrity tests - they can be run in parallel and don't require any setup and teardown)
* A second way to achieve testability is to factor out the methods that access the dependencies

todo, state vs behaviour, state vs dependencies

=== OOP design ===

todo

Start from top-down, with domain, behaviour, interaction between objects, database design, pseudo-code if needed. Can also include scenarios, use-cases and UML diagrams.

Object reification - not only domain models, but also domain actions, relations and activities can be objects, e.g. a class ActivateSurvey or ExportSurvey.

Hierarchy depth.

Inheritance vs composition.

Multiple inheritance is done with traits. Use-case: ActiveRecords that support encryption, but not all.

=== Design pattern grime and software evolution ===

Design rot after time - how to keep it tight? (Grime.)

=== State ===

Keep a clear separation between classes with state and classes with no state.

todo, elaborate

=== Types of classes ===

Different categories of classes:

* Builders (e.g. query builder)
* Data-transfer object (no behaviour; pass to views to have better documentation and intent than associative arrays)
* Value classes (e.g. Email to wrap email string around)
* Command object (e.g. SurveyActivator)
* Helper (no state; e.g. QuestionAttributeHelper to bake attributes into different formats used by the views)
* Wrapper (also no state; e.g IOWrapper, to be able to mock file access)

todo, immutability, possible with private properties that are set in the constructor,

todo: command-query separation for classes?

=== Types of classes in LimeSurvey ===

* ActiveRecord, used to communicate with the database, and should not do ''anything'' else
* Controllers, used for glue code; should not contain business-logic
* Commands, same as controllers but from CLI
* Helper functions, should be short and obey command-query separation (TODO: Long functions should be separated into command objects or service classes); todo: should not have any dependencies?
* Helper classes, similar to helper functions but have dependencies that need to be mocked during tests; should not have any state
* Service classes, contains logic related to a clear and separate task, like create or import survey
* Question render classes, contains logic related to how questions are rendered (TODO: Need better separation between state and logic and more clear design); similar to widgets
* Plugin classes, using the plugin event system
* Widgets, containing HTML logic for custom HTML widgets
* Customizations to the Yii framework by inheritance
* Unit and functional test classes

A couple of classes contain only data, like LsDefaultDataSet.

todo, no difference between state property and dependency property in OOP

=== What is "glue code"? ===

todo

Putting the pieces together, e.g. service class A need data from model B, fetch it and run.

todo, add example

=== "Where do I cut?" ===

Separation of concerns, but which concerns and which type of separation?

=== Size ===

A class should have a single and clear purpose; compare with [https://en.wikipedia.org/wiki/SOLID SOLID].

=== Class name ===

* ActiveRecord classes are named after the database table they are bound to, but with singular instead of plural. E.g. table "lime_users" have model "User".
* Services classes are named after what they ''do'', e.g. SurveyCreator
* Helper classes should probably be named as specific as possible when possible, to avoid them from growing too big
* Follow the naming tradition of the framework with regard to controllers, e.g. UserController or UserAdministrationController.

== Functions ==

Functions are one of the fundamental building blocks of programming, so it's important to get it right.

Functions that are part of a class are called "methods", if you want to be formal.

Different types of functions in PHP:

* Functions (not attached to a class)
* Methods (attached to class)
* Anonymous functions (does not capture scope automatically)
* Short functions (does capture scope automatically)

I'm using "function" as a word for all types of functions in PHP below.

<hr>

=== Size ===

* A function should be short enough to be completely readable on one screen, approx 60 lines at most
* A function should not have too many arguments; if you have five or more, consider making it a class instead
* If a function is growing too big, it might be better to create a class instead or split it into several functions (if both functions have '''common state''', a class might be better, unless you want to pass around '''explicit state''')

=== Contract ===

* A function has a contract with its surrounding environment:
** Pre-condition: What needs to be true before the function is executed
** Post-condition: What will be true after the function has returned
* The function contract can be checked with assertions (internal invariants) or exceptions (outside world); see below
* Another good way is to use unit-tests to make sure the function's contract remains stable through changes
* The first line in the docblock should be one sentence describing the relation between function arguments and its output<br>Example<br><syntaxhighlight lang="php">
/**
* Creates a random password of length $length (defaults to 12)
* @param int $length
* @return string
*/
function createPassword($lenght = 12)

/**
* Creates an HTML language drop down for survey with id $surveyId, marking $selectedLanguage as selected
* @param int $surveyId
* @param string $selectedLanguage
* @return string <select> HTML
*/
function createLanguageDropdown($surveyId, $selectedLanguage)

</syntaxhighlight>

=== Push side-effects up in the stack trace ===

This one is a bit abstract.

First, what is a '''side-effect'''? In short, it's anything that happens in a function that ''is not'' described by the ''relation'' between function arguments and output.

Another way to phrase it is, that a side-effect is anything that is not always the same for the given input to a function; a function without any side-effects will always return the same result if it gets the same input.

'''Examples:'''

<syntaxhighlight lang="php">
// gT accesses the file system and will return different result depending on what's in the translation files
function gT($sToTranslate, $sEscapeMode = 'html', $sLanguage = null);

// If $sText and $sEscapeMode is always the same, quoteText() will always return the same string.
function quoteText($sText, $sEscapeMode = 'html');
</syntaxhighlight>

A function with no side-effects is called '''pure'''. A function that is guaranteed to always return (no exceptions, no errors, no warnings, no division by zero) is called '''total'''. Another name for purity is [https://en.wikipedia.org/wiki/Referential_transparency referential transparency].

It's a good thing if functions in a code-base ''either'' have side-effects, ''or'' return a result. Not both. This is called [https://en.wikipedia.org/wiki/Command%E2%80%93query_separation command-query separation].

Examples of side-effects:

* Database or file access
* Echo, or write to stdout or stderr
* Randomization

Why does this matter? Because side-effects make testing harder! '''If you have side-effects, you cannot create unit tests''', ''unless'' those side-effects can be mocked. If not, you need integrity tests with database setup or more. The more side-effects you have in a function, the more mocking is required to unit test it.

So, one solution to this is to move side-effects higher up in the stack trace, that is, move them to the calling code.

'''Example:'''

<syntaxhighlight lang="php">
function getSurveyInfo(int $surveyid, string $languagecode = '', boolean $force = false): array;
</syntaxhighlight>

Since this function takes $surveyid, we know it will probably query the database. Quering the database is a side-effect, and thus it requires a database scaffold for the test (or mocking, but the database connection is not injected, so there's no way to do it). One simple solution is to lift the side-effect out and pass in a Survey object instead:

<syntaxhighlight lang="php">
function getSurveyInfo(Survey $survey, string $languagecode = '', boolean $force = false): array;
</syntaxhighlight>

Much better! The side-effect of calling the database now happens ''before'' the function call. Now we can either mock a Survey object, or make an imitating stub for our test.

Reading the function body, there is in fact another database access, but since this is a relation to the Survey model, it could easily be moved out too. We've just made a function testable! Hooray!

This principle is rephrased in an architectural settings as [https://github.com/kbilsted/Functional-core-imperative-shell/blob/master/README.md functional core, imperative shell]. This architecture helps you get a good ratio between fast unit tests and slower integrity tests.

=== Function name ===

* The function name should tell you '''what''' it does; docs should tell you '''why''' (if this information is not obvious). '''How''' is described by the code itself (hopefully, but can in some cases be relevant to document).
* Function name can often be '''verb [+ adjective] + noun''', like "createFieldmap", "quoteText", "getRelativePath"
* Prefix with "is" for boolean functions

todo: difference between create, get, fetch, generate, ...

'''Good examples:'''

* gT() - An exception to descriptive function names; since this is used everywhere, the minimal name is motivated; maybe even name it "t()"?
* createPassword() - One verb, one noun - clear
* isCaptchaEnabled() - Using "is" signifies it returns boolean; clear purpose
* getFullResponseTable() - Verb, adjective, noun - but is "full" needed here? Is there a non-full version of the same function?
* replaceExpressionCodes() - Pretty good, but it's obvious that more information is needed in the docblock to describe what "replace" means, and what an "expression code" is
* fixCKeditorText() - "fix" is a bit vague, but maybe best there is? Pray that docblock contains information!

'''Bad examples:'''

* languageDropdown() - No verb, doesn't tell you what it does
* rmdirr() - Two r's, looks like a typo, but the last "r" actually means "recursive"!
* CSVUnquote() - Is CSV really the namespace? Why is the verb the second word?
* incompleteAnsFilterState() - One verb, but in the middle, or is "filter state" a noun?; why abbreviate "answer" to "ans"?
* reverseTranslateFieldNames() - Two verbs - did author mean "reverseTranslatedFieldNames"? Or "reverse and translate"? If so, it should be two functions, one for reverse and one for translate
* checkUploadedFileSizeAndRenderJson() - If you have an "and" in the function name, you should consider splitting it into two functions

<hr>

=== Assertions ===

NB: This is not assertions as used in unit-tests, but assertions as used to check invariants in production code.

Assertions can be used for mental checks. They are only used for internal logic - failed assertions are not supposed to be seen by the end user. For interaction with the outside world, like database or browser, exceptions should be used instead.

Assertions can be disabled in production mode and have then no runtime cost.

'''Example:'''

<syntaxhighlight lang="php">
/**
* Translation helper function
*
* @param string $sToTranslate
* @param string $sEscapeMode Valid values are html (this is the default, js and unescaped)
* @param string $sLanguage
* @return string
*/
function gT($sToTranslate, $sEscapeMode = 'html', $sLanguage = null)
{
assert(is_string($sToTranslate));
assert(strlen($sToTranslate) > 0);
assert($sEscapeMode === 'html' || $sEscapeMode === 'js' || $sEscapeMode === 'unescaped');
return quoteText(Yii::t('', $sToTranslate, array(), null, $sLanguage), $sEscapeMode);
}
</syntaxhighlight>

<hr>

=== Exceptions ===

todo

todo: exception hierarchy

todo: what can be repaired after exception? transaction rollback

* Exceptions are used to check inputs from the outside world (browser, database, file system)
* Don't use exceptions for control flow, only when fatal errors happen that make further execution impossible
* Exceptions should have clear error messages that make them ''actionable'' - there should be a clear "next step" for the user or developer
* Never, ever, do an empty catch-block

==== Alternatives to exceptions ====

Some people consider exceptions being a hidden form of "goto" which confuses the control flow of the program. They propose different other solutions:

* Return a tuple, like <code>[$result, $errorMessage]</code> where $errorMessage is null at success
* Return <code>null</code> at failure
* Tagged union result type (not yet possible in latest PHP)
* Result object

The con being that you have to manually propagate the error, where an exception can happen from anywhere in the stack trace without any other function knowing about it.

=== If-statements ===

If-statements should not be too long or hard to understand. If they are, consider factor out the checks into separate functions.

<syntaxhighlight lang="php">
if ((empty($instance->oOptions->{$attribute}))
|| (
!empty($instance->oOptions->{$attribute})
&& (
$instance->oOptions->{$attribute} === 'inherit'
|| $instance->oOptions->{$attribute} === 'I'
// NB: Do NOT use === here, it won't work with Postgresql.
|| $instance->oOptions->{$attribute} == '-1'
)
)
) {
</syntaxhighlight>

Can be shortened by factoring out method <code>isInherit</code>:

<syntaxhighlight lang="php">
if (empty($instance->options->{$attribute})
|| $this->isInherit($instance-options->{$attribute})) {
}
/**
* Returns true if $value is set to inherit
* @param mixed|null $value
* @return boolean
*/
public function isInherit($value) {
return !empty($value)
&& (
$value === 'inherit'
|| $value === 'I'
// NB: Do NOT use === here, it won't work with Postgresql.
|| $value == '-1'
);
}
</syntaxhighlight>

And one more time by using a variable for the value:

<syntaxhighlight lang="php">
$value = $instance->options->{$attribute};
if (empty($value) || $this->isInherit($value)) {
}
</syntaxhighlight>

More clear, right? "If it's empty or set to inherit, do this and that."

=== Variables ===

Descriptive naming.

* Follow PSR-12 - no underscore, use camelCaseLikeThis
* Variables of ActiveRecord classes can have same name as the class, like "$survey" or "$question"
* Add -s for plural when it's an array: "$surveys", "$questions"
* Never include "array" or "list" in variable names - using plural is enough
* The ''context'' of the function helps with variable naming, e..g "$name" might be fine in a function about questions; this is extra helpful when functions are short!
* When a function is short, it's much easier to figure out variable meaning based on context
* $qid, $gid, and $sid are so established in the code-base that they could be considered OK
* The -data suffix means "blob of stuff", only use it when needed, like with $viewData
* Use $result when baking a return value; add its exact type as @var annotation (worst possible name, acceptable but anything with more meaning is better)

Not so good:

<syntaxhighlight lang="php">
$result = LabelSet::model()->findAll();
</syntaxhighlight>

Better with model name and -s for plural:

<syntaxhighlight lang="php">
$labelSets = LabelSet::model()->findAll();
</syntaxhighlight>

* Do not use Hungarian notation (prefix with "type"), but instead <code>/** @var */</code> annotations - these can be checked automatically and will then be enforced to be correct, unlike Hungarian notation which can "rot"

<syntaxhighlight lang="php">
/** string[] An array of strings with 0-n elements */
$allFields = [];
</syntaxhighlight>

Psalm can infer types if the function documentation is enough. The strictness can be adjusted. Not all variables will need @var annotation, the tool will warn you when it's confused.

* Data that is sent to views as associative arrays will be:

<syntaxhighlight lang="php">
/** @var array Can be basically anything :( Better would be data-transfer objects or more precise notation */
$data = [];
// Maybe more clear as $viewData? Discuss.
</syntaxhighlight>

You can be more precise when you specify which type of array you're writing:

<syntaxhighlight lang="php">
/** @var array<string, string> This means the array key is string, and the array value is also string */
$data = [];
$data['name'] = 'Olle';
$data['occupation'] = 'Developer';
$data['age'] = 38; // ERROR! Value must be string.
</syntaxhighlight>

For more info about array type notation, see the [https://psalm.dev/docs/annotating_code/type_syntax/array_types/ Psalm documentation].

Some smaller examples:

<syntaxhighlight lang="php">
$theme = App()->request->getPost('theme'); // Should be $themeType - $theme looks like a model/AR
$gridid === 'questionthemes-grid'; // Should be $gridId with capital "I", since it's two words in English
$delete = Yii::app()->request->getParam('delete'); // Tuff one - $delete is ok? Thoughts?
$files = json_decode(stripslashes($sJSON), true); // $file is a resource, $files an array of resources, this is $fileData perhaps?
$valid_extensions_array = explode(",", $aAttributes['allowed_filetypes']); // Should be $validExtensionTypes
$language = Yii::app()->session['survey_' . $surveyid]['s_lang']; // TODO: Should this be a value class? Then Language::make(...);
$surveyInfo = getSurveyInfo($surveyId, $language); // OK, BUT should be a separate DTO!
$fieldMap = createFieldMap($survey, 'short', false, false, $language); // Same, make a DTO
$cquestions = array(); // What's "c"? Method name is getChildQuestions and $questions is an argument - better with $childQuestions?
</syntaxhighlight>

=== Looping ===

* The bodies of foreach-loops are often a good candidate to factor out into separate functions.

'''Example:'''

<syntaxhighlight lang="php">
foreach ($questions as $question) {
processQuestion($question);
}
</syntaxhighlight>

Note the variable naming from plural to singular.

* Loop indexing should be named i, j, k etc.

'''Example:'''

<syntaxhighlight lang="php">
for ($i = 0; $i < $length; $i++) {
for ($j = 0; $j < $otherLength; $j++) {
// ...
}
}
</syntaxhighlight>

<hr>

=== Function composition ===

todo, "doThisAndThat" --> "doThis(doThat())"

=== Cases ===

<syntaxhighlight lang="php">
/**
* This function generates an array containing the fieldcode, and matching data in the same order as the activate script
*
* @param Survey $survey Survey ActiveRecord model
* @param string $style 'short' (default) or 'full' - full creates extra information like default values
* @param boolean $force_refresh - Forces to really refresh the array, not just take the session copy
* @param bool|int $questionid Limit to a certain qid only (for question preview) - default is false
* @param string $sLanguage The language to use
* @param array $aDuplicateQIDs
* @return array
*/
function createFieldMap($survey, $style = 'short', $force_refresh = false, $questionid = false, $sLanguage = '', &$aDuplicateQIDs = array())
</syntaxhighlight>

'''Good:'''

* Name is verb and noun
* Each argument is documented (almost)

'''Bad:'''

* Returns "array", which can be anything. A separate class for "Fieldmap" would be better.
* Not clear if it should be "createFieldMap" or "createFieldmap" - is "fieldmap" one word or two?
* Very many boolean arguments. Should probably be a class with methods like <code>$fieldmapCreator->setForceRefresh(true);</code> instead.
* Too long.
* Doesn't elaborate on what "fieldmap" really is, and does not link to any documentation about it.
* Access super-global, which makes it hard to test. Should instead return a data-transfer object, like:<br><syntaxhighlight lang="php">
$_SESSION['fieldmap'] = createFieldMap(...);
</syntaxhighlight>
* Has no test
* Mixes Hungarian notation with non-Hungarian notation in the argument list

== Defensive programming and error handling ==

todo

* '''Fail hard, fail early'''. The earlier the program crashes when something is wrong, the lower is the probability that you'll end up with corrupt data in the database that will later require manual labor to correct.
* Fail with '''actionable information'''
* Check input to functions and throw <code>InvalidArgumentException</code> if it violates the function's pre-conditions
* Use assert for class-internal invariants
* Use assert to make assumptions explicit for the reader

== Documentation ==

=== PHPDoc ===

* All functions must have a proper docblock
* The first line of the docblock should describe the relation between ''all'' the input arguments and the output of the function in a single sentence
* Each parameter must have the correct type
* Don't use <code>array</code> as type if it's a list of object - instead, use <code>[]</code> like so: <code>Survey[]</code> for a list of surveys

=== Technical documentation ===

todo, UML, scenarios, use-cases

== The PHP of yesterday ==

Old idioms and habits that should be abandoned.

* Don't use associative arrays, almost never. Data-transfer objects have multiple benefits: they are clearly structured, can be documented, can enforce invariants. There's ''no'' performance overhead of objects compared to arrays in modern PHP.
* Objects are already passed by reference; arrays are value types
* Use <code>[]</code> instead of <code>array()</code>
* Hungarian notation was useful before static analysis existed for PHP. These days it's better to use something that can be checked automatically: docblock @param and inline @var annotations.

== The PHP of tomorrow ==

todo

Union tags

Short functions

Match expressions

== Security ==

todo

XSS

Database injection

Permissions and roles

== Performance ==

todo

Loading too many rows into PHP models

== Testing ==

todo

QA

PHPUnit

TDD

Mocks, can't mock functions, static methods, mocking as a DSL, PHPUnit mocking tools

Pure functions, referential transparency, side-effects

Unit, functional, integration

Don't test the framework; don't test PHP

Makes sure the function or class lives up to its specification; make sure it will ''always'' live up to its specification, even in the future, to avoid regressions.

== Static analysis ==

<code>php -l</code>, CodeSniffer, Mess Detector, Psalm

== Database design ==

todo

== JavaScript ==

todo

classes, functions, components, tests

== CSS ==

todo

== HTML ==

todo

== Resources ==

todo

Books, links, videos

Code quality guide

2021-04-21T12:51:42Z

Olle: /* "Where do I cut?" */

DRAFT

== Prologue ==

# '''Be risk aware'''. Too good code can be a business risk (slow to write, maybe over-designed). Too sloppy code can also be a business risk (hard to maintain and understand). You have to find a balance that is adapted to the current situation and risk analysis, in which code quality becomes a '''risk mitigation''' technique among others.
# '''Be humble'''. LimeSurvey was made by developers from all over the world, with different age, education and experience. Your code might be read by a completely different team ten years from now, in the same way you are now reading code by developers that no longer work with us, but which work pays our rent.
# '''Performance matters sometimes''', and shouldn't be disregarded completely. In particular, database queries using the ORM and ActiveRecord can be problematic. Some surveys have thousands of questions and hundreds of thousands of responses. Fast response time is also important for a fluid user experience.
# '''It's harder to read code than to write code'''. Don't choose patterns that are easy or fast to write, but that are easy to read.
# Make your code '''communicate intent'''.
# It's easy to forget '''cross-cutting concerns''' like translation and security. Keep a mental note.
# '''Stress affects code quality''' and your risk behaviour. If your stress level is too high to write code with proper quality, take a step back and discuss it with your boss, or you'll push problems to the future.

== Quality ==

The purpose of this guide is to increase the quality of the LimeSurvey code-base. What is quality? Which aspects of quality can be measured? Which kind of company culture gives rise to appropriate code quality?

It's usually easier to get along what is "bad" code than what's "best" code. Blacklist instead of whitelist?

Quality attributes related to code quality:

* Readability
* Testability
* Maintainability
* Performance
* Security
* Reliability

Can not increase all at the same time - performance vs readability.

It's better to avoid emotional language when describing code quality, like "clean" or "dirty". Be precise, objective and suggest solutions.

Idiomatic code is more readable than non-idiomatic code. What's idiomatic depends on which context or domain you work in. We work in PHP and web application development, and have other idioms than in, say, functional or hardware-close programming.

Some code are "hot spots" - changed often. Those parts should require higher quality than other code.

== Risk ==

todo

data loss as most severe risk for LS

usability a business risk - hard to use or understand, people will choose another tool

risks relevant when fixing bugs

risks relevant when adding new features (lack of testing, wrong requirements, scope creep)

risks relevant when refactoring (regressions)

unit tests and QA as risk mitigation

partial deployment, alpha/beta/rc, risk communication

software rot, design pattern rot/grime, software evolution

rot = non-pattern related code

testing by community, bug fixing by community

== Modules ==

There's no inherit module functionality in PHP, but Yii has a module system. Libraries can be seen as a module system.

Examples of implicit modules in LimeSurvey:

* Front-end (survey taking)
* Back-end (survey design)
* Survey theme editing
* Expression manager
* Plugin system

In the future, they need to be separated and implemented more clearly as whatever Yii 3 module system is in use.

Some data models are common for all modules, e.g. surveys and users. Can have a "Common" module for such data.

todo, relation to Yii config system

== Classes ==

todo

* Avoid empty OOP ceremony, like defining getters and setters for all properties. Might as well make them public, ''unless'' they have invariants that need to be upheld, e.g. "this number is always between 1 and 10" or "this string is maximum length 20".
* Almost always avoid static methods. They cannot be mocked. One exception is (possibly) factory methods (Foo::make(...)).
* Inject all dependencies. This will make sure the class can be unit-tested (unit-tests have several benefits over integrity tests - they can be run in parallel and don't require any setup and teardown)
* A second way to achieve testability is to factor out the methods that access the dependencies

todo, state vs behaviour, state vs dependencies

=== OOP design ===

todo

Start from top-down, with domain, behaviour, interaction between objects, database design, pseudo-code if needed. Can also include scenarios, use-cases and UML diagrams.

Object reification - not only domain models, but also domain actions, relations and activities can be objects, e.g. a class ActivateSurvey or ExportSurvey.

Hierarchy depth.

Inheritance vs composition.

Multiple inheritance is done with traits. Use-case: ActiveRecords that support encryption, but not all.

=== Design pattern grime and software evolution ===

Design rot after time - how to keep it tight? (Grime.)

=== State ===

Keep a clear separation between classes with state and classes with no state.

todo, elaborate

=== Types of classes ===

Different categories of classes:

* Builders (e.g. query builder)
* Data-transfer object (no behaviour; pass to views to have better documentation and intent than associative arrays)
* Value classes (e.g. Email to wrap email string around)
* Command object (e.g. SurveyActivator)
* Helper (no state; e.g. QuestionAttributeHelper to bake attributes into different formats used by the views)
* Wrapper (also no state; e.g IOWrapper, to be able to mock file access)

todo, immutability, possible with private properties that are set in the constructor,

todo: command-query separation for classes?

=== Types of classes in LimeSurvey ===

* ActiveRecord, used to communicate with the database, and should not do ''anything'' else
* Controllers, used for glue code; should not contain business-logic
* Commands, same as controllers but from CLI
* Helper functions, should be short and obey command-query separation (TODO: Long functions should be separated into command objects or service classes); todo: should not have any dependencies?
* Helper classes, similar to helper functions but have dependencies that need to be mocked during tests; should not have any state
* Service classes, contains logic related to a clear and separate task, like create or import survey
* Question render classes, contains logic related to how questions are rendered (TODO: Need better separation between state and logic and more clear design); similar to widgets
* Plugin classes, using the plugin event system
* Widgets, containing HTML logic for custom HTML widgets
* Customizations to the Yii framework by inheritance
* Unit and functional test classes

A couple of classes contain only data, like LsDefaultDataSet.

todo, no difference between state property and dependency property in OOP

=== What is "glue code"? ===

todo

Putting the pieces together, e.g. service class A need data from model B, fetch it and run.

todo, add example

=== "Where do I cut?" ===

Separation of concerns, but which concerns and which type of separation?

=== Size ===

A class should have a single and clear purpose; compare with [https://en.wikipedia.org/wiki/SOLID SOLID].

=== Class name ===

* ActiveRecord classes are named after the database table they are bound to, but with singular instead of plural. E.g. table "users" have model "User".
* Services classes are named after what they ''do'', e.g. SurveyCreator
* Helper classes should probably be named as specific as possible when possible, to avoid them from growing too big
* Follow the naming tradition of the framework with regard to controllers, e.g. UserController or UserAdministrationController.

== Functions ==

Functions are one of the fundamental building blocks of programming, so it's important to get it right.

Functions that are part of a class are called "methods", if you want to be formal.

Different types of functions in PHP:

* Functions (not attached to a class)
* Methods (attached to class)
* Anonymous functions (does not capture scope automatically)
* Short functions (does capture scope automatically)

I'm using "function" as a word for all types of functions in PHP below.

<hr>

=== Size ===

* A function should be short enough to be completely readable on one screen, approx 60 lines at most
* A function should not have too many arguments; if you have five or more, consider making it a class instead
* If a function is growing too big, it might be better to create a class instead or split it into several functions (if both functions have '''common state''', a class might be better, unless you want to pass around '''explicit state''')

=== Contract ===

* A function has a contract with its surrounding environment:
** Pre-condition: What needs to be true before the function is executed
** Post-condition: What will be true after the function has returned
* The function contract can be checked with assertions (internal invariants) or exceptions (outside world); see below
* Another good way is to use unit-tests to make sure the function's contract remains stable through changes
* The first line in the docblock should be one sentence describing the relation between function arguments and its output<br>Example<br><syntaxhighlight lang="php">
/**
* Creates a random password of length $length (defaults to 12)
* @param int $length
* @return string
*/
function createPassword($lenght = 12)

/**
* Creates an HTML language drop down for survey with id $surveyId, marking $selectedLanguage as selected
* @param int $surveyId
* @param string $selectedLanguage
* @return string <select> HTML
*/
function createLanguageDropdown($surveyId, $selectedLanguage)

</syntaxhighlight>

=== Push side-effects up in the stack trace ===

This one is a bit abstract.

First, what is a '''side-effect'''? In short, it's anything that happens in a function that ''is not'' described by the ''relation'' between function arguments and output.

Another way to phrase it is, that a side-effect is anything that is not always the same for the given input to a function; a function without any side-effects will always return the same result if it gets the same input.

'''Examples:'''

<syntaxhighlight lang="php">
// gT accesses the file system and will return different result depending on what's in the translation files
function gT($sToTranslate, $sEscapeMode = 'html', $sLanguage = null);

// If $sText and $sEscapeMode is always the same, quoteText() will always return the same string.
function quoteText($sText, $sEscapeMode = 'html');
</syntaxhighlight>

A function with no side-effects is called '''pure'''. A function that is guaranteed to always return (no exceptions, no errors, no warnings, no division by zero) is called '''total'''. Another name for purity is [https://en.wikipedia.org/wiki/Referential_transparency referential transparency].

It's a good thing if functions in a code-base ''either'' have side-effects, ''or'' return a result. Not both. This is called [https://en.wikipedia.org/wiki/Command%E2%80%93query_separation command-query separation].

Examples of side-effects:

* Database or file access
* Echo, or write to stdout or stderr
* Randomization

Why does this matter? Because side-effects make testing harder! '''If you have side-effects, you cannot create unit tests''', ''unless'' those side-effects can be mocked. If not, you need integrity tests with database setup or more. The more side-effects you have in a function, the more mocking is required to unit test it.

So, one solution to this is to move side-effects higher up in the stack trace, that is, move them to the calling code.

'''Example:'''

<syntaxhighlight lang="php">
function getSurveyInfo(int $surveyid, string $languagecode = '', boolean $force = false): array;
</syntaxhighlight>

Since this function takes $surveyid, we know it will probably query the database. Quering the database is a side-effect, and thus it requires a database scaffold for the test (or mocking, but the database connection is not injected, so there's no way to do it). One simple solution is to lift the side-effect out and pass in a Survey object instead:

<syntaxhighlight lang="php">
function getSurveyInfo(Survey $survey, string $languagecode = '', boolean $force = false): array;
</syntaxhighlight>

Much better! The side-effect of calling the database now happens ''before'' the function call. Now we can either mock a Survey object, or make an imitating stub for our test.

Reading the function body, there is in fact another database access, but since this is a relation to the Survey model, it could easily be moved out too. We've just made a function testable! Hooray!

This principle is rephrased in an architectural settings as [https://github.com/kbilsted/Functional-core-imperative-shell/blob/master/README.md functional core, imperative shell]. This architecture helps you get a good ratio between fast unit tests and slower integrity tests.

=== Function name ===

* The function name should tell you '''what''' it does; docs should tell you '''why''' (if this information is not obvious). '''How''' is described by the code itself (hopefully, but can in some cases be relevant to document).
* Function name can often be '''verb [+ adjective] + noun''', like "createFieldmap", "quoteText", "getRelativePath"
* Prefix with "is" for boolean functions

todo: difference between create, get, fetch, generate, ...

'''Good examples:'''

* gT() - An exception to descriptive function names; since this is used everywhere, the minimal name is motivated; maybe even name it "t()"?
* createPassword() - One verb, one noun - clear
* isCaptchaEnabled() - Using "is" signifies it returns boolean; clear purpose
* getFullResponseTable() - Verb, adjective, noun - but is "full" needed here? Is there a non-full version of the same function?
* replaceExpressionCodes() - Pretty good, but it's obvious that more information is needed in the docblock to describe what "replace" means, and what an "expression code" is
* fixCKeditorText() - "fix" is a bit vague, but maybe best there is? Pray that docblock contains information!

'''Bad examples:'''

* languageDropdown() - No verb, doesn't tell you what it does
* rmdirr() - Two r's, looks like a typo, but the last "r" actually means "recursive"!
* CSVUnquote() - Is CSV really the namespace? Why is the verb the second word?
* incompleteAnsFilterState() - One verb, but in the middle, or is "filter state" a noun?; why abbreviate "answer" to "ans"?
* reverseTranslateFieldNames() - Two verbs - did author mean "reverseTranslatedFieldNames"? Or "reverse and translate"? If so, it should be two functions, one for reverse and one for translate
* checkUploadedFileSizeAndRenderJson() - If you have an "and" in the function name, you should consider splitting it into two functions

<hr>

=== Assertions ===

NB: This is not assertions as used in unit-tests, but assertions as used to check invariants in production code.

Assertions can be used for mental checks. They are only used for internal logic - failed assertions are not supposed to be seen by the end user. For interaction with the outside world, like database or browser, exceptions should be used instead.

Assertions can be disabled in production mode and have then no runtime cost.

'''Example:'''

<syntaxhighlight lang="php">
/**
* Translation helper function
*
* @param string $sToTranslate
* @param string $sEscapeMode Valid values are html (this is the default, js and unescaped)
* @param string $sLanguage
* @return string
*/
function gT($sToTranslate, $sEscapeMode = 'html', $sLanguage = null)
{
assert(is_string($sToTranslate));
assert(strlen($sToTranslate) > 0);
assert($sEscapeMode === 'html' || $sEscapeMode === 'js' || $sEscapeMode === 'unescaped');
return quoteText(Yii::t('', $sToTranslate, array(), null, $sLanguage), $sEscapeMode);
}
</syntaxhighlight>

<hr>

=== Exceptions ===

todo

todo: exception hierarchy

todo: what can be repaired after exception? transaction rollback

* Exceptions are used to check inputs from the outside world (browser, database, file system)
* Don't use exceptions for control flow, only when fatal errors happen that make further execution impossible
* Exceptions should have clear error messages that make them ''actionable'' - there should be a clear "next step" for the user or developer
* Never, ever, do an empty catch-block

==== Alternatives to exceptions ====

Some people consider exceptions being a hidden form of "goto" which confuses the control flow of the program. They propose different other solutions:

* Return a tuple, like <code>[$result, $errorMessage]</code> where $errorMessage is null at success
* Return <code>null</code> at failure
* Tagged union result type (not yet possible in latest PHP)
* Result object

The con being that you have to manually propagate the error, where an exception can happen from anywhere in the stack trace without any other function knowing about it.

=== If-statements ===

If-statements should not be too long or hard to understand. If they are, consider factor out the checks into separate functions.

<syntaxhighlight lang="php">
if ((empty($instance->oOptions->{$attribute}))
|| (
!empty($instance->oOptions->{$attribute})
&& (
$instance->oOptions->{$attribute} === 'inherit'
|| $instance->oOptions->{$attribute} === 'I'
// NB: Do NOT use === here, it won't work with Postgresql.
|| $instance->oOptions->{$attribute} == '-1'
)
)
) {
</syntaxhighlight>

Can be shortened by factoring out method <code>isInherit</code>:

<syntaxhighlight lang="php">
if (empty($instance->options->{$attribute})
|| $this->isInherit($instance-options->{$attribute})) {
}
/**
* Returns true if $value is set to inherit
* @param mixed|null $value
* @return boolean
*/
public function isInherit($value) {
return !empty($value)
&& (
$value === 'inherit'
|| $value === 'I'
// NB: Do NOT use === here, it won't work with Postgresql.
|| $value == '-1'
);
}
</syntaxhighlight>

And one more time by using a variable for the value:

<syntaxhighlight lang="php">
$value = $instance->options->{$attribute};
if (empty($value) || $this->isInherit($value)) {
}
</syntaxhighlight>

More clear, right? "If it's empty or set to inherit, do this and that."

=== Variables ===

Descriptive naming.

* Follow PSR-12 - no underscore, use camelCaseLikeThis
* Variables of ActiveRecord classes can have same name as the class, like "$survey" or "$question"
* Add -s for plural when it's an array: "$surveys", "$questions"
* Never include "array" or "list" in variable names - using plural is enough
* The ''context'' of the function helps with variable naming, e..g "$name" might be fine in a function about questions; this is extra helpful when functions are short!
* When a function is short, it's much easier to figure out variable meaning based on context
* $qid, $gid, and $sid are so established in the code-base that they could be considered OK
* The -data suffix means "blob of stuff", only use it when needed, like with $viewData
* Use $result when baking a return value; add its exact type as @var annotation (worst possible name, acceptable but anything with more meaning is better)

Not so good:

<syntaxhighlight lang="php">
$result = LabelSet::model()->findAll();
</syntaxhighlight>

Better with model name and -s for plural:

<syntaxhighlight lang="php">
$labelSets = LabelSet::model()->findAll();
</syntaxhighlight>

* Do not use Hungarian notation (prefix with "type"), but instead <code>/** @var */</code> annotations - these can be checked automatically and will then be enforced to be correct, unlike Hungarian notation which can "rot"

<syntaxhighlight lang="php">
/** string[] An array of strings with 0-n elements */
$allFields = [];
</syntaxhighlight>

Psalm can infer types if the function documentation is enough. The strictness can be adjusted. Not all variables will need @var annotation, the tool will warn you when it's confused.

* Data that is sent to views as associative arrays will be:

<syntaxhighlight lang="php">
/** @var array Can be basically anything :( Better would be data-transfer objects or more precise notation */
$data = [];
// Maybe more clear as $viewData? Discuss.
</syntaxhighlight>

You can be more precise when you specify which type of array you're writing:

<syntaxhighlight lang="php">
/** @var array<string, string> This means the array key is string, and the array value is also string */
$data = [];
$data['name'] = 'Olle';
$data['occupation'] = 'Developer';
$data['age'] = 38; // ERROR! Value must be string.
</syntaxhighlight>

For more info about array type notation, see the [https://psalm.dev/docs/annotating_code/type_syntax/array_types/ Psalm documentation].

Some smaller examples:

<syntaxhighlight lang="php">
$theme = App()->request->getPost('theme'); // Should be $themeType - $theme looks like a model/AR
$gridid === 'questionthemes-grid'; // Should be $gridId with capital "I", since it's two words in English
$delete = Yii::app()->request->getParam('delete'); // Tuff one - $delete is ok? Thoughts?
$files = json_decode(stripslashes($sJSON), true); // $file is a resource, $files an array of resources, this is $fileData perhaps?
$valid_extensions_array = explode(",", $aAttributes['allowed_filetypes']); // Should be $validExtensionTypes
$language = Yii::app()->session['survey_' . $surveyid]['s_lang']; // TODO: Should this be a value class? Then Language::make(...);
$surveyInfo = getSurveyInfo($surveyId, $language); // OK, BUT should be a separate DTO!
$fieldMap = createFieldMap($survey, 'short', false, false, $language); // Same, make a DTO
$cquestions = array(); // What's "c"? Method name is getChildQuestions and $questions is an argument - better with $childQuestions?
</syntaxhighlight>

=== Looping ===

* The bodies of foreach-loops are often a good candidate to factor out into separate functions.

'''Example:'''

<syntaxhighlight lang="php">
foreach ($questions as $question) {
processQuestion($question);
}
</syntaxhighlight>

Note the variable naming from plural to singular.

* Loop indexing should be named i, j, k etc.

'''Example:'''

<syntaxhighlight lang="php">
for ($i = 0; $i < $length; $i++) {
for ($j = 0; $j < $otherLength; $j++) {
// ...
}
}
</syntaxhighlight>

<hr>

=== Function composition ===

todo, "doThisAndThat" --> "doThis(doThat())"

=== Cases ===

<syntaxhighlight lang="php">
/**
* This function generates an array containing the fieldcode, and matching data in the same order as the activate script
*
* @param Survey $survey Survey ActiveRecord model
* @param string $style 'short' (default) or 'full' - full creates extra information like default values
* @param boolean $force_refresh - Forces to really refresh the array, not just take the session copy
* @param bool|int $questionid Limit to a certain qid only (for question preview) - default is false
* @param string $sLanguage The language to use
* @param array $aDuplicateQIDs
* @return array
*/
function createFieldMap($survey, $style = 'short', $force_refresh = false, $questionid = false, $sLanguage = '', &$aDuplicateQIDs = array())
</syntaxhighlight>

'''Good:'''

* Name is verb and noun
* Each argument is documented (almost)

'''Bad:'''

* Returns "array", which can be anything. A separate class for "Fieldmap" would be better.
* Not clear if it should be "createFieldMap" or "createFieldmap" - is "fieldmap" one word or two?
* Very many boolean arguments. Should probably be a class with methods like <code>$fieldmapCreator->setForceRefresh(true);</code> instead.
* Too long.
* Doesn't elaborate on what "fieldmap" really is, and does not link to any documentation about it.
* Access super-global, which makes it hard to test. Should instead return a data-transfer object, like:<br><syntaxhighlight lang="php">
$_SESSION['fieldmap'] = createFieldMap(...);
</syntaxhighlight>
* Has no test
* Mixes Hungarian notation with non-Hungarian notation in the argument list

== Defensive programming and error handling ==

todo

* '''Fail hard, fail early'''. The earlier the program crashes when something is wrong, the lower is the probability that you'll end up with corrupt data in the database that will later require manual labor to correct.
* Fail with '''actionable information'''
* Check input to functions and throw <code>InvalidArgumentException</code> if it violates the function's pre-conditions
* Use assert for class-internal invariants
* Use assert to make assumptions explicit for the reader

== Documentation ==

=== PHPDoc ===

* All functions must have a proper docblock
* The first line of the docblock should describe the relation between ''all'' the input arguments and the output of the function in a single sentence
* Each parameter must have the correct type
* Don't use <code>array</code> as type if it's a list of object - instead, use <code>[]</code> like so: <code>Survey[]</code> for a list of surveys

=== Technical documentation ===

todo, UML, scenarios, use-cases

== The PHP of yesterday ==

Old idioms and habits that should be abandoned.

* Don't use associative arrays, almost never. Data-transfer objects have multiple benefits: they are clearly structured, can be documented, can enforce invariants. There's ''no'' performance overhead of objects compared to arrays in modern PHP.
* Objects are already passed by reference; arrays are value types
* Use <code>[]</code> instead of <code>array()</code>
* Hungarian notation was useful before static analysis existed for PHP. These days it's better to use something that can be checked automatically: docblock @param and inline @var annotations.

== The PHP of tomorrow ==

todo

Union tags

Short functions

Match expressions

== Security ==

todo

XSS

Database injection

Permissions and roles

== Performance ==

todo

Loading too many rows into PHP models

== Testing ==

todo

QA

PHPUnit

TDD

Mocks, can't mock functions, static methods, mocking as a DSL, PHPUnit mocking tools

Pure functions, referential transparency, side-effects

Unit, functional, integration

Don't test the framework; don't test PHP

Makes sure the function or class lives up to its specification; make sure it will ''always'' live up to its specification, even in the future, to avoid regressions.

== Static analysis ==

<code>php -l</code>, CodeSniffer, Mess Detector, Psalm

== Database design ==

todo

== JavaScript ==

todo

classes, functions, components, tests

== CSS ==

todo

== HTML ==

todo

== Resources ==

todo

Books, links, videos

Workarounds: Question design, layout and theme-ing - LimeSurvey 3.0+

2021-04-19T13:39:08Z

Olle:

This section more or less deals with styling your survey, adjusting the layout and setting up special question types. You can find '''similar information''' at these pages:

* [[Theme editor|The theme editor - LimeSurvey 3.0+]]
* [[Workarounds: Manipulating a survey at runtime using Javascript - LimeSurvey 3.0+]]
* [[Workarounds: Survey behaviour - LimeSurvey 3.0+]]
* [[Workarounds: Further solutions provided by LimeSurvey users - LimeSurvey 3.0+]]
* [[Question themes]]

<div class="simplebox"><center><br />'''Please keep in mind that these workarounds are not official LimeSurvey extensions - they are solutions that users have created for themselves. <span style='color:#EE0000'>Therefore LimeSurvey can't offer guarantees or support for these solutions.</span><br />If you have questions, please contact the users that, thankfully, shared their solutions with the community.'''<br /><br /></center></div>

{{Note|'''If you would like to receive survey design support, please contact one of the authorized LimeSurvey partners listed here:''' https://limesurvey.com .}}

=Alternate background colour of questions=

To alternate the background colour of questions, open the questions one by one and use CSS to edit each question's background. For example, if you wish to change the background colour of a question thas has the ID 6, use the below code:

<syntaxhighlight lang="css">
<style>
.question6 {
background-color: #E0EBF8;
}
</style>
</syntaxhighlight>

To check the ID of a question, create and save it into a question group, and then access again the question editor. You will see above the question code the ID of the question:

<center>[[File:ID_location_question.png]]</center>

=Card sorting question=

A custom question theme for Slider Control Buttons for LimeSurvey 3.x can be found here - https://github.com/tpartner/LimeSurvey-Card-Sorting-3.x

=Create MaxDiff question type=

''Tested with: LimeSurvey 3.17.3''

This workaround uses JavaScript to convert an '''''Array (flexible labels) by column''''' question into a [http://en.wikipedia.org/wiki/MaxDiff MaxDiff] question type.

<center>[[File:MaxDiff_question.png]]</center>

'''Example'''<br />
* [[Media:MaxDiff_question.zip]]

'''IMPLEMENTATION'''
#[[Workarounds: Manipulating a survey at runtime using Javascript#How to use Script (eg. JavaScript etc.) in LimeSurvey? - LimeSurvey 3.0+|Set up your survey to use JavaScript]].
#Create an [[Question_type_-_Array_by_column|Array (flexible labels) by column question]] with two subquestions (representing the left and right columns, respectively).
#Add answers to the array - (representing the rows).
#Create a copy the default theme (extend the default theme).
#Add the following to the end of '''''custom.js''''' in your new template:
<syntaxhighlight lang="javascript" enclose="div">function maxDiff(qID, randomize) {

// Identify some elements
var thisQuestion = $('#question'+qID);
var thisTable = $('table.subquestion-list:eq(0)', thisQuestion);

// Assign a new question class
$(thisQuestion).addClass('max-diff-array');

// Move the columns
$('thead tr:eq(0)', thisTable).prepend($('thead tr:eq(0) th:eq(1)', thisTable));
$('tr.answers-list', thisTable).each(function(i){
$('td.answer-item:eq(0)', this).prependTo(this);
});

// Random rows
if(randomize) {
var rowsArr = [];
$('tr.answers-list', thisTable).each(function(i){
$(this).attr('data-index', i);
rowsArr.push(i);
});
shuffleArray(rowsArr);
$(rowsArr).each(function(i){
$('tbody', thisTable).append($('tr[data-index="'+this+'"]', thisTable));
});
}

// Prevent clicking twice in the same row
$('input:radio', thisQuestion).on('click', function () {

$('input:radio', thisQuestion).prop('disabled', false);
$('input:radio:checked', thisQuestion).each(function(i) {
var thisRow = $(this).closest('tr.answers-list');
$('input:radio', thisRow).not(this).prop('disabled', true);
});
});

// Fix up the row classes
var rowClass = 1;
$('tr.answers-list', thisTable).each(function(i) {
$(this).addClass('array'+(2-(i%2)));
});
}

function shuffleArray(array) {
for (var i = array.length - 1; i > 0; i--) {
var j = Math.floor(Math.random() * (i + 1));
var temp = array[i];
array[i] = array[j];
array[j] = temp;
}
return array;
}</syntaxhighlight>
#Add the following to the end of '''''custom.css''''' in your new template:<syntaxhighlight lang="css" enclose="div">.max-diff-array th.answertext {
text-align: center;
border-right: 3px solid #FFFFFF;
border-left: 3px solid #FFFFFF;
}

/* Override the responsive "no-more-tables" stuff */
@media only screen and (max-width: 801px) {

.max-diff-array .no-more-tables table {
display: table;
border-collapse: inherit;
}

.max-diff-array .no-more-tables thead,
.max-diff-array .no-more-tables tbody {
display: table-row-group;
}

.max-diff-array .no-more-tables tr {
left: auto;
position: relative;
top: auto;
display: table-row;
border: 0 none;
}

.max-diff-array .no-more-tables th,
.max-diff-array .no-more-tables td {
display: table-cell;
text-align: center !important;
color: #2c3e50;
font-size: 15px;
}

.max-diff-array th.answertext {
border-right: 3px solid #FFFFFF;
border-left: 3px solid #FFFFFF;
}

.max-diff-array .answer-item label span {
display: none !important;
}
}</syntaxhighlight>
#Add a script like this to the question source of the Array (flexible labels) question:<syntaxhighlight lang="javascript" enclose="div"><script type="text/javascript" charset="utf-8">
$(document).ready(function(){
// Call the maxDiff() function
// Set the second parameter to true for randomized rows
maxDiff({QID}, true);
});
</script></syntaxhighlight>

=Likert Scale=

To create a likert scale, you have to choose either Array or Array (5 point choice) as question type to part the answer by using a pipe char "|" - which answer should be on the left side and which one on the right side of the array. For example, If you want to have 'Good' on the left side of the row and 'Evil' on the right side of the row, just write 'Good|Evil' into the answer field:

<center>[[File:Likert_array_subquestions.png]]</center>

<center>[[File:H_SD.jpg]]</center>

'''Example:''' [[Media:Question type - Array - Semantic Differential Question Type.zip]]

=Dropdown responses for Array=

Link tpartner forum

Download example link

Screenshot

=Embedding audio in questions=

To embed the audio clips, you have to use a code similar to the one listed below:

<syntaxhighlight lang=html>
<audio controls="controls"><source src=" /upload/surveys/336775/images/MP3_file_name.mp3
" type="audio/mp3" /> Your browser does not support this audio</audio>
</syntaxhighlight>

Once embedded, the question would look like this:

<center>[[File:Embed_audio_example.png]]</center>

To introduce audio clips as subquestions and/or answers, click on the green pencil to open the HTML editor and attach the corresponding code (while being in the source mode).

{{Alert|title=Attention|text=You may need to turn off the XSS filter - see the documentation for [[Global settings#Security|global settings]].}}

=Evaluative Space Grid (ESG)=

Check the old wiki section -> working

=Hiding inputs of a "Multiple options with comments" question=

See example + forum post

=How to hide the asterisk= 


The instructions are similar to the ones presented above for LimeSurvey 2.


* Access the desired theme. If it is a default theme, create a copy of it by clicking on the "extend" button.
* Access the list of themes and click on the '''theme editor''' that corresponds to the newly created theme.
* On the left side, you can visualise the corresponding CSS files of your theme.
* Click on custom.css and add the following line:


<syntaxhighlight lang="css" enclose="div">.asterisk {display: none;}</syntaxhighlight>


* Save the changes. The red asterisk that is usually displayed at the beginning of the question text is hidden.

=How to hide the language switcher from the welcome page= 


In the case in which you decide to launch a multilingual survey, you will observe on the welcome page a drop-down menu that permits your respondents to select the language in which they wish to fill in your survey:


<center>[[File:Language switcher show languages.png]]</center>


However, in certain scenarios you wish to hide the respective option. There are many ways in which you can hide the language switcher. The '''"twig"''' way is displayed below.


Access [[Themes]] from the global [[Administering LimeSurvey|Configuration menu]]:


<center>[[File:Language switcher themes.png]]</center>


Click on the '''Theme editor''' button to edit the desired theme:


<center>[[File:Language switcher theme editor.png]]</center>


{{Note|LimeSurvey does not allow you to edit the standard themes! If you wish to add changes to a standard theme, click on the '''Extend''' button located on the top bar to create an editable copy of it.}}


Look on the left side of the screen for the '''language_changer.twig''' file.


<center>[[File:Location language switcher twig.png]]</center>


Go to the line that contains the following function:


<syntaxhighlight lang="php" enclose="div">
{% if aSurveyInfo.alanguageChanger.show == true %}
</syntaxhighlight>


Comment it out (replace "%" with "#") and copy the following line below it:


<syntaxhighlight lang="php" enclose="div">
{% if false == true %}
</syntaxhighlight>


The line should look like this in the end:


<center>[[File:Language switcher code replacement.png]]</center>


Click on "Copy to local theme and save changes".


Access your survey and select the edited theme from the [[General settings|general settings]] panel. Now, the welcome page should look like this:


<center>[[File:Hide language switcher twig.png]]</center>

=How to hide the language switcher located on the top menu= 


To hide the top language switcher, we will follow pretty much the same steps as described above. We just have to access the right twig file to edit it. Access again the theme you wish to change, and then go to '''Screen''' which is located in the upper-right part of the window and select '''Navigation''' from the dropdown list. Now, look on the left side of the window for "language_changer_top_menu.twig". Click on it and comment out:


<syntaxhighlight lang="php" enclose="div">
{% if aSurveyInfo.alanguageChanger.show == true %}
</syntaxhighlight>


Add the following line below it:


<syntaxhighlight lang="php" enclose="div">
{% if false == true %}
</syntaxhighlight>


No language switcher will be displayed on the right side of the screen:


<center>[[File:Language switcher hide top menu.png]]</center>

=Image interest points and comments=

A custom question theme for Slider Control Buttons for LimeSurvey 3.x can be found here - https://github.com/tpartner/LimeSurvey-Image-Interest-Points-3.x

=Public registration - mandatory fields= 


If you use a [[Survey participants|survey participants table]] and you also allow [[Participant_settings#Allow_public_registration|public registration]], then users will be prompted by the following message:


<center>[[File:non-mandatory public reg.png]]</center>


As it can be observed above, only the email field is mandatory.


To have all three fields marked as being mandatory, please edit your survey theme accordingly. If you use '''Fruity''', you have to go to the '''registration''' screen and see how the participants email field looks like:


<syntaxhighlight lang="twig">
{# Participants email #}
<div class='{{ aSurveyInfo.class.registerformcolrowc }} form-group row' {{ aSurveyInfo.attr.registerformcolrowc }}>
<label {{ aSurveyInfo.attr.registerformcolrowclabel }} class='{{ aSurveyInfo.class.registerformcolrowclabel }} control-label'> {{ gT("Email address:") }} {{ include('./subviews/registration/required.twig') }}</label>
<div {{ aSurveyInfo.attr.registerformcolrowcdiv }} >
{{ C.Html.textField('register_email', aSurveyInfo.sEmail, ({'id' : 'register_email','class' : 'form-control input-sm','required' : true})) }}
</div>
</div>
</syntaxhighlight>


After that, make sure to edit the first name and last name fields correspondingly by adding the label: <syntaxhighlight lang="twig">{{ include('./subviews/registration/required.twig') }}</syntaxhighlight> and this line which makes the field mandatory to be filled out: <syntaxhighlight lang="twig">'required' : true</syntaxhighlight>


The edited file should look like this:


<syntaxhighlight lang="twig">
{# Participants first name #}
<div class='{{ aSurveyInfo.class.registerformcolrow }} form-group row' {{ aSurveyInfo.attr.registerformcolrow }}>
<label for='register_firstname' class='{{ aSurveyInfo.class.registerformcolrowlabel }} control-label '>{{ gT("First name:") }} {{ include('./subviews/registration/required.twig') }}</label> {# extra label #}
<div class="">
{{ C.Html.textField('register_firstname', aSurveyInfo.sFirstName, ({'id' : 'register_firstname','class' : 'form-control', 'required' : true})) }} {# mandatory field #}
</div>
</div>


{# Participants last name #}
<div class='{{ aSurveyInfo.class.registerformcolrowb }} form-group row' {{ aSurveyInfo.attr.registerformcolrowb }}>
<label {{ aSurveyInfo.attr.registerformcolrowblabel }} class='{{ aSurveyInfo.class.registerformcolrowblabel }} control-label '>{{ gT("Last name:") }} {{ include('./subviews/registration/required.twig') }}</label> {# extra label #}
<div {{ aSurveyInfo.attr.registerformcolrowbdiv }} >
{{ C.Html.textField('register_lastname', aSurveyInfo.sLastName, ({'id' : 'register_lastname', 'class' : 'form-control', 'required' : true})) }} {# mandatory field #}
</div>
</div>
</syntaxhighlight>


Now, the public registration page should look like this (all the fields being mandatory):


<center>[[File:mandatory public reg.png]]</center>

=Reverse slider=

{{Box|The reverse slider feature can be used in any (multiple) numerical input question type. For more details, please check the [[Question_type_-_Multiple_numerical_input#Slider|slider wiki subsection]].}}

=Slider with control buttons=

A custom question theme for Slider Control Buttons for LimeSurvey 3.x can be found here - https://github.com/tpartner/LimeSurvey-Slider-Controls-3x

QS:Question theme

2021-04-19T13:34:17Z

Olle:

<translate>

<languages />

<onlyinclude>
===Question theme (question_theme)=== 


'''Description'''


It allows you to use customized themes for the respective question.


'''Available options'''
*Your created question themes which are located under the '''Question themes''' in the [[Themes]] panel.

See: https://manual.limesurvey.org/Question_themes


<div class="simplebox">[[File:help.png]] '''Note:''' This feature is under development at the moment.</div>
</onlyinclude>


[[Category:Question Settings]][[Category:Question Display Options]]

</translate>

Code quality guide

2021-04-14T11:20:24Z

Olle: /* Static analysis */

Code quality guide

2021-04-14T10:14:19Z

Olle: /* Assertions */

Code quality guide

2021-04-12T15:34:57Z

Olle: /* Performance */