Summary Of Edits made on May 15th, 2023
- Pug is Jade… lol
- updated with more examples of well established projects that solve the same problems Pug does, without indention.
- Gave more explicit advice in the end of the article
A stroll down memory lane
To my horror; I just stumbled upon pug. It brought me back to one of my contracting jobs when I was pretty new to developing. I had just really figured out HTTP and how web applications work on a fundamental level. I was quite proficient in JavaScript/CSS and this is what I was hired for. The only problem was the application used jade. As you may note, it hasn’t had a release in over 5 years, because its a shit idea IS pug. The cancerous indention based template engine has just rebranded. I chuckled when i found this out.
In hindsight, this was part of the reason why I failed in this contract and ended up losing this client. I was too stubborn and inexperienced to realize jade was a major impediment for me. I trusted a more experience developer was using it for a reason – he even asked me at one point if I liked it. I didn’t but told him I did. I hated working on this project and wasn’t working enough hours to meet expectations.
Why is pug a shit idea
HTML/css are finicky at baseline. Adding a layer of abstraction to make a pretty document is not worth it in any way. One of the polarizing topics regarding python is its code block indentation style. Personally, I am indifferent to this… FOR A PROGRAMMING LANGUAGE. The use of indentation based blocks for a markup language is absolutely insane.
Do Not Invent Here.
It buys you very little (a subjectively “pretty” markup document), adds uneeded complexity, diverges from convention and by and large solves nothing new. There are tons of valid template engines that address all of the issues with writing markup. The purpose of these systems is to keep your markup dry and organize your markup in ways that are easy to maintain. These indention based template engines address the former but absolutely drops the ball on the later.
- It is not as explicit as a XML based template engine. This will inevitably lead to mistakes as your documents grow and become more complex. I agree that XML is ugly and things like config or editing end-user generating content are better done in yaml style. Yaml isn’t a markup language, its “a human readable serialization language”.
- Defying a defacto convention for a web based markup (XML) is a really bad idea. This adds a literal barrier to entry for contributing to your project. This nullifies the ability to quickly copy/paste demo components for rapid iterative development – you now have to translate it into PUG.
What about end-user content?
In the case where you would need human readable documents that are serialized into valid HTML… use markdown or kramdown. They are really… really good. I’m writing this post in markdown. My clients are delivered websites they can edit in markdown. The template engine is liquid.
Especially true for learning
The reason I fell into the indentation based markup trap is because I was in a gullible phase as a developer where I didn’t know any better. I had just learned python and enjoyed it as a backend language so i figured, “Why not?!”. Sometimes there are standards for a reason. Any and all effort I spent wrestling with indentation based HTML was a complete waste; never used it again and never will.
For those trying to learn, these traps are everywhere. There are endless tools and bells and whistles for every language. Many… many useless projects are out there selling you a solution you don’t want. If you are trying to learn it is imperative that you have good foundational knowledge of how these tools work so you can judge if they are innovative enough to adopt.
How deep should I dive?
That’s entirely subjective and very personal. I’d say in general you will benefit from learning everything you can from how compilers work to high level things like changing the font on your website. Not everyone has the time or drive. Balancing learning with productivity is important to gauge on your own.
For a new developer I’d say just start with a deep dive through the source code / documentation of the tools, frameworks or libraries you use that are relevant to a skillset you are trying to acquire. You wont understand any of it at first, but as you explore you will start to. Balance this with actual productivity and you will flourish.
When to use a thing?
I’ve notice new developers tend to be on the bleeding edge of adopting technology. Which is fine as long as they make sure to learn the underlying technology. Sometimes those projects end up being the new standard, oftentimes they don’t. I picked moojs over jQuery in 07; this would have been a really big deal if I hadn’t focused on the fundamentals of JavaScript. In fact, this focus on core JavaScript concepts has been paramount in me adapting to the ever changing landscape of web development.
Again, very subjective and dependent on your specific goals and ability. As a crafty vetern; I’m a minimalist. I get super annoyed when other people’s code breaks my code. I am hyper critical of importing anything that’s not a defacto standard that is actively being maintained. If I cannot read and understand what your code does I will not be using it. If the code doesn’t work exactly how I want it to I will fork it without hesitation and commit to manually pulling upstream commits.
This will be a very different strategy than a novice developer should employ. Import ALL the things; just know you’re importing other people’s problems. You may have to dive in there and get your hands on some source code. Know that any time reading code or learning fundamentals of how something works will not be a waste… unless you picked perl then you’re screwed.