{"version":"https://jsonfeed.org/version/1","title":"Aaron Gustafson: Content tagged software development","description":"The latest 20 posts and links tagged software development.","home_page_url":"https://www.aaron-gustafson.com","feed_url":"https://www.aaron-gustafson.com/feeds/software-development.json","author":{"name":"Aaron Gustafson","url":"https://www.aaron-gustafson.com"},"icon":"https://www.aaron-gustafson.com/i/og-logo.png","favicon":"https://www.aaron-gustafson.com/favicon.png","expired":false,"items":[{"id":"https://www.aaron-gustafson.com/notebook/optimizing-your-codebase-for-ai-coding-agents/","title":"✍🏻 Optimizing Your Codebase for AI Coding Agents","summary":"By looking at how a model reasons over a codebase to solve tasks, I found ways to help it — as well as the human engineers working in the same project — reduce wasted time.","content_html":"<p>I’ve been playing around a bit with GitHub Copilot as an autonomous agent to help with software development. The results have been mixed, but positive overall. I made an interesting discovery when I took the time to read through the agent’s reasoning over a particular task. I thought the task was straightforward, but I was wrong. Watching the agent work was like watching someone try to navigate an unfamiliar room, in complete darkness, with furniture and Lego bricks scattered everywhere.</p>\n<p>The good news? Most of the issues weren’t actually <em>code</em> problems; they were organizational and documentation problems. The kinds of problems that make tasks hard for humans too.</p>\n<p>As I watched the agent struggle, I realized that optimizing for AI agents is really just about removing ambiguity and making implicit knowledge explicit. In other words: it’s just good engineering.</p>\n<h2 id=\"what-did-i-learn%3F\" tabindex=\"-1\"><a class=\"header-anchor\" href=\"#what-did-i-learn%3F\" aria-hidden=\"true\">#</a> What did I learn?</h2>\n<p>After reviewing the agent’s execution logs (which read like a stream-of-consciousness diary of confusion), several patterns emerged:</p>\n<h3 id=\"1.-documentation-sprawl-is-an-efficiency-killer\" tabindex=\"-1\"><a class=\"header-anchor\" href=\"#1.-documentation-sprawl-is-an-efficiency-killer\" aria-hidden=\"true\">#</a> 1. <strong>Documentation sprawl is an efficiency killer</strong></h3>\n<p>The agent spent roughly 40% of its time just trying to figure out which documentation to trust. We had instructions in workflow comments, the README, task specific instructions, and more. In other words, we had no clear source of truth. Pieces of that truth were scattered across multiple files and the docs were inconsistent and — in some cases — contradictory.</p>\n<p>Sound familiar? It’s the equivalent of having five different “getting started” guides that all got written at different times by different people and nobody bothered to consolidate them. (If you’ve ever worked on a project that’s been around for more than a year with no one in charge of documentation, you know exactly what I’m talking about.)</p>\n<p><strong>The fix:</strong> Establish a single source of truth. Ruthlessly. We consolidated everything into one comprehensive guide and updated all references to point <em>only</em> there. Deprecated docs were deleted and/or redirected, as appropriate. No more choose your own adventure. No more guessing.</p>\n<h3 id=\"2.-agents-won%E2%80%99t-optimize-themselves\" tabindex=\"-1\"><a class=\"header-anchor\" href=\"#2.-agents-won%E2%80%99t-optimize-themselves\" aria-hidden=\"true\">#</a> 2. <strong>Agents won’t optimize themselves</strong></h3>\n<p>Here’s a fun one: the agent ran several full production builds—complete with image processing, template compilation… the whole shebang—just to validate a markdown file was in the right format. These builds took 30-60 seconds. <em>Each time.</em></p>\n<p>This is like requiring someone to assemble an entire car just to check if the owner’s guide is displaying the right “check engine” symbol. Technically it works, but yikes.</p>\n<p><strong>The fix:</strong> Write fast, focused validation scripts. One tool for each job. Tell the agent what the utility is, where to find it, and how to use it. Give it explicit instructions to use utility scripts in lieu of full site builds whenever possible.</p>\n<h3 id=\"3.-ambiguity-breeds-confusion-(and-wasted-tokens)\" tabindex=\"-1\"><a class=\"header-anchor\" href=\"#3.-ambiguity-breeds-confusion-(and-wasted-tokens)\" aria-hidden=\"true\">#</a> 3. <strong>Ambiguity breeds confusion (and wasted tokens)</strong></h3>\n<p>The agent spent 15+ minutes having an internal philosophical debate about whether to process test data. Should it reject it? Accept it? Create a placeholder? The instructions didn’t say, so the agent did what any of us would do: it agonized — or at least feigned agonizing — over the decision and tried to infer intent from context clues.</p>\n<p><strong>The fix:</strong> Be explicit about edge cases. We added a dedicated section for handling test form submissions. No more guessing.</p>\n<h2 id=\"there%E2%80%99s-a-pattern-here\" tabindex=\"-1\"><a class=\"header-anchor\" href=\"#there%E2%80%99s-a-pattern-here\" aria-hidden=\"true\">#</a> There’s a pattern here</h2>\n<p>If you squint, all of these issues share a common root cause: <strong>implicit assumptions</strong>.</p>\n<p>We assumed humans would know to check one doc instead of five. We assumed the difference between validation and building was obvious. We assumed everyone would understand how to handle edge cases.</p>\n<p>AI agents don‘t — can’t? — make those assumptions. They need explicit instructions, clear boundaries, and unambiguous inputs. Honestly? So do humans. We’re just better at muddling through — or think we are.</p>\n<h2 id=\"early-results\" tabindex=\"-1\"><a class=\"header-anchor\" href=\"#early-results\" aria-hidden=\"true\">#</a> Early results</h2>\n<p>After implementing these changes, we expect (and early testing confirms):</p>\n<ul>\n<li>~40% reduction in processing time,</li>\n<li>~75% reduction in token usage, and</li>\n<li>&gt;80% reduction in confusion and circular reasoning.</li>\n</ul>\n<p>But here’s the thing: these improvements don’t just help the AI agent. They help <em>everyone</em>. The consolidated documentation is easier to navigate. The fast validation scripts are useful for humans too. The explicit edge case handling prevents future questions.</p>\n<h2 id=\"the-key-to-reducing-toil%3A-excellent-docs-and-tools\" tabindex=\"-1\"><a class=\"header-anchor\" href=\"#the-key-to-reducing-toil%3A-excellent-docs-and-tools\" aria-hidden=\"true\">#</a> The key to reducing toil: excellent docs and tools</h2>\n<p>Optimizing for AI agents isn’t really about AI. It’s about removing ambiguity, eliminating redundancy, and making implicit knowledge explicit. It’s about writing code and documentation that doesn’t require a deep understanding of the project to comprehend.</p>\n<p>In other words: it’s just good engineering.</p>\n<p>So if you’re working with AI coding agents — or planning to — invest in your docs and tooling. Don’t think of it as wasted time “writing for robots.” Think of it as paying down documentation debt and building an efficient engineering process.</p>\n<p>Your future self, your teammates, and the bots will thank you.</p>\n<h2 id=\"afterword\" tabindex=\"-1\"><a class=\"header-anchor\" href=\"#afterword\" aria-hidden=\"true\">#</a> Afterword</h2>\n<p>Interestingly, an AI agent was a particularly useful partner in finding and addressing the technical debt we’d been living with. Sometimes you need a pedantic robot to point out that your house is a mess.</p>\n","url":"https://www.aaron-gustafson.com/notebook/optimizing-your-codebase-for-ai-coding-agents/","tags":["AI/ML","software development"],"image":"https://www.aaron-gustafson.com/i/posts/2025-10-21/hero.jpg","date_published":"2025-10-21T22:11:32Z"},{"id":"https://www.aaron-gustafson.com/notebook/links/google-bard-ai-chatbot-raises-ethical-concerns-from-employees/","title":"🔗 Google Bard AI Chatbot Raises Ethical Concerns From Employees","content_html":"<p>Why do companies release software before it’s safe? Chances are they actually consider their product to be their stock price rather than their software… yet another victim of the financialization of our economy.</p>\n<blockquote>\n<p>One worker’s conclusion: Bard was “a pathological liar,” according to screenshots of the internal discussion. Another called it “cringe-worthy.” One employee wrote that when they asked Bard suggestions for how to land a plane, it regularly gave advice that would lead to a crash; another said it gave answers on scuba diving “which would likely result in serious injury or death.”</p>\n<p>Google launched Bard anyway. The trusted internet-search giant is providing low-quality information in a race to keep up with the competition, while giving less priority to its ethical commitments, according to 18 current and former workers at the company and internal documentation reviewed by Bloomberg. The Alphabet Inc.-owned company had pledged in 2021 to double its team studying the ethics of artificial intelligence and to pour more resources into assessing the technology’s potential harms. But the November 2022 debut of rival OpenAI’s popular chatbot sent Google scrambling to weave generative AI into all its most important products in a matter of months.</p>\n</blockquote>\n","social_text":"When you consider your product to be your stock price rather than your software…","url":"https://www.aaron-gustafson.com/notebook/links/google-bard-ai-chatbot-raises-ethical-concerns-from-employees/","external_url":"https://www.bloomberg.com/news/features/2023-04-19/google-bard-ai-chatbot-raises-ethical-concerns-from-employees?leadSource=uverify%20wall","tags":["AI/ML","software development"],"image":"https://assets.bwbx.io/images/users/iqjWHBFdfxIU/i827R1A0F_Wg/v1/1200x800.jpg","date_published":"2023-04-19T15:56:40Z"},{"id":"https://www.aaron-gustafson.com/notebook/links/from-gaming-with-your-eyes-to-coding-with-ai-new-frontiers-for-accessibility/","title":"🔗 From gaming with your eyes to coding with AI: New frontiers for accessibility","content_html":"<p>I love everything about this piece showcasing how people with disabilities are using open source to empower themselves and others.</p>\n","social_text":"I love everything about this piece showcasing how people with disabilities are using open source to empower themselves and others.","url":"https://www.aaron-gustafson.com/notebook/links/from-gaming-with-your-eyes-to-coding-with-ai-new-frontiers-for-accessibility/","external_url":"https://github.com/readme/featured/open-source-accessibility","tags":["accessibility","software development"],"date_published":"2023-03-14T23:23:31Z"},{"id":"https://www.aaron-gustafson.com/notebook/thoughts-on-the-proposed-websites-and-software-applications-accessibility-act/","title":"✍🏻 Thoughts on the proposed Websites and Software Applications Accessibility Act","summary":"Senator Duckworth and Representative Sarbanes introduced the WSAAA to explicitly bring websites—and other forms of digital media that didn’t exist when the ADA was signed into law—into the purview of the Americans with Disabilities Act (ADA).","content_html":"<p>Last month, Senator Tammy Duckworth (D-Ill.) and Representative John P. Sarbanes (D-Md.) introduced the Websites and Software Applications Accessibility Act—I’m gonna call it the WS3A for short—simultaneously in the U.S. Senate (<a href=\"https://www.congress.gov/bill/117th-congress/senate-bill/4998\">S. 4998</a>) and House of Representatives (<a href=\"https://www.congress.gov/bill/117th-congress/house-bill/9021\">H.R. 9021</a>) to explicitly bring websites—and other forms of digital media that didn’t exist when the ADA was signed into law—into the purview of the Americans with Disabilities Act (ADA). I am definitely in favor of this effort as it removes the ambiguity that currently exists in U.S. law as to whether websites are governed by the ADA. The WS3A is a reasonable framework, but there is still a lot of work to be done when it (hopefully) passes.</p>\n<p>On reading <a href=\"https://www.duckworth.senate.gov/imo/media/doc/22.09.28%20-%20Websites%20and%20Software%20Applications%20Accessibility%20Act%20BILL%20TEXT%20FINAL1.pdf\">the text of the WS3A</a>, I really appreciated the thought they put into the way it’s structured. In a nutshell, it</p>\n<ol>\n<li>Affirms that the (ADA) prohibits discrimination against people with disabilities in their use of websites.</li>\n<li>Tasks the Department of Justice (DOJ) and the Equal Employment Opportunity Commission (EEOC) with establishing, updating, and enforcing accessibility standards for websites and applications.</li>\n<li>Sets up a committee to work with these government offices to establish the rules that govern digital accessibility. It also establishes a central repository (and governing committee) to provide guidance on how to achieve compliance. Both committees must include representatives from numerous named disability communities as well as digital accessibility experts.</li>\n<li>Identifies who needs to abide by these standards (e.g., the government, employers, commercial entities).</li>\n<li>Establishes the legal grounding for litigation (from both the government and citizens) of violations of the established standards.</li>\n</ol>\n<p>There’s more to it than that, but it’s a reasonable summary. I suggest reading <a href=\"https://www.duckworth.senate.gov/imo/media/doc/22.09.27%20SxS%20-%20Websites%20and%20Software%20Applications%20Accessibility%20Act%20FINAL.pdf\">Senator Duckworth’s summary doc</a> for more detail as well.</p>\n<h2 id=\"we-don%E2%80%99t-all-need-%E2%80%9Cthe-same%E2%80%9D-experience\" tabindex=\"-1\"><a class=\"header-anchor\" href=\"#we-don%E2%80%99t-all-need-%E2%80%9Cthe-same%E2%80%9D-experience\" aria-hidden=\"true\">#</a> We don’t all need “the same” experience</h2>\n<p>In Section 3 of the WS3A, a part of the definition for “accessibility” is the requirement for people with disabilities to be able “to engage in the same interactions as” people without disabilities. This sounds good on first blush, but I think “the same” could be misleading.</p>\n<p>A number of years back, I was consulting with a financial services firm. Their web team was quite interested in putting accessibility into practice on their website after spending a few days talking about it with me. When I circled back a few months later, things weren’t going so well. The team that was focused on accessibility was two sprints behind “because of accessibility” and management was ready to give up on it. And so I asked them to walk me through what was going on.</p>\n<p>The problem was an interactive graph they had built for a page in their company’s marketing site. It allowed users to see how much they’d save in fees over a certain number of years based on an initial investment amount that could be adjusted via a slider control. The slider allowed the initial investment amount to range from a low of $5,000 to something like $5,000,000 in increments of $5,000. They had run into all sorts of delays in getting the slider to work <em>identically</em> for people using either a mouse (the default they’d considered) or a keyboard.</p>\n<p>After getting the details, I had them take a step back and look at the big picture. I asked them to consider the goal of the interface: to help people understand the more they invest with this company, the more they will save in fees. Then I asked them if the keyboard experience of that slider was a good one. It wasn’t; no one is going to move the slider potentially several hundred times to get to the exact amount they’re considering investing, nor should they have to. So I asked them to reconsider their approach and come up with other ways to achieve the goal. After all, this was for a marketing site; they weren’t displaying someone’s actual account information, where they would need to be more exacting in their approach.</p>\n<p>They realized the same goal could be achieved in two ways. First, they could ensure the copy that came before the visualization offered the same information in textual form. Second, they could simplify the slider interface to have a set number of stops for keyboard users, to give users a sense of how things would change, but without making the interface tedious to use. These were both excellent alternatives and provided a better, some might say <em>more</em> accessible experience for folks who relied on a keyboard to both navigate and interact with he web.</p>\n<p>When it comes to accessibility, it’s easy to get hung up while trying to provide an <em>identical</em> experience when that isn’t always the best thing. Everyone should be granted the opportunity to accomplish the core goal of an interface, but they don’t necessarily need to do it in the same way. If we get too caught up in providing the same experience, it’s easy to miss out on providing the right experience.</p>\n<p>So, in reflecting on the WS3A’s definition of accessibility, I would prefer to see a little more nuance. I did notice that later, in the Rulemaking section, they use the phrase “equally effective experiences for users with disabilities and users without disabilities.” That’s a much better goal here. The same opportunities need to exist; parity is important, but not everyone requires the same accommodations.</p>\n<p>This applies in other contexts too. For example, some images are informational, others are decorative; strict reading of a requirement for “the same” experience might lead folks to believe all images require descriptions, which they don’t. Similarly, users need to have control over how they receive information. They need to be able to adjust font sizes, stop things form moving around on the screen, change the colors of the interface to improve readability, eliminate distractions, and so on. We need to be building interfaces that can <em>adapt</em> to serve our users’ individualized needs across a wide range of intersections encompassing their own capabilities and disabilities as well as those of their device, their network, and the influence of their environment. (Insert shameless plug for <a href=\"https://adaptivewebdesign.info/\">my book</a> here.)</p>\n<h2 id=\"we-need-to-better-define-an-%E2%80%9Cundue-burden%E2%80%9D\" tabindex=\"-1\"><a class=\"header-anchor\" href=\"#we-need-to-better-define-an-%E2%80%9Cundue-burden%E2%80%9D\" aria-hidden=\"true\">#</a> We need to better-define an “undue burden”</h2>\n<p>The WS3A provides two pathways for an entity to side-step their obligations under the ADA. One seems pretty reasonable: if compliance would “fundamentally alter the nature” of the entity’s offerings, they can be excused from having to comply. The other reason creates a huge loophole, however: if compliance would “impose an undue burden” on the entity in violation.</p>\n<p>What exactly is an “undue burden”? <a href=\"https://www.ada.gov/reachingout/l2factors.html\">According to the ADA</a>, it means “significant difficulty or expense,” which is determined in consideration of:</p>\n<blockquote>\n<ol>\n<li>The nature and cost of the action needed under this part;</li>\n<li>The overall financial resources of the site or sites involved in the action; the number of persons employed at the site; the effect on expenses and resources; legitimate safety requirements that are necessary for safe operation, including crime prevention measures; or the impact otherwise of the action upon the operation of the site;</li>\n<li>The geographic separateness, and the administrative or fiscal relationship of the site or sites in question to any parent corporation or entity;</li>\n<li>If applicable, the overall financial resources of any parent corporation or entity; the overall size of the parent corporation or entity with respect to the number of its employees; the number, type, and location of its facilities; and</li>\n<li>If applicable, the type of operation or operations of any parent corporation or entity, including the composition, structure, and functions of the workforce of the parent corporation or entity.</li>\n</ol>\n</blockquote>\n<p>The exact math is not exactly clear-cut—especially when we’re talking about digital products as opposed to physical structures—and I could see a number of corporations declaring something an “undue burden” when, in fact, it is relatively easy to address. It would be nice to see some guidance around what is considered to be a regular “cost of doing accessible business” in terms of percentage of operating revenue or percentage of staff dedicated to identifying and remediating accessibility issues.</p>\n<h2 id=\"other-things-i-hope-to-see-addressed\" tabindex=\"-1\"><a class=\"header-anchor\" href=\"#other-things-i-hope-to-see-addressed\" aria-hidden=\"true\">#</a> Other things I hope to see addressed</h2>\n<p>Below are a some additional questions and thoughts I think the commissions operating under the WS3A should seek to address:</p>\n<ul>\n<li><strong>If we agree accessibility is a journey, not a destination (i.e., we’re never “done”), how can we declare something is “accessible” (or not)?</strong> It feels like the <a href=\"https://www.w3.org/WAI/standards-guidelines/wcag/\">Web Content Accessibility Guidelines (WCAG)</a> offer some solid guidance and that will likely set the bar for this effort, especially given that <a href=\"https://www.section508.gov/\">Section 508 of the Rehabilitation Act</a> relies on that set of guidelines as well. I’m encouraged by their recognition that what’s needed is ongoing evaluation of the guidance as well, but it still presents challenges around how we define “accessible enough.” Additionally, digital products are different because they are easily changed, updated, and improved (as opposed to, say, a giant set of concrete stairs).</li>\n<li><strong>We don’t really have clarity around the mechanisms for informing non-compliant entities of their violations.</strong> It’s also unclear as to whether there is a reasonable grace period for them to remediate the issue and report back for validation. Having a grace period to address issues will also be key for heading litigation trolls off at the pass.</li>\n<li><strong>We need some guidance around how much of a disruption is grounds for a formal complaint.</strong> Many organizations ship code pretty much constantly and may introduce an accessibility bug and then address it within a few minutes, hours, or days. Again, a grace period starting when the entity is made aware of the violation would be key for addressing this.</li>\n<li><strong>Third-party code is not addressed at all in the WS3A.</strong> Whose responsibility is it? A huge percentage of the web (and other software projects) are built using open source and commercial codebases that they don’t own or control. If an entity tests a piece of third-party code and determines that it meets their obligations under ADA and then an update to that code introduces an accessibility bug and they are unaware, who is at fault and who is responsible for the remediation? The process seems a little more straightforward with open source code, provided the library maintainer is open to contributions that improve accessibility, but commercial code is a whole other thing.</li>\n</ul>\n<hr>\n<p>On the whole, I really appreciate what Senator Duckworth and Representative Sarbanes (and their staff and partners) are trying to do here. I hope it passes and look forward to keeping tabs on the work of the various commissions tasked with providing the necessary guidance and resources that will lead to a more inclusive web.</p>\n<p>🤞🏻</p>\n","social_text":"Some thoughts on the Websites and Software Applications Accessibility Act proposed by @SenDuckworth and @RepSarbanes","url":"https://www.aaron-gustafson.com/notebook/thoughts-on-the-proposed-websites-and-software-applications-accessibility-act/","tags":["accessibility","inclusive design","software development","web design","web development"],"image":"https://www.aaron-gustafson.com/i/posts/2022-10-07/hero.jpg","date_published":"2022-10-07T16:41:58Z"},{"id":"https://www.aaron-gustafson.com/notebook/missed-connections/","title":"✍🏻 Missed Connections","summary":"I couldn’t comment directly on Stuart Langridge’s response to my last post, so here goes…","content_html":"<p>Earlier today, <a href=\"https://www.kryogenix.org\">Stuart Langridge</a>—who I worked with on WaSP’s DOM Scripting Task Force and have the utmost respect for—<a href=\"https://www.kryogenix.org/days/2014/09/19/fundamentally-connected/\">published a blog response</a> to <a href=\"https://aaron-gustafson.com/notebook/2014/a-fundamental-disconnect/\">my last post</a>. In it, he made some good points I wanted to highlight, but he also misunderstood one thing I said and managed to avoid addressing the core of my argument. As comments aren’t enabled on his site, I thought I’d respond here.</p>\n<p>Let’s start with the good stuff:</p>\n<blockquote>\n<p>Now, nobody is arguing that the web environment is occasionally challengingly different across browsers and devices. But a lot of it isn’t. No browser ships with a JavaScript implementation in which 1 and 1 add to make 3, or in which Arrays don’t have a length property, or in which the for keyword doesn’t exist. If we ignore some of the Mozilla-specific stuff which is becoming ES6 (things such as array comprehensions, which nobody is actually using in actual live code out there in the universe), JavaScript is pretty stable and pretty unchanging across all its implementations. Of course, what we’re really talking about here is the DOM model, not JavaScript-the-language, and to claim that “JavaScript can be the virtual machine” and then say “aha I didn’t mean the DOM” is sophistry on a par with a child asking “can I not not not not not have an ice-cream?”. But the DOM model is pretty stable too, let’s be honest. In things I build, certainly I find myself in murky depths occasionally with JavaScript across different browsers and devices, but those depths are as the sparkling waters of Lake Treviso by comparison with CSS across different browsers. In fact, when CSS proves problematic across browsers, JavaScript is the bandage used to fix it and provide a consistent experience — your keyframed CSS animation might be unreliable, but jQuery plugins work everywhere. JavaScript is the glue that binds the other bits together.</p>\n</blockquote>\n<p>To be honest, I could not agree more, nor could I put it more elegantly. JavaScript, as a language, is relatively stable in terms of its core API. Sure, there are some gaps that JavaScript libraries have always sought to even out, but by and large what works in one browser will work in another. Assuming, of course, JavaScript is available… but let’s come back to that.</p>\n<p>In this passage Stuart also highlights the quagmire that is CSS support. This is a great point to hammer home: we have no assurance that the CSS we write will be understood by or interpreted the same in every browser. This is why it is so important that we provide fallbacks like a hex value for that RGBa color we want to use. It pays have a solid understanding of how fault tolerance works because it helps us author the most robust code and ultimately leads to fewer browser headaches (and happier users). I devoted a huge portion of the CSS chapter in <a href=\"https://adaptivewebdesign.info\">my book</a> to the topic.</p>\n<p>I also loved this passage:</p>\n<blockquote>\n<p>Web developers are actually better than non-web developers. And Aaron explains precisely why. It is because to build a great web app is precisely to build a thing which can be meaningfully experienced by people on any class of browser and device and capability. The absolute tip-top very best “native” app can only be enjoyed by those to whom it is native. “Native apps” are poetry: undeniably beautiful when done well, but useless if you don’t speak the language. A great web app, on the other hand, is a painting: beautiful to experience and available to everybody. The Web has trained its developers to attempt to build something that is fundamentally egalitarian, fundamentally available to everyone. That’s why the Web’s good. The old software model, of something which only works in one place, isn’t the baseline against which the Web should be judged; it’s something that’s been surpassed. Software development is easiest if it only has to work on your own machine, but that doesn’t mean that that’s all we should aim for. We’re all still collaboratively working out exactly how to build apps this way. Do we always succeed? No. But by any measure the Web is the largest, most widely deployed, most popular and most ubiquitous computing platform the world has ever known. And its programming language is JavaScript.</p>\n</blockquote>\n<p>I’ll admit I got a little teary-eyed when he said <q>The Web has trained its developers to attempt to build something that is fundamentally egalitarian, fundamentally available to everyone.</q>. Stuart is bang on with this passage. Building the Web requires more of us than traditionally software development. In many ways, it asks us to be our best selves.</p>\n<p>The one thing I take issue with is that last sentence, but again, I’ll come back to it.</p>\n<p>In the middle, his post got a little off-track. Most likely it was because I was not as clear in my post as I could have been:</p>\n<blockquote>\n<p>I am not at all sold that “we have knowledge of [the server environment] and can author your program accordingly so it will execute as anticipated” when doing server development. Or, at least, that’s possible, but nobody does. If you doubt this, I invite you to go file a bug on any server-side app you like and say “this thing doesn’t work right for me” and then add at the bottom “oh, and I’m running FreeBSD, not Ubuntu”. The response will occasionally be “oh really? we had better get that fixed then!” but is much more likely to be “we don’t support that. Use Ubuntu and this git repository.” Now, that’s a valid approach — we only support this specific known configuration! — but importantly, on the web Aaron sees requiring a specific browser/OS combination as an impractical impossibility and the wrong thing to do, whereas doing this on the server is positively virtuous. I believe that this is no virtue. Dismissing claims of failure with “well, you should be using the environment I demand” is just as large a sin on the server or the desktop as it is in the browser. You, the web developer, can’t require that I use your choice of browser, but equally you, the server developer, shouldn’t require that I use your particular exact combination of server packages either. Why do client users deserve more respect than server users? If a developer using your server software should be compelled to go and get a different server, how’s that different from asking someone to install a different web browser? Sure, I’m not expecting someone who built a server app running on Linux to necessarily also make it run on Windows (although wise developers will do so), but then I’m not really expecting someone who’s built a 3d game with WebGL to make the experience meaningful for someone browsing with Lynx, either.</p>\n</blockquote>\n<p>Here’s what he was reacting to:</p>\n<blockquote><p>If we’re writing server-side software in Python or Rails or even PHP, one of two things is true:</p><ol><li>We control the server environment: operating system, language versions, packages, etc.; or</li><li>We don’t control the server environment, but we have knowledge of it and can author your program accordingly so it will execute as anticipated.</li></ol></blockquote>\n<p>In this passage, I was talking about software we write for ourselves, our companies, and our clients. In those cases we do—or at least we <em>should</em>—know the environment our code is running in and can customize our code or the server build if a particular package or feature is missing. In fact, this is such a consistent need that we now have umpteen tools that empower us make recipes of server requirements so we can quickly build, configure, and deploy servers right from the command line. I would never write server-side code for a client running Windows without testing it on a carbon-copy of their Windows server. That would be reckless and unprofessional.</p>\n<p>If, however, I was writing code to sell or license to third parties, I’d fall into the second camp I outlined:</p>\n<blockquote>\n<p>In the more traditional installed software world, we can similarly control the environment by placing certain restrictions on what operating systems our code can run on and what the dependencies for its use may be in terms of hard drive space and RAM required. We provide that information up front and users can choose to use our software or use a competing product based on what will work for them.</p>\n</blockquote>\n<p>Lots of people who offer software in this way provide an overview of hardware and software requirements for using their product, and that’s fine. But I feel Stuart was incorrectly lumping the two camps together. He asks “Why do client users deserve more respect than server users?” I agree with the sentiment—the lack of requirements documentation for some third party server utilities is certainly appalling—but if I choose to try installing a given utility or program without knowing if it will work on my system, that’s my choice. And, moreover, failing installs of server-side utilities is a concern that I—a technical-savvy software developer—can readily deal with (or at least that I am competent enough to solve with Google’s help). I don’t think we can expect the same of the people who read our content, check their bank balances on our systems, and whose experience and capabilities may not be the same as ours.</p>\n<p>Stuart brings his response to a close with the gloriously uplifting statement—<q>[B]y any measure the Web is the largest, most widely deployed, most popular and most ubiquitous computing platform the world has ever known.</q>—before declaring, unequivocally, <q>[I]ts programming language is JavaScript.</q> That sounds great, but it’s not entirely true.</p>\n<p>The first part is dead-on: the Web absolutely is <q>most popular and most ubiquitous computing platform the world has ever known</q>, but saying that the Web’s only programming language is JavaScript is a bit disingenuous. Yes, JavaScript is the de-facto programming language in the browser, but that’s only half of the equation: PHP, Perl, C++, Ruby, Java, Python… these (and many others) are the languages that drive the vast majority of the server-side processing that makes the dynamic Web possible. (Yes, JavaScript has made it onto the server side of things, but I don’t think that was what he was trying to say. Stuart, please correct me if I’m wrong.) These languages provide a fallback when JavaScript fails us. We need them.</p>\n<p>The fact is that you can’t build a robust Web experience that relies solely on client-side JavaScript. And that’s what disappointed me about Stuart’s post: he completely avoided addressing this, the main thrust of my argument. While JavaScript may technically be available and consistently-implemented across most devices used to access our sites nowadays, we do not control how, when, or even if that JavaScript is ultimately executed. That’s the disconnect.</p>\n<p>Any number of factors can bring our carefully-crafted JavaScript application to its knees. I mentioned a few in my post, but I’ll reiterate them here, along with a few others:</p>\n<ol>\n<li><strong>Bugs</strong>: None of us write buggy code, of course, but even if we did, we have numerous safeguards that would prohibit that buggy code from making it into production. <a href=\"https://blogs.wsj.com/digits/2011/02/07/gawker-outage-causing-twitter-stir/\">Right? Right!?</a> But what about third-party code? I have gotten a buggy version of jQuery from the Google Ajax CDN before. And I’ve certainly come across buggy jQuery plugins. And what about the JavaScript being injected by other third party services? Advertising networks… social widgets… we test all of that code too, right? Any errors or conflicts in JavaScript code can cause all JavaScript execution to stop.</li>\n<li><strong>Browser Add-ons</strong>: We can’t control which add-ons or plugins our users have installed on their browser, but each and every one has the ability to manipulate the DOM, insert CSS, and inject scripts. If we don’t code defensively, we can spend hours trying to replicate a bug report only to ultimately discover the person reporting it had an add-on installed that was causing the issue. I’ve been there. It sucks.</li>\n<li><strong>Man-in-the-Middle Attacks</strong>: Back in the olden days, we used to have to worry about JavaScript being blocked at the firewall as a security threat. That issue has largely gone away, but we still run into similar issues today: Sky accidentally blocked jQuery for all of their UK subscribers when they <a href=\"https://www.theguardian.com/technology/2014/jan/28/sky-broadband-blocks-jquery-web-critical-plugin\">mistakenly flagged the hosted version of jQuery as malware and filtered it out</a>. And routers are capable of injecting code that can break our pages too: <a href=\"https://aaron-gustafson.com/notebook/2014/the-network-effect/\">I wrote about Comcast doing it the other day</a> and then experienced a similar issue with the Atlanta airport’s free Wi-Fi while on my way home from BlendConf. Sadly, unless we send everything via SSL, we can’t even control what code ultimately gets delivered to our users.</li>\n<li><strong>Underpowered Hardware</strong>: Some devices just don’t have the RAM to store or processing power to execute large JavaScript frameworks. If we’re using one, we could be dead in the water. Oh, and iOS sandboxes in-app browsers and <a href=\"https://sealedabstract.com/rants/why-mobile-web-apps-are-slow/\">they run really slowly</a> compared to the Safari browser (which is already pretty slow compared to desktop browsers). If someone opens a link to our site in the Twitter app or if we are using an app wrapper around our Web experience, the whole thing may… just… crawl.</li>\n<li><strong>Still Loading</strong>: While our JavaScript is being downloaded, processed, and executed, it’s not running. So, if JavaScript is a requirement for any interaction, the site could appear frozen until the browser finishes dealing with it.</li>\n</ol>\n<p>All of this adds up to JavaScript being the biggest potential single point of failure in our Web experience.</p>\n<p>Again, it’s not that JavaScript is a bad thing; I love JavaScript and write it every day—some days it’s all I do. But when we write JavaScript, its critical that we recognize that we can’t be guaranteed it will run. We need a backup plan and that’s what progressive enhancement asks of us. If we do that, our bases are covered and we can sleep soundly knowing that our users are happy because they can do what they need to do, no matter what.</p>\n<p>And I, for one, enjoy sleeping.</p>\n<p><em>Note: I no longer use “native” in this context, but it remains in quoted material.</em></p>\n","url":"https://www.aaron-gustafson.com/notebook/missed-connections/","tags":["web design","web development","JavaScript","software development"],"date_published":"2014-09-19T20:12:50Z"},{"id":"https://www.aaron-gustafson.com/notebook/subtree-merge-as-an-alternative-to-submodules-with-git-svn/","title":"✍🏻 Subtree merge as an alternative to submodules with git svn","summary":"We use Subversion as our version control system for all client work here at Easy because we absolutely love Springloops’ hosted Subversion service , but we use Git for all of our open source projects because, well, Git is a lot more fun…","content_html":"<p>We use <a href=\"http://subversion.tigris.org/\">Subversion</a> as our version control system for all client work here at Easy because we absolutely love <a href=\"http://www.springloops.com/v2?r=131284121846315085\" rel=\"external\">Springloops’ hosted Subversion service</a>, but we use <a href=\"http://www.kernel.org/pub/software/scm/git/docs/\" rel=\"external\">Git</a> for <a href=\"http://github.com/easy-designs\" rel=\"external\">all of our open source projects</a> because, well, Git is a lot more fun to work with and we love the community that’s built up around <a href=\"http://github.com\" rel=\"external\">Github</a>. In order to have the best of both worlds when working on client projects, we use <a href=\"http://www.kernel.org/pub/software/scm/git/docs/git-svn.html\" rel=\"external\">git-svn</a> as our front-end to Subversion. It’s a great tool, but it’s not without its limitations. One such limitation is its inability to translate <a href=\"http://www.kernel.org/pub/software/scm/git/docs/user-manual.html#submodules\" rel=\"external\">Git submodules</a> into <a href=\"http://svnbook.red-bean.com/en/1.0/ch07s03.html\" rel=\"external\">svn:externals</a>. Thankfully, Git offers an alternative that is comparable and plays nicely with Subversion: <a href=\"http://www.kernel.org/pub/software/scm/git/docs/howto/using-merge-subtree.html\" rel=\"external\">the subtree merge</a>.</p>\n<p>When attempting to <code class=\"shell\">dcommit</code> a Git repository containing a submodule, you’ll likely receive a message like this:</p>\n<blockquote cite=\"http://de-co-de.blogspot.com/2009/02/git-svn-and-submodules.html\">\n<p>952bee47201e87b0b0e851bcbe6c8940d429cda0 doesn’t exist in the repository at /usr/local/git/libexec/git-core/git-svn line 3787 Failed to read object 952bee47201e87b0b0e851bcbe6c8940d429cda0 at /usr/local/git/libexec/git-core/git-svn line 480</p>\n</blockquote>\n<p>That annoying message is the painful reminder that you need to find another way to add content from another project into your repository. Subtree merge to the rescue!</p>\n<p>If you’ve already hit the error, go ahead and delete your submodule folder(s) and the <code>.gitmodules</code> file and commit the changes to your repository to make the path available again. Next, from a shell within the root of your Git repository enter these commands at the prompt (replacing the capitalized phrases with your relevant information):</p>\n<ol>\n<li><code class=\"shell\">git remote add -f LOCAL_NAME PATH/TO/GIT/REPOSITORY</code></li>\n<li><code class=\"shell\">git merge -s ours --no-commit LOCAL_NAME/BRANCH_NAME</code></li>\n<li><code class=\"shell\">git read-tree --prefix=PATH/I/WANT/IT/IN/ -u LOCAL_NAME/BRANCH_NAME </code></li>\n<li><code class=\"shell\">git commit -m \"Merge of PROJECT\"</code></li>\n<li><code class=\"shell\">git pull -s subtree LOCAL_NAME master</code></li>\n</ol>\n<p>To provide a fully fleshed-out example for you, I used the following to merge the master branch of eCSStender into the path <code>vendors/ecsstender</code> within another project.</p>\n<ol>\n<li><code class=\"shell\">git remote add -f eCSStender git://github.com/easy-designs/eCSStender.js.git</code></li>\n<li><code class=\"shell\">git merge -s ours --no-commit eCSStender/master</code></li>\n<li><code class=\"shell\">git read-tree --prefix=vendors/ecsstender/ -u eCSStender/master</code></li>\n<li><code class=\"shell\">git commit -m \"Merge of eCSStender into the vendors directory\"</code></li>\n<li><code class=\"shell\">git pull -s subtree eCSStender master</code></li>\n</ol>\n<p>The beauty of this is that you can use that last line to pull in the latest version of the external project and then all you have to do is <code class=\"shell\">dcommit</code> the changes to get them into Subversion. Problem solved.</p>\n","url":"https://www.aaron-gustafson.com/notebook/subtree-merge-as-an-alternative-to-submodules-with-git-svn/","tags":["developer tools","software development"],"date_published":"2010-04-05T10:45:21Z"},{"id":"https://www.aaron-gustafson.com/notebook/oracle-opens-up/","title":"✍🏻 Oracle opens up","summary":"In hopes of stemming the massive explosion of open source database use, Oracle is preparing an “express” version of it’s Oracle Database 10g line: Oracle Database XE . Like many things on the web right now, it’s currently in beta, with…","content_html":"<p>In hopes of stemming the massive explosion of open source database use, Oracle is preparing an “express” version of it’s Oracle Database 10g line: <a href=\"http://www.oracle.com/technology/products/database/xe/index.html\">Oracle Database XE</a>. Like many things on the web right now, it’s currently in beta, with a full release planned for late this year.</p>\n<p>Courting the open source set is an interesting move for Oracle. <a href=\"http://www.php.net\">PHP</a> developers are the obvious target right now, but I wouldn’t be surprised to see some of the focus shifted to <a href=\"http://www.rubyonrails.org\">Rails</a> developers in the near future.</p>\n<p>Here’s a breakdown of some of the features/limitations:</p>\n<ul>\n<li>available for Windows or Linux</li>\n<li>stores up to 4GB of data</li>\n<li>will only use one processor (crippled to keep their Enterprise clients no doubt)</li>\n<li>will only use up to 1GB of RAM (ditto)</li>\n<li>upgradeable to other Oracle Database 10g editions (of course)</li>\n</ul>\n<p>I haven’t downloaded it to play yet, but there seems to be some fairly detailed instructions on both install and integration on the PHP end.</p>\n","url":"https://www.aaron-gustafson.com/notebook/oracle-opens-up/","tags":["open source","software development","business"],"date_published":"2005-11-03T15:25:17Z"}]}