{"_id":"56b55f905f1cf00d00cc477e","api":{"params":[],"results":{"codes":[]},"settings":"","url":"","auth":"required"},"githubsync":"","link_url":"","slug":"introduction","sync_unique":"","excerpt":"What's Science all about?","hidden":false,"project":"56b534f15f1cf00d00cc4759","updates":["56b9e13bce5d540d00e2d719","56bc4173b5642e0d006c022d"],"user":"56b534d0168b5c1700c159a7","body":"Do you have an old project? Maybe a project that you think can be improved?\n\nIt's sometimes difficult to improve upon existing code, without running the risks of breaking functionality. That's where Scientist comes in. Scientist lets your run your existing code, and your newly proposed code in parallel. Comparing the results of both to ensure that your functionality remains consistent. It's a sharp knife in the refactorer's toolkit.\n\nUntil you're happy that your new code is functioning as it should be, Scientist will continue to execute your old code. Your application won't feel any different.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Case Study\"\n}\n[/block]\nLet's imagine that we have the following snippet of code in our website.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<?php\\n\\n$template = 'Welcome to the site, <name>!';\\n\\n$name = 'Dayle';\\n\\necho str_replace('<name>', 'Dayle', $template);\",\n      \"language\": \"php\"\n    }\n  ]\n}\n[/block]\nWhat a lovely greeting app! Except.. well. It could be better, couldn't it? I wonder if using a `preg_replace()` might make it better? A little faster maybe?\n\nWhy don't we create an experiment to find out? Let's extract our code into two callbacks to prepare it for our Scientist.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<?php\\n\\n/**\\n * We'll create a control callable. This will contain\\n * the code that we know and trust.\\n */\\n$control = function($template, $name) {\\n  return str_replace('<name>', $name, $template);\\n};\\n\\n/**\\n * Next, let's create a trial callable. It's our\\n * potentially risky, potentially awesome code.\\n */\\n$trial = function($template, $name) {\\n return preg_replace('/\\\\<name\\\\>/', $name, $template); \\n};\",\n      \"language\": \"php\"\n    }\n  ]\n}\n[/block]\nWrapping our existing code in a closure is a great way of making a callback that can be used with scientist. We could always use the array callback notation to call a class method instead, if we so wished.\n\nWe've created two callables. One contains our old code, and the other contains our new `preg_replace()` powered code. We've got the makings of a fine experiment, so let's set up the laboratory and do some science.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<?php\\n\\n/**\\n * First we need to create a new Laboratory instance.\\n * Here's where we're going to be doing our science.\\n */\\n$lab = new \\\\Scientist\\\\Laboratory;\\n\\n/**\\n * Let's define a new experiment, and pass it our\\n * control and trial callables.\\n */\\n$experiment = $lab->experiment('Greet a user by name.')\\n  ->control($control)\\n  ->trial('Use preg_replace.', $trial);\\n\\n/**\\n * Next, we'll run the experiment, passing our\\n * parameters in. We can use the result to\\n * greet our user.\\n */\\necho $experiment->run($template, $name);\",\n      \"language\": \"php\",\n      \"name\": null\n    }\n  ]\n}\n[/block]\nThere's a few things happening here. Let's step through them slowly.\n\nOn line seven we're created a brand new Laboratory instance.\n\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<?php\\n\\n$lab = new \\\\Scientist\\\\Laboratory;\",\n      \"language\": \"php\"\n    }\n  ]\n}\n[/block]\nWe need one of these to define a new experiment.\n\nNext, we use the Laboratory to define a new experiment. We pass an experiment name to the `experiment()` method, the control callable to the `control()` method, and the trial callable to the `trial()` method along with a helpful trial name.\n\nWe could provide as many alternate trials as we like, but for simplicity sake, I'll only be using one in this example. We'd just keep chaining the `trial()` methods.\n\nFinally, we `run()` the experiment.\n\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<?php\\n\\necho $experiment->run($template, $name);\",\n      \"language\": \"php\"\n    }\n  ]\n}\n[/block]\nThe parameters we pass to the `run()` method will be given to both our control and trial callables. It's done by magic! We don't need to worry about that.\n\nLet's examine a few facts.\n\n  * **All** control and trial callables will be executed when an experiment runs.\n  * **Only the control method** will return a value from the experiment.\n  * The trial callables will **never** output values to the rest of the codebase.\n  * Trial callables will have their output compared with the control's, automatically.\n\nThe result of `run()` will be the output from our control callable. The code that we know and trust. The code that's safe to run for our users.\n\nOur trials will be executed too, but instead of using the result, it will be compared with the control, and stored (using Journals) for later examination.\n\nWe can continue to examine the results from our experiment. The speed of the trials, whether the resulting values match reliably, whether they use too much memory, and tweak our experiment code as needed until the trial is an identically (or better) performing match for the control.\n\nAt this point, we can safely remove our experiment, and run only the new, now successful 'trial' code.\n\nWe have not, at any point, exposed our users to the experimental code until we are absolutely certain that it functions as it's supposed to.\n\nThat is Science.","version":"56b534f25f1cf00d00cc475c","__v":3,"category":"56b55e5b5f1cf00d00cc477c","createdAt":"2016-02-06T02:50:56.283Z","link_external":false,"order":0,"title":"Introduction","type":"basic","childrenPages":[]}

