The following is part of a larger series discussing the ongoing development of PoliTree, an attempted political-compass killer which has been way too long in the making. To find out more, visit the introduction.
November likely marks the most significant milestone this project has seen in years. The new target is to finish this by mid-2024. The site’s code redesign is very much underway, I finally have a confident understanding of web development, and I have the structure of the codebase for the site entirely planned out.
Below you can see the site in both its desktop and mobile variants:
A top priority for this redesign is making the codebase as clean as possible, and the development workflow as organized as possible. I’ve learned this the hard way multiple times through this project and I am determined to not make the same mistakes.
The following are my guidelines for coding this site:
- Any code written or solution should fully be understood first. If you’re using templates or StackOverflow code, first be able to fully explain everything in it and weigh it against alternative options.
- JS/HTML/CSS should be kept as separate as possible. This goes for tools/languages in general.
- The developer toolchain should be as minimal as possible to minimize the amount of tools one will have to be familiar with and to minimize unexpected interactions. (This can be compromised depending on how much complexity is added, and how messy any workaround would be.)
- Take extensive notes, which can later be transformed into extensive documentation. Any issues or roadblocks should immediately be filed as an issue on Codeberg to assist with keeping track of issues and make offloading tasks easier. Any progress made towards these issues, and any resources/links found in the troubleshooting/research process should also be detailed in the issue threads.
- Modularize, modularize, modularize. Do not put all the JS into one file. Break down files/folders by type, function, and front-end/back-end. Each file should do one thing and do it well.
- When first developing components/a section of logic, first try to develop it in a separate environment from the project and then integrate it after you’ve finished developing it.
- Avoid hardcoding wherever possible. If you have a repeating HTML component, dynamically generate it from a module. Test information should be loaded from JSON modules, not written directly onto the HTML.
- Do not architect on the fly. Layouts should first be sketched/wireframed before jumping into development. Start with a holistic understanding of the site and how it should navigate before jumping into designing pages. Plan out your codebase, have an idea of what components are needed and how they’ll interact even if you don’t yet know how to actually implement them.
We started by trying to repurpose a Pure.CSS template, but with that we ran into a bunch of issues, so I took to breaking the template down into grids on paper, and then just reimplementing it from scratch. This did a ton to reduce the uncertainty factor, and allowed me to fully understand the layout I was working with. The structure of the template was a single main page consisting of head, body and footer. Everything was designed Navigation involves replacing the contents of the body as opposed to switching to a different HTML file.
To implement the navigation logic, I made use of JS modularization. Each “page” was an HTML snippet of the relevant comments, put into a JS file, which was then imported into the main navigation file. The main navigation file has one function for each page, each of which gets called by the forward/back buttons. Each rendered page contains pointers to the pages forward/back relative to it, similar to a linked list.
Each section of logic gets its own JS module. There’s a clear front-end/back-end separation, with the back-end routing to the front-end in terms of the component rendering.
Each JSON element also gets treated as a module. There’s some incredibly screwy stuff with how JS handles JSON imports so this still has to be fully worked out.
The plan is to make use of HTML5 SessionStorage in order to store and operate on the various variables generated by user input during the test. Separate testing has been done with this, there should be no problems integrating this.
The developer toolchain currently makes use of just Lighttpd and Sass.
- Lighttpd is necessary as modularization will violate CORS Policy on most browsers if you do not run it on a server. This isn’t an issue in production, but for development, you need a local server to actually see any of the JS. Lighttpd was picked because it’s incredibly lightweight and incredibly easy to set up.
- Sass is used because it has support for both variables and CSS modularization. In addition to helping to organize the CSS, it also will make adding themeing support in the future much cleaner.
I am currently undecided on whether or not to make use of a bundler to resolve the JSON problem.
Evangelical Christian, Marxist, and a bit of a Luddite. I run this blog as a way to compile my various theories and arguments spanning a wide variety of subjects from technology to politics.