{"id":269,"date":"2024-08-06T20:32:19","date_gmt":"2024-08-06T20:32:19","guid":{"rendered":"https:\/\/permutationcity.co.uk\/bp\/?p=269"},"modified":"2024-08-12T19:00:45","modified_gmt":"2024-08-12T19:00:45","slug":"journey-destination-and-story","status":"publish","type":"post","link":"https:\/\/permutationcity.co.uk\/bp\/2024\/08\/06\/journey-destination-and-story\/","title":{"rendered":"Journey, destination and story"},"content":{"rendered":"\n<p>I&#8217;ve been thinking about writing this one for\n<a href=\"https:\/\/permutationcity.co.uk\/bp\/2024\/04\/02\/retrospective-1-26\/\">a while<\/a>,\nactually longer than that.\nI really needed an example to talk about.\nFortunately I\n<a href=\"https:\/\/permutationcity.co.uk\/bp\/2024\/07\/23\/iterative-development\/\">wrote some code<\/a>\nrecently.\nThis is about code changes, how they made and how to present them.<\/p>\n\n\n\n<p>I&#8217;m going to talk about code changes as having a few different parts:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li>The journey is how you take the existing code and make whatever changes are needed. You might have a clear specification that lets you go in a straight line. You might have a few notes about what is needed so the path may be winding. In either case there can be surprises. That might mean a detour, a new direction or backing up and starting again.<\/li>\n\n\n\n<li>The destination is the code you end up with. It might be similar to the original code, there might be a few changes or it could be completely different. If someone knew what your task was these might seem like obvious changes or they might be opaque.<\/li>\n\n\n\n<li>The story is the history you leave behind showing the start to the destination. This could be the same as your journey but it doesn&#8217;t have to be. This is what a code reviewer will see when the changes are being made. This is what a developer will find if they&#8217;re going back through the history to fix or extend the code in the future.<\/li>\n<\/ul>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"the-journey\">The journey<\/h2>\n\n\n\n<p>The problem with journeys is that they are complicated and messy.\nWe can look a my <a href=\"https:\/\/github.com\/glasgowmatthew\/BitsLibrary\/tree\/journey\">prototype&#8217;s journey<\/a> and\nwhat really happened.<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><a href=\"https:\/\/github.com\/glasgowmatthew\/BitsLibrary\/commit\/a205f5c56ef852482fd3589111342b1871d6264a\">Single bit manipulation library<\/a><\/li>\n\n\n\n<li><a href=\"https:\/\/github.com\/glasgowmatthew\/BitsLibrary\/commit\/b3aada78a677a1c48db1c8ae8dd0ba11da48605a\">fix identifier update<\/a><\/li>\n\n\n\n<li><a href=\"https:\/\/github.com\/glasgowmatthew\/BitsLibrary\/commit\/8dc37aa91d391b7cb971dd777288a8fb49c324b5\">fix IsClear<\/a><\/li>\n\n\n\n<li><a href=\"https:\/\/github.com\/glasgowmatthew\/BitsLibrary\/commit\/bee119e2f4989fdc255ab9ff4ee1f0e1a25d45b7\">fix remove logging<\/a><\/li>\n\n\n\n<li><a href=\"https:\/\/github.com\/glasgowmatthew\/BitsLibrary\/commit\/82113da0d1c3823909bf711f5a38cf1cb742cd28\">fix name update<\/a><\/li>\n\n\n\n<li><a href=\"https:\/\/github.com\/glasgowmatthew\/BitsLibrary\/commit\/09970427f4c8415a154fcf94a83f2da98ab2f3d4\">fix use xor for flip<\/a><\/li>\n\n\n\n<li><a href=\"https:\/\/github.com\/glasgowmatthew\/BitsLibrary\/commit\/8979d1cce1b26920567ccc073f5f8d663ba39a5f\">fix identifer change<\/a><\/li>\n\n\n\n<li><a href=\"https:\/\/github.com\/glasgowmatthew\/BitsLibrary\/commit\/90b830002f798f5670bfe10875644f6612d1f75a\">fix test bug<\/a><\/li>\n<\/ul>\n\n\n\n<p>This is my initial implementation of single bit manipulation functions and some tests.\nThen I have to fix some bugs, get rid of some debugging code I forgot about,\nfix some names, realise their is a simpler way of writing something, fix some more names\nand finally fix a test.<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><a href=\"https:\/\/github.com\/glasgowmatthew\/BitsLibrary\/commit\/0986f26e57122b9a9c054735e13e915e5bfa36d5\">Multi-bit manipulation library<\/a><\/li>\n\n\n\n<li><a href=\"https:\/\/github.com\/glasgowmatthew\/BitsLibrary\/commit\/850132844fc9d26ee648307352d7a84918752cb6\">Removing single bit operations<\/a><\/li>\n\n\n\n<li><a href=\"https:\/\/github.com\/glasgowmatthew\/BitsLibrary\/commit\/9e5c1e0e4ec0b46d5ce8dab4ebab4bae67d9b2f7\">fix remove single bit<\/a><\/li>\n\n\n\n<li><a href=\"https:\/\/github.com\/glasgowmatthew\/BitsLibrary\/commit\/3cb61713f2f61689964bc721e0b28739eb839552\">fix incorrect return type<\/a><\/li>\n\n\n\n<li><a href=\"https:\/\/github.com\/glasgowmatthew\/BitsLibrary\/commit\/f983ce1416922829705eb9a84053335388d54055\">Add GetAt\/SetAt functions<\/a><\/li>\n<\/ul>\n\n\n\n<p>Then a extend my implementation to multiple bit manipulation,\nget rid of the original single bit implementation (that&#8217;s just size=1 for the new functions),\nfix the changes, fix the changes again,\nintroduce the bit field accessors that actually do something new.<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><a href=\"https:\/\/github.com\/glasgowmatthew\/BitsLibrary\/commit\/b433da6c56c130bcb70e4b17c8fef4780eace2c3\">Add Bits::Index helper<\/a><\/li>\n\n\n\n<li><a href=\"https:\/\/github.com\/glasgowmatthew\/BitsLibrary\/commit\/7fc28bbdbbcc2cf3cae706dd1d48510aeabd3237\">Add Bits::Range helper<\/a><\/li>\n\n\n\n<li><a href=\"https:\/\/github.com\/glasgowmatthew\/BitsLibrary\/commit\/2b82f8149b8da1ea7cd02cfda68bf6391037034b\">fix Index<\/a><\/li>\n\n\n\n<li><a href=\"https:\/\/github.com\/glasgowmatthew\/BitsLibrary\/commit\/ae4712e45df324e3d529fd74c76da37de6e3c1e3\">fix Range<\/a><\/li>\n\n\n\n<li><a href=\"https:\/\/github.com\/glasgowmatthew\/BitsLibrary\/commit\/a863ad13be036ca00aafca269aece01cd37cbc99\">Use constexpr<\/a><\/li>\n<\/ul>\n\n\n\n<p>Next add the helper classes one by one and sprinkle in some <code>const<\/code> and <code>constexpr<\/code>.\nTechnically the library is complete but it&#8217;s still not as good as it can be.<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><a href=\"https:\/\/github.com\/glasgowmatthew\/BitsLibrary\/commit\/ac4749f2c3de01696ecca373f072987ff1543276\">Improve testing<\/a><\/li>\n\n\n\n<li><a href=\"https:\/\/github.com\/glasgowmatthew\/BitsLibrary\/commit\/facba48a43d25ffe5de0a0d7e831a082f92b5bb7\">Improve testing (again)<\/a><\/li>\n<\/ul>\n\n\n\n<p>I come up with a couple of ways to make the testing simpler.<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><a href=\"https:\/\/github.com\/glasgowmatthew\/BitsLibrary\/commit\/14c0e51123c46475f9e2e834bc451887235f1ee9\">Use Bits::Range as the low level calculator<\/a><\/li>\n\n\n\n<li><a href=\"https:\/\/github.com\/glasgowmatthew\/BitsLibrary\/commit\/9b7f5d367ff4e31f69c807e863ed77bd9228cd56\">Re-order file<\/a><\/li>\n\n\n\n<li><a href=\"https:\/\/github.com\/glasgowmatthew\/BitsLibrary\/commit\/b15146ce13af243dd3d1ed7cb8fdc9e87971ea40\">Revert &#8220;Re-order file&#8221;<\/a><\/li>\n\n\n\n<li><a href=\"https:\/\/github.com\/glasgowmatthew\/BitsLibrary\/commit\/0cfa59a54ced049014ca644fa543cbe89fc7bd74\">fix range as low level<\/a><\/li>\n\n\n\n<li><a href=\"https:\/\/github.com\/glasgowmatthew\/BitsLibrary\/commit\/88b1626a19b0f763cb446c464cbf4f6ec4d327d3\">Re-order file<\/a><\/li>\n\n\n\n<li><a href=\"https:\/\/github.com\/glasgowmatthew\/BitsLibrary\/commit\/e7d911d4333336654e0e1b60e7abce2c1f65564d\">fix range as low level<\/a><\/li>\n<\/ul>\n\n\n\n<p>I decide the library is simpler if based on <code>Bits::Range<\/code> because\nit caches the bit mask rather than calculate it each time.\nThat means the file makes more sense in a different order but they I notice some bugs.\nNormally I would have just dropped the re-order but I wanted to capture it for posterity.<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><a href=\"https:\/\/github.com\/glasgowmatthew\/BitsLibrary\/commit\/816a79aaace5a1651bba91f97d5cca0f58695955\">Derive Bits::Index from Range<\/a><\/li>\n\n\n\n<li><a href=\"https:\/\/github.com\/glasgowmatthew\/BitsLibrary\/commit\/59568f5e5b066222592046d333ef41b08362f8e2\">fix Use Bits::Range as the low level calculator<\/a><\/li>\n<\/ul>\n\n\n\n<p>Finally I realise there are several benefits to deriving <code>Bits::Index<\/code> from <code>Bits::Range<\/code> and\nget rid of newline that crept in somewhere.<\/p>\n\n\n\n<p>This is honest but much more complicated than I&#8217;d want to see in a history.\nLooking through it is more confusing than it needs to be.\nIt doesn&#8217;t matter that I changed some identifiers or fixed some minor bugs.\nIt would be better to just have them fixed in the history.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"just-the-highlights\">Just the highlights<\/h2>\n\n\n\n<p>In most situations it&#8217;s better to tell a\n<a href=\"https:\/\/github.com\/glasgowmatthew\/BitsLibrary\/tree\/just-the-highlights\">simpler story<\/a>.<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><a href=\"https:\/\/github.com\/glasgowmatthew\/BitsLibrary\/commit\/5b751587ee1e15fe2185329dcd40c1139eea19af\">Single bit manipulation library<\/a><\/li>\n\n\n\n<li><a href=\"https:\/\/github.com\/glasgowmatthew\/BitsLibrary\/commit\/a15cec74b6c282f49f1f1305936ced6116838fb2\">Multi-bit manipulation library<\/a><\/li>\n\n\n\n<li><a href=\"https:\/\/github.com\/glasgowmatthew\/BitsLibrary\/commit\/66175cf3bacc79b128e6e80572a5934da13dcd51\">Removing single bit operations<\/a><\/li>\n\n\n\n<li><a href=\"https:\/\/github.com\/glasgowmatthew\/BitsLibrary\/commit\/94375b02fe593c5779ab40d2573c56700fce4d25\">Add GetAt\/SetAt functions<\/a><\/li>\n\n\n\n<li><a href=\"https:\/\/github.com\/glasgowmatthew\/BitsLibrary\/commit\/5a2cf9a342f7ea0240d4a678965f835345426d1d\">Add Bits::Index helper<\/a><\/li>\n\n\n\n<li><a href=\"https:\/\/github.com\/glasgowmatthew\/BitsLibrary\/commit\/f894c01385a72f746a1c20a0b8af98d694797a78\">Add Bits::Range helper<\/a><\/li>\n\n\n\n<li><a href=\"https:\/\/github.com\/glasgowmatthew\/BitsLibrary\/commit\/c058b250dd2dbd231433abd68e8826ccbddac4de\">Use constexpr<\/a><\/li>\n\n\n\n<li><a href=\"https:\/\/github.com\/glasgowmatthew\/BitsLibrary\/commit\/7028bcdb8a45a947ac19040c3deede8a4008212e\">Improve testing<\/a><\/li>\n\n\n\n<li><a href=\"https:\/\/github.com\/glasgowmatthew\/BitsLibrary\/commit\/16b003378997ece70829169357e84ca98a241e9e\">Improve testing (again)<\/a><\/li>\n\n\n\n<li><a href=\"https:\/\/github.com\/glasgowmatthew\/BitsLibrary\/commit\/21f3f2ce1defe8669964ec6c4abb64964f9d4be1\">Use Bits::Range as the low level calculator<\/a><\/li>\n\n\n\n<li><a href=\"https:\/\/github.com\/glasgowmatthew\/BitsLibrary\/commit\/f0cb3a3b6e91ecb75c4a8638e5eaa5ca3e7d5017\">Re-order file<\/a><\/li>\n\n\n\n<li><a href=\"https:\/\/github.com\/glasgowmatthew\/BitsLibrary\/commit\/847c7684d51f9a5f233e198a8631c0056b57512e\">Derive Bits::Index from Range<\/a><\/li>\n<\/ul>\n\n\n\n<p>This is more what I&#8217;d want to see.\nYou can see the stages that I went through without getting lost in the details.\nHowever there is still more back and forth than is really needed.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"a-new-story\">A new story<\/h2>\n\n\n\n<p>Telling a <a href=\"https:\/\/github.com\/glasgowmatthew\/BitsLibrary\/tree\/a-new-story\">new story<\/a>\ncan dramatically simplify things for later readers.<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><a href=\"https:\/\/github.com\/glasgowmatthew\/BitsLibrary\/commit\/66d84d5643412411a6a9eb5a7e673eb01bb2ae54\">Single bit manipulation library<\/a><\/li>\n\n\n\n<li><a href=\"https:\/\/github.com\/glasgowmatthew\/BitsLibrary\/commit\/fde027c95afe406b73d43e38112937808ca95831\">Multi-bit manipulation library<\/a><\/li>\n\n\n\n<li><a href=\"https:\/\/github.com\/glasgowmatthew\/BitsLibrary\/commit\/047666e4420e0a1fe66fdc3021b46f395fd9baac\">Add helper classes<\/a><\/li>\n\n\n\n<li><a href=\"https:\/\/github.com\/glasgowmatthew\/BitsLibrary\/commit\/54ccaae64324806600ed328b0e423a19b6fd6869\">Use Bits::Range as the low level calculator<\/a><\/li>\n\n\n\n<li><a href=\"https:\/\/github.com\/glasgowmatthew\/BitsLibrary\/commit\/b4ef838eab35f9aa04e452cb053282565d0fd5c2\">Re-order file<\/a><\/li>\n<\/ul>\n\n\n\n<p>These commits don&#8217;t match up neatly to my original ones.\nThe improved testing is used from the start, as is <code>constexpr<\/code>.\n<code>Bits::Index<\/code> is derived from <code>Bits::Range<\/code> as soon as the helpers are added.\nIt tells a simple story of starting with functions for single and then multiple bits then\nadding helper classes and finally using those classes as a foundation.<\/p>\n\n\n\n<p>Note that I take a full commit just to re-order the file rather than combine that with something else.\nRe-ordering a file or swapping things between files can make a history very confusing.\nIt&#8217;s often best to make these moves by themselves.<\/p>\n\n\n\n<p>Given the setup described in <a href=\"https:\/\/permutationcity.co.uk\/bp\/2024\/07\/23\/iterative-development\/\">Iterative development<\/a> it may be unrealistic to get something this simple but different situations will allow different stories. I could have decided to take the library further. It only deals with continuous bit ranges but<br>a <code>Bits::Mask<\/code> class would easily allow non-contiguous bit ranges. I have to stop somewhere though.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"just-the-destination\">Just the destination<\/h2>\n\n\n\n<p>In the limit your story could be\n<a href=\"https:\/\/github.com\/glasgowmatthew\/BitsLibrary\/tree\/just-the-destination\">just the destination<\/a>.<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><a href=\"https:\/\/github.com\/glasgowmatthew\/BitsLibrary\/compare\/main...just-the-destination\">Add bit manipulation library<\/a><\/li>\n<\/ul>\n\n\n\n<p>For this simple library that&#8217;s probably okay.\nThe <code>Bit::Range<\/code> is as easy to understand as the initial functions.\nI wouldn&#8217;t recommend it for anything complicated.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"a-story-takes-time\">A story takes time<\/h2>\n\n\n\n<p>Checking in your full journey doesn&#8217;t take you any time but\ncrafting a new story certainly does, why bother?\nI think the benefit is for the code reviewers and developers who look back on it, including future you.<\/p>\n\n\n\n<p>Doing a proper code review can be hard work. You may not completely understand what the original code does. You have to try and understand what the changes are doing and whether they are correct. Is that refactored code really doing the same thing as the original? Are they using the library correctly? Does the algorithm do what they think it does? It&#8217;s much easier to do all this if you&#8217;re just seeing the highlights or have a clear story to follow. For this example it&#8217;s possible to understand just the destination. However with a complicated change I don&#8217;t think it&#8217;s possible <em>properly<\/em> review all the changes in one go. You can certainly look at a bunch of changes all at once but you can&#8217;t understand them as well.<\/p>\n\n\n\n<p>So this is an exchange of time.\nSome extra time in order to set up a good story but less time to do the review and\nless time for anyone inspecting the history later.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"in-the-end\">In the end<\/h2>\n\n\n\n<p>I&#8217;ve found it worthwhile to tell good stories.\nI know that I want to be able to look back at code histories 6 months from now or 6 years from now.<\/p>\n\n\n\n<p>I have changed tools recently and am finding it harder to do this. I had been using <a href=\"https:\/\/www.sourcetreeapp.com\/\">Sourcetree<\/a> for MacOS for several years. Recently I have been using&#8230; Sourcetree for Windows but involving <a href=\"https:\/\/learn.microsoft.com\/en-us\/windows\/wsl\/\">Windows Subsystem for Linux<\/a> and it&#8217;s slow, so slow I can&#8217;t reliably edit my history. I think the problem is something to do with how file caching works for WSL. So a lot more has to be done <a href=\"https:\/\/git-scm.com\/book\/en\/v2\/Getting-Started-The-Command-Line\">directly on the command line<\/a>. It&#8217;s just not as good as being able to edit the history directly with a visual tool.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>I&#8217;ve been thinking about writing this one for a while, actually longer than that. I really needed an example to talk about. Fortunately I wrote some code recently. This is about code changes, how they made and how to present them. I&#8217;m going to talk about code changes as having a few different parts: The [&hellip;]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_import_markdown_pro_load_document_selector":0,"_import_markdown_pro_submit_text_textarea":"","footnotes":""},"categories":[1],"tags":[17],"class_list":["post-269","post","type-post","status-publish","format-standard","hentry","category-general","tag-organisation"],"_links":{"self":[{"href":"https:\/\/permutationcity.co.uk\/bp\/wp-json\/wp\/v2\/posts\/269","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/permutationcity.co.uk\/bp\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/permutationcity.co.uk\/bp\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/permutationcity.co.uk\/bp\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/permutationcity.co.uk\/bp\/wp-json\/wp\/v2\/comments?post=269"}],"version-history":[{"count":2,"href":"https:\/\/permutationcity.co.uk\/bp\/wp-json\/wp\/v2\/posts\/269\/revisions"}],"predecessor-version":[{"id":302,"href":"https:\/\/permutationcity.co.uk\/bp\/wp-json\/wp\/v2\/posts\/269\/revisions\/302"}],"wp:attachment":[{"href":"https:\/\/permutationcity.co.uk\/bp\/wp-json\/wp\/v2\/media?parent=269"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/permutationcity.co.uk\/bp\/wp-json\/wp\/v2\/categories?post=269"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/permutationcity.co.uk\/bp\/wp-json\/wp\/v2\/tags?post=269"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}