Writing code, both science and art
Jan Zavrl
Drupal Camp London, March 2019
Jan Zavrl
Full stack developer
Senior Drupal developer at NDP
Acquia certified Drupal 8 Grand Master
@jnzavrl | jzavrl | janzavrl.me
@ndp_studio | ndp-studio.com
Writing code, both science and art, London, March 2019
The what and the why
- Rules, expectations, consistency
- Two types - style and substance
- Automating API documentation
- For the guy next to you and after you
Writing code, both science and art, London, March 2019
Let's start with the basics
- Code style and formatting
- Indentation
- Spaces
- Opening tags, end with blank line
- Line wrapping and length
Writing code, both science and art, London, March 2019
if (isset($view_modes['teaser'])) {
entity_get_display('node', $type->id(), 'teaser')
->setComponent('body', array(
'label' => 'hidden',
'type' => 'text_summary_or_trimmed',
))
->save();
}
if(isset($view_modes['teaser'])){
entity_get_display('node',$type->id(),'teaser')
->setComponent('body',array(
'label'=>'hidden',
'type'=>'text_summary_or_trimmed'
))->save();
}
Writing code, both science and art, London, March 2019
Control structures
- If, switch and try statements
- Template exceptions
Writing code, both science and art, London, March 2019
if ($actual_count == $expected_count) {
$message = $this->t('Expected count is correct');
}
elseif ($expected_count == 0) {
$message = $this->t('Expected count is 0');
}
else {
$message = $this->t('Expected count is unknown');
}
Writing code, both science and art, London, March 2019
switch ($key) {
case 'field_name':
$checked_value = $field_storage->getName();
break;
case 'field_id':
case 'field_storage_uuid':
$checked_value = $field_storage->uuid();
break;
default:
$checked_value = $field->get($key);
break;
}
Writing code, both science and art, London, March 2019
try {
$this->migration->checkRequirements();
}
catch (RequirementsException $e) {
$this->message->display(
$this->t(
'Migration @id did not meet the requirements. @message @requirements',
array(
'@id' => $this->migration->id(),
'@message' => $e->getMessage(),
'@requirements' => $e->getRequirementsString(),
)
),
'error'
);
return MigrationInterface::RESULT_FAILED;
}
Writing code, both science and art, London, March 2019
{% if data.width %}
{% trans %}
width {{ data.width }}
{% endtrans %}
{% elseif data.height %}
{% trans %}
height {{ data.height }}
{% endtrans %}
{% endif %}
<?php if ($content): ?>
<div class="content">
<?php print $content; ?>
</div>
<?php endif; ?>
Writing code, both science and art, London, March 2019
Arrays
- Short array syntax
- Multiline or single line
- Trailing comma
Writing code, both science and art, London, March 2019
$test_samples = ['Save and continue', 'Anonymous', 'Language'];
$header['type'] = [
'data' => $this->t('Field type'),
'class' => array(RESPONSIVE_PRIORITY_MEDIUM),
];
Writing code, both science and art, London, March 2019
Naming conventions
- Variables as snake_case or lowerCamelCase
- Constants as UPPERCASE
- Classes as UpperCamelCase
- Methods and properties as lowerCamelCase
Writing code, both science and art, London, March 2019
Comment your code
- File doc block - @file, with exceptions
- Functions and methods doc block
- Hook implementations
- {@inheritdoc}
- Inline comments
Writing code, both science and art, London, March 2019
<?php
/**
* @file
* Allows to ban individual IP addresses.
*/
use Drupal\Core\Routing\RouteMatchInterface;
/**
* Get a translated version of the field item instance.
*
* To indicate that a field item applies to one translation of an entity and
* not another, the property path must originate with a translation of the
* entity. This is the reason for using target_instances, from which the
* property path can be traversed up to the root.
*
* @param \Drupal\Core\Field\FieldItemInterface $field_item
* The untranslated field item instance.
* @param $langcode
* The langcode.
*
* @return \Drupal\Core\Field\FieldItemInterface
* The translated field item instance.
*/
protected function createTranslatedInstance(FieldItemInterface $item, $langcode) {
Writing code, both science and art, London, March 2019
/**
* Implements hook_entity_bundle_info_alter().
*/
function forum_entity_bundle_info_alter(&$bundles) {
/**
* Implements hook_ENTITY_TYPE_presave() for node entities.
*
* Assigns the forum taxonomy when adding a topic from within a forum.
*/
function forum_node_presave(EntityInterface $node) {
Writing code, both science and art, London, March 2019
CSS
- Very similar to the default formatting
- Indentation, spaces, whitespace
- New lines between rulesets, none between related rulesets
- File and inline comments
Writing code, both science and art, London, March 2019
JavaScript
- File closure and strict mode
- Naming conventions on variables, functions and constants
- Do not use global variables
- Function declaration and calls
- Commenting your code
Writing code, both science and art, London, March 2019
/**
* @file
* Attaches behavior for the Editor module.
*/
(function ($, Drupal, drupalSettings) {
'use strict';
...
})(jQuery, Drupal, drupalSettings);
Writing code, both science and art, London, March 2019
/**
* Detaches editor behaviors from the field.
*
* @param {HTMLElement} field
* The textarea DOM element.
* @param {object} format
* The text format that's being activated, from
* drupalSettings.editor.formats.
* @param {string} trigger
* Trigger value from the detach behavior.
*/
Drupal.editorDetach = function (field, format, trigger) {
if (format.editor) {
Drupal.editors[format.editor].detach(field, format, trigger);
// Restore the original value if the user didn't make any changes yet.
if (field.getAttribute('data-editor-value-is-changed') === 'false') {
field.value = field.getAttribute('data-editor-value-original');
}
}
};
Writing code, both science and art, London, March 2019
/**
* Enables editors on text_format elements.
*
* @type {Drupal~behavior}
*
* @prop {Drupal~behaviorAttach} attach
* Attaches an editor to an input element.
* @prop {Drupal~behaviorDetach} detach
* Detaches an editor from an input element.
*/
Drupal.behaviors.editor = {
attach: function (context, settings) {
// If there are no editor settings, there are no editors to enable.
if (!settings.editor) {
return;
}
$(context).find('[data-editor-for]').once('editor').each(function () {
var $this = $(this);
...
});
}
};
Writing code, both science and art, London, March 2019
Twig
- Looping over data
- Attributes and filters
- Comments - file doc block
- Do not use any logic
Writing code, both science and art, London, March 2019
{% for container in containers %}
<div class="layout-column layout-column--half">
{% for block in container.blocks %}
{{ block }}
{% endfor %}
</div>
{% endfor %}
Writing code, both science and art, London, March 2019
{#
/**
* @file
* Default theme implementation to display a block.
*
* Available variables:
* - plugin_id: The ID of the block implementation.
* - label: The configured label of the block if visible.
* - configuration: A list of the block's configuration values.
* - label: The configured label for the block.
* - label_display: The display settings for the label.
* - provider: The module or other provider that provided this block plugin.
* - Block plugin specific settings will also be stored here.
* - content: The content of this block.
* - attributes: array of HTML attributes populated by modules, intended to
* be added to the main container tag of this template.
* - id: A valid HTML ID and guaranteed unique.
* - title_attributes: Same as attributes, except applied to the main title
* tag that appears in the template.
* - title_prefix: Additional output populated by modules, intended to be
* displayed in front of the main title tag that appears in the template.
* - title_suffix: Additional output populated by modules, intended to be
* displayed after the main title tag that appears in the template.
*
* @see template_preprocess_block()
*
* @ingroup themeable
*/
#}
Writing code, both science and art, London, March 2019
Object oriented code
- Classes and interfaces
- Methods and properties
- Translate function, with placeholders
- @variable, %variable, :variable
- Dependency injection
Writing code, both science and art, London, March 2019
namespace Drupal\block\Entity;
use Drupal\Core\Cache\Cache;
...
/**
* Defines a Block configuration entity class.
*
* @ConfigEntityType(
* ...
*/
class Block extends ConfigEntityBase implements BlockInterface, EntityWithPluginCollectionInterface {
/**
* The ID of the block.
*
* @var string
*/
protected $id;
/**
* The plugin collection that holds the block plugin for this entity.
*
* @var \Drupal\block\BlockPluginCollection
*/
protected $pluginCollection;
/**
* {@inheritdoc}
*/
public function getPlugin() {
return $this->getPluginCollection()->get($this->plugin);
}
...
}
Writing code, both science and art, London, March 2019
/**
* Constructs a ContentEntityForm object.
*
* @param \Drupal\Core\Entity\EntityManagerInterface $entity_manager
* The entity manager.
* @param \Drupal\user\PrivateTempStoreFactory $temp_store_factory
* The factory for the temp store object.
*/
public function __construct(EntityManagerInterface $entity_manager, PrivateTempStoreFactory $temp_store_factory) {
parent::__construct($entity_manager);
$this->tempStoreFactory = $temp_store_factory;
}
/**
* {@inheritdoc}
*/
public static function create(ContainerInterface $container) {
return new static(
$container->get('entity.manager'),
$container->get('user.private_tempstore')
);
}
/**
* {@inheritdoc}
*/
public function save(array $form, FormStateInterface $form_state) {
$node = $this->entity;
$insert = $node->isNew();
$node->save();
$node_link = $node->link($this->t('View'));
Writing code, both science and art, London, March 2019
$this->t('Direction that text in this language is presented.');
$this->t('The %label search page has been updated.', [
'%label' => $this->entity->label()
]);
Writing code, both science and art, London, March 2019
What can (should) you do?
- Set up your code editor
- Use Coder and CodeSniffer
- Formatting comes a long way
- Be consistent and respect
style
Writing code, both science and art, London, March 2019
Using Coder Sniffer
- PHP CodeSniffer
- Coder, provides rulesets
- Manual checks
- Using code editors
Writing code, both science and art, London, March 2019
Installing necessities
Writing code, both science and art, London, March 2019
composer global require drupal/coder:8.x
composer global require dealerdirect/phpcodesniffer-composer-installer
phpcs -i
Manual steps, more options are available, but the above is the bare minimum
PHPStorm
Writing code, both science and art, London, March 2019
Other editors
Writing code, both science and art, London, March 2019
- Visual Studio (extension)
- Sublime Text (plugin)
- Atom (plugin)
Be consistent!
Writing code, both science and art, London, March 2019
Simply making it work doesn't cut it.
Writing code, both science and art, London, March 2019
Documentation and resources
https://www.drupal.org/docs/develop/standards
https://www.drupal.org/docs/8/modules/code-review-module
Writing code, both science and art, London, March 2019
@jnzavrl | jzavrl | janzavrl.me
@ndp_studio | ndp-studio.com
Questions, comments?
Feel free to give me a nudge outside.
Writing code, both science and art, London, March 2019
Thank you
Writing code, both science and art
By Jan Zavrl
Writing code, both science and art
Many beginners in Drupal and also generally in development, feel that as long as something works we should leave it as it is. Wrong.
- 738