Lessons Learned

by Richard Taylor : 2019-01-28

In no particular order.

• Resist the urge to over-engineer

  Even though I knew I only wanted a few features from this program, it was hard to not design and implement it as if I might need to extend it massively in the future.

  That's what you get from years of working on code that needed extending but was not extendable.

  So many of my personal projects never get finished because they never get complete enough to be useful... whilst potentially being very extendable.

  To force myself to keep the design compact I decided to put all the classes into a single file. That way my desire to keep the file small enough to read offset my desire to abstract things too much.

• Unit tests always pay for themselves

  Not a lesson I learned here for the first time, but worth repeating over and over again. Even a small piece of code like this benefits from having unit tests. And if I do need to extend and refactor in future, or even just remember how this is supposed to work, it will be so much easier.

  Part of the not over-engineering was a decision to use regexes rather than a full HTML parser to extract and insert into documents. That is easier to justify (to yourself at least) if you have tests that show the cases you have covered.

• Write some docs for yourself

  I knocked up this documentation as a demo of the code I was writing. But actually on reflection I found it really useful to clarify what I had done and why. I think even if I had never published it to the web it would still have been worth writing.

  Often I just make notes in a text file alongside the code. But I think in future I will write something a bit more substantial, even if just for myself.

• Resist the urge to over-style the content

  One of the motivations for writing content directly in HTML was to avoid all the cookies, tracking pixels, bloated JavaScript and adverts that are included by other tools (or may be included in the future).

  A potential drawback with this level of control is the abilty to spend forever tweaking style sheets to get exactly what you want. This takes some effort to resist.

  Particularly, since many of these threads are about code of some kind, I was very tempted to apply complex styling to the code elements. There are many JavaScript libraries to do this. But ultimately I don't think it is good for content to style down to that level. How a reader prefers to see code "coloured" is down to their preference. It is the writer's job to markup the content clearly and the browsers job to display it as the user requires.

  At the end of the day, content is more important than styling IMO.