Extension:StructuredDiscussions/Coding Conventions

In addition to the standard coding conventions for MediaWiki Flow uses the following conventions:

PHP

While not perfect we try to regularly run the static analysis tools from phpstorm against the Flow project. This is especially useful when refactoring as the static analysis can find undefined methods/classes/etc.

Syntax

• Pure methods in a class should be marked static. Pure methods have no state and always have the same output when given the same input.
• Avoid creating static methods that are not pure.
• Annotate arrays of single types as MyObject[], string[], etc rather than array to convey more complete type information

Other

• Most php in Flow uses en:Dependency_Injection via container.php.
• The container should only be accessed statically from entry points to Flow from MediaWiki.
  • Flow\\Block\\* is currently an exception to this rule, but is essentially an inner entry point.
• Global variables should only be accessed from container.php and injected into classes via either constructor or setter injection.
• Name action API parameters like 'foobar', not 'foo-bar', 'foo_bar', etc.

Data loading and processing is handled independently to allow for loose coupling and the single responsibility principle. In practice this means that most API results are generated through two objects. The first object is a query object. It takes user provided parameters and queries the data store. These objects return an array of Flow\\Formatter\\FormatterRow instances. The query result is passed into a Formatter instance such as Flow\\Formatter\\RevisionFormatter. The Formatter does the job of sanitizing the data provided down to only that visible to the current user and formatting that data in a useful way. The Formatter result is either directly returned in the case of an API request, or passed on to Lightncandy to perform the api result -> HTML transformation.

Handlebars

Syntax

If an element is more than 100 characters long it should be converted to a multi-line element. Multi-line elements have one attribute per line with the attributes lined up using spaces. Following the attributes is a single line containing only the closing > to clearly de-lineate the attributes block from the content of the element. Attributes may also be expanded to multiple lines if they would extend past 100 lines or when they contain multiple conditionals.

Example multi-line element:

   <a href="{{foo.url}}"
      title="{{foo.title}}"
      class="mw-ui-button
             mw-ui-{{#if something}}progressive{{else}}destructive{{/if}}
             {{#if isModerated}}foo-moderated{{/if}}"
      data-something="{{blah.blah.blah}}"
   >
       {{content}}
   </a>

Helpers

Helpers should be as generic as possible. For example prefer:

   {{l10n (concat "foo-" value "-baz")}}

over a case specific helper like

   {{mySpecialL10n value}}