Introduction

What's Science all about?

Do you have an old project? Maybe a project that you think can be improved? It's sometimes difficult to improve upon existing code, without running the risks of breaking functionality. That's where Scientist comes in. Scientist lets your run your existing code, and your newly proposed code in parallel. Comparing the results of both to ensure that your functionality remains consistent. It's a sharp knife in the refactorer's toolkit. Until you're happy that your new code is functioning as it should be, Scientist will continue to execute your old code. Your application won't feel any different. [block:api-header] { "type": "basic", "title": "Case Study" } [/block] Let's imagine that we have the following snippet of code in our website. [block:code] { "codes": [ { "code": "<?php\n\n$template = 'Welcome to the site, <name>!';\n\n$name = 'Dayle';\n\necho str_replace('<name>', 'Dayle', $template);", "language": "php" } ] } [/block] What a lovely greeting app! Except.. well. It could be better, couldn't it? I wonder if using a `preg_replace()` might make it better? A little faster maybe? Why don't we create an experiment to find out? Let's extract our code into two callbacks to prepare it for our Scientist. [block:code] { "codes": [ { "code": "<?php\n\n/**\n * We'll create a control callable. This will contain\n * the code that we know and trust.\n */\n$control = function($template, $name) {\n return str_replace('<name>', $name, $template);\n};\n\n/**\n * Next, let's create a trial callable. It's our\n * potentially risky, potentially awesome code.\n */\n$trial = function($template, $name) {\n return preg_replace('/\\<name\\>/', $name, $template); \n};", "language": "php" } ] } [/block] Wrapping our existing code in a closure is a great way of making a callback that can be used with scientist. We could always use the array callback notation to call a class method instead, if we so wished. We've created two callables. One contains our old code, and the other contains our new `preg_replace()` powered code. We've got the makings of a fine experiment, so let's set up the laboratory and do some science. [block:code] { "codes": [ { "code": "<?php\n\n/**\n * First we need to create a new Laboratory instance.\n * Here's where we're going to be doing our science.\n */\n$lab = new \\Scientist\\Laboratory;\n\n/**\n * Let's define a new experiment, and pass it our\n * control and trial callables.\n */\n$experiment = $lab->experiment('Greet a user by name.')\n ->control($control)\n ->trial('Use preg_replace.', $trial);\n\n/**\n * Next, we'll run the experiment, passing our\n * parameters in. We can use the result to\n * greet our user.\n */\necho $experiment->run($template, $name);", "language": "php", "name": null } ] } [/block] There's a few things happening here. Let's step through them slowly. On line seven we're created a brand new Laboratory instance. [block:code] { "codes": [ { "code": "<?php\n\n$lab = new \\Scientist\\Laboratory;", "language": "php" } ] } [/block] We need one of these to define a new experiment. Next, we use the Laboratory to define a new experiment. We pass an experiment name to the `experiment()` method, the control callable to the `control()` method, and the trial callable to the `trial()` method along with a helpful trial name. We could provide as many alternate trials as we like, but for simplicity sake, I'll only be using one in this example. We'd just keep chaining the `trial()` methods. Finally, we `run()` the experiment. [block:code] { "codes": [ { "code": "<?php\n\necho $experiment->run($template, $name);", "language": "php" } ] } [/block] The parameters we pass to the `run()` method will be given to both our control and trial callables. It's done by magic! We don't need to worry about that. Let's examine a few facts. * **All** control and trial callables will be executed when an experiment runs. * **Only the control method** will return a value from the experiment. * The trial callables will **never** output values to the rest of the codebase. * Trial callables will have their output compared with the control's, automatically. The result of `run()` will be the output from our control callable. The code that we know and trust. The code that's safe to run for our users. Our trials will be executed too, but instead of using the result, it will be compared with the control, and stored (using Journals) for later examination. We can continue to examine the results from our experiment. The speed of the trials, whether the resulting values match reliably, whether they use too much memory, and tweak our experiment code as needed until the trial is an identically (or better) performing match for the control. At this point, we can safely remove our experiment, and run only the new, now successful 'trial' code. We have not, at any point, exposed our users to the experimental code until we are absolutely certain that it functions as it's supposed to. That is Science.