AI is improving at a sustained, impressive pace. During 2025, models went from being a novelty with potential to being a genuinely useful tool that I use daily. The improvement in both models and tooling has been remarkable.

That said, I’m still not convinced that LLMs will replace software engineers. It will just make engineers more productive and reduce the pressure on the workforce of this industry. The day we achieve artificial general intelligence everything will change, then it won’t just be the software engineers job that we should be worried about. Until then, what we have is a very capable tool, a leverage that landed quicker than probably any other before it.

I’ve been doing this job for 15 years. It is obviously impossible to tell where the LLM’s capabilities will land, however my gut feeling is that there is only so much that we can squeeze out it. Based on my current conversation with Opus 4.6, which I consider to be the best of the best at the moment, it is incredibly capable but it is no senior software engineer. It is like dealing with a smart junior engineer that works at 100 times the speed.

The easy part easier, the hard part harder

There’s an excellent article by Blundergoat called AI Makes the Easy Part Easier and the Hard Part Harder that I agree with completely.

Writing code was never the hard part. It’s writing code well. It is understanding the problem, navigating ambiguity, knowing why a particular approach is the right one, and having the judgment to make architectural decisions.

This is exactly why you should lean into AI for the easy parts and stop fighting it on the hard parts. Use it where it shines, go old school where it doesn’t.

There are still plenty of times where even the most capable model, across multiple providers, leads me absolutely nowhere and I have to do things the old-fashioned way. In the previous year, I invested a significant amount of my time into experimenting with the capabilities of AIs and I’ve started to understand what it is good at and what it is not good at. And so, being able to speed up my work when I’m quite confident that LLM will do well and not waste my time where I am not confident that it will, is what I think is the trick that a lot of people are missing out on.

From assembly to English

Here’s how I see the current landscape.

Consider the history of programming: machine code was written for computers, by humans who had to think like computers. Then came C, relatively close to the metal, but more readable, more expressive. Then Python built on top of it, abstracting further. Each layer made things easier to read, easier to express, easier to reason about. The human brain is capable of infinite wisdom and capacity of understanding, however, in our day-to-day, this amount is actually very finite. For example, Python allows us for our thoughts to go much further because they are abstracted much more than C and assembly were capable of.

Now we’ve added another layer: English.

We’ve gone from a language designed for computers, to a compromise between computer and human language (at varying degrees), to the actual native language of the programmer. AI is giving us a similar leap over high-level languages as high-level languages gave us over assembly.

However, here I should also address another concern of mine, and that is that our natural language is actually not as perfect as we usually like to think. When you express a concept to somebody, you may have to go into a certain level of detail that varies depending on shared context and how much you think your interlocutor is going to understand from what you’re saying. And so, in real time, you adapt and express more or less, depending on the situation. You will certainly be familiar with how sometimes the thoughts that you have expressed in your native language may have not landed in the way that you thought they should have.

The real bottleneck is human willpower

I’ve been saying this for years: the limiting factor in programming is not the computer or the language. It’s the human brain, but in particular, not even necessarily our intelligence. We only have so much willpower to chase down a bug. So much memory to hold a system in our heads. So much patience to set up a test environment, write boilerplate, or untangle someone else’s abstractions.

This is why I’ve always advocated for keeping code simple, not over-optimising, and making things easier for your future self. If you make things easier for future-you, then future-you will have more willpower to spend on the actual investigation, planning, etc.

The interface between humans and the power of computers has always been the bottleneck. When higher-level languages were introduced, humans suddenly achieved much more — not because they got smarter, but because the interface got better, the friction lower. The exact same thing is happening now with AI.

I’m still doing the thinking

I’ve read people on Hacker News saying they miss “doing the thinking” now that AI is involved. I disagree. I’m still doing the same amount of thinking. Maybe even more, because I can now tackle problems I would have previously shelved as too laborious.

Perhaps those people mean they miss tinkering with lower-level details, which is perfectly valid. I understand the appeal. But I don’t feel like AI is doing the thinking for me. It’s more like working together: I think, I direct, I review, I decide. The AI helps me execute faster. The thinking is still mine.

The complaint that they miss doing the thinking is the same as saying “I miss setting the registries of the CPU manually now that I have a higher level language that doesn’t require me to do it”. By all means, you can go and set the registries of the CPU manually, but is that really practical? Aren’t there other interesting problems that you can tackle with how much brain power you have freed up?

What AI has unlocked for me

Now that I feel that I have a good understanding as to where I can leverage AI and the very latest models are generally good, I’d say that in the best cases I can achieve the mythical 10x programming. Maybe even more. Side projects that I always wanted to do but never had the time or energy for are now feasible. Investigations that used to be laborious are quicker. Things that were annoying to put together now have shortcuts.

I built a few VS Code extensions that I’d wanted for years — small tools to navigate code more effectively. I’m particularly proud of one that lets you navigate to any line of Python code just by having the stack trace in your clipboard. It’s not perfect, but it’s something I always wanted and never would have built without AI. Not because I wasn’t capable, but because the friction to work in typescript and understand how to write a VScode extension was too high.

I’ve built machine learning models to predict delinquency for invoices at Yelp. I trained a model to recognise my black cat compared to other black cats. Small things, silly things, practical things — all of them now within reach.

And I’m writing a book. This is something I’ve always wanted to do, but it always seemed too much — too many words, too much structure, too much effort on top of a full-time job.

Practical advice

AI is great for greenfield, less so for production

Accept this and work with it. For new projects, AI is extraordinary. For complex, established codebases with years of accumulated decisions, it struggles. That’s fine, leverage the strengths and avoid the weaknesses.

Plan ahead and explain well

You reap what you sow. If you express something in as few words as possible and hit enter don’t complain if the response isn’t what you were hoping for. Then you’ll review it, redo it, and start losing patience. You may even think that LLMs are a fad, and you would be better off without it.

Instead: explain things well, once. Link the files you refer to. Do some planning together with the AI before you start. Then execute your plan. The upfront investment pays for itself.

agents.md is the most important thing you should configure

The file agents.md is probably the single most powerful leverage point you have, and I don’t see this being said enough, or strongly enough.

Every single time you open a new chat, it’s as if you’re talking to a brand new engineer on their first day. There is absolutely no reason not to invest time in writing, optimising, and tuning these files.

Use AI to use AI

I use AI to help me use AI better. I ask it what prompt would work best, whether syntax and grammar matter when writing prompts, whether the order of instructions makes a difference. If there’s a disagreement and I think the AI should have known better, I ask it why it thinks the disagreement originated and how we can prevent it. More often than not, I end up having the AI update my agents.md file to avoid the same issue next time. I review everything, of course.

Experiment more

Think about all the things you couldn’t do before. Just try asking AI to do something, go on, just for the lols. See how far you can push it. You might be surprised.

When making the placeholder website for my book I thought “Now that I have made the cover image I wonder if I can make the book in 3D”. The result, after several iterations, is quite stunning.

LLMs are cheerful but I’m grumpy

LLMs are tuned by companies that want to make money. I imagine that those companies have figured out that making LLMs sound cheerful and overconfident makes users happier. As long as the user is sold then the bottom line is subscriptions. A suppose that a fair, balanced and trustworthy LLM wouldn’t sell as much. They are accommodating to a fault. They will compliment your awesome ideas. “Great catch!”. “You are absolutely right”.

LLMs can’t be trusted. I’ve addressed this in my own agents.md by asking them to label their own confidence about their statements, to not sound like cheerleaders, and to flag uncertainty explicitly. You should do the same.

Case in point: this post

This post you’re reading right now is AI-generated. But the difference between a low-quality AI post and a high-quality one is the same as the difference between low-quality and high-quality code. I carefully selected what to say. I let AI help me write it. Then I checked everything, added a little, rewrote some parts, adapted some more. Two passes. I have probably saved some time, and in the meantime I migrated the website from prose.sh to Hugo on Cloudflare. Why not.

Have you received a new job offer? Ask for more money. Have you received a pay raise? Ask for more money. If you cringe at the idea of asking for more money, you likely really need to ask for more money.

Every year you have (hopefully) improved. You are wiser, learned some tech for a whole year, learned the processes, met the people, and therefore are worth more. So ask to be remunerated accordingly. Every time you receive a pay rise, google for the current inflation and discount that percentage from it. Lead the conversation this way during the meeting.

Never tell recruiters how much you earn, or want

There is no way any of this is going to play in your favor. Always decline to say how much you are currently making, or want. On the contrary, always ask for a salary bracket.

Ask why

Workers know how, gods know why.

Ask why, always. Why should you ask why you say? You learn quickly, I’m impressed! People tend to tell you how to solve a problem, rather than what the problem is, and they may not have considered certain things. This is particularly true when talking to non-engineers. Knowing why you are doing something also strengthens your understanding, and allows you to do a better job.

You should also keep this in mind when you are asking for help yourself: don’t just say what you need help with, start saying why you are doing it!

If you are new and feel like it would cause friction, just say that you really really want to learn.

Doing vs. learning

I’m more of a doer, and this had a negative impact over time. The pressure to deliver and prove yourself will push you to try and cut the learning short, and push forward. This is what my friend Lee calls “programming by coincidence”.

So, remember to take it slowly, and research a topic before jumping in and try to fix something you don’t know well. It will pay dividends.

Impostor syndrome

It’s important for you to understand that you will always feel like you don’t know what you are doing. That’s because you think most of your job should be “doing”, but in reality it is to find out how or even what you are doing.

The more you know, the more you know what you don’t know.

I’m often asked “when will this stop?”. If you do things right, it will never stop.

Career leverage points

There are a few things in your career that you can get a lot of leverage out of. Interviewing and your CV are a couple of them.

Invest a lot of time on your CV. Be 100% sure there are no typos. Keep it around 2 pages. Sell yourself without lying.

I revise mine often, mostly adding whatever comes to mind. Afterall, it will come with you for decades to come!

I’ve probably done more than a hundred interviews. I’ve also run dozens of them as an interviewer, which by the way helps (so go on sign up to run interviews for your company now!). This helps me to know what interviewers want, perform better in tech tests, being more confident, etc. It reduces the cognitive load during interviews, allowing time to think at a higher level.

Buy “Cracking the Coding Interview “by Gayle Laakmann McDowell, it’s worth it!

Ownership

Try to make all problems your problems and people will love you for it. In the right company, you’ll also get rewarded for it.

Work life balance

Make the most of your 7/8 hours of work every day, then switch off. If you can’t finish something that’s too bad, there is always tomorrow. Do you have too much to do and you can’t possibly fit it in your working day? That’s too bad, but your manager/team-lead should probably have planned things so that they could fit in your working day.

I only have two exceptions to this rule:

• If you screwed something up, you need to clean up after yourself.

• As a one-off, if there is a particular deadline, go-live, or the like, be flexible.

Yes, but

Whether it’s been planned in an agile fashion, or another way, you’ll have a certain stream of work. At some point you’ll be asked to work on something else. This usually comes in the form of “could you just…” or “spend 5 minutes on…”. The person you are talking to probably don’t realize how complicated things are, hence they think it’s a “5 minutes” job. But there is no such thing.

When you work, your time doesn’t belong to you, you are selling it, and if someone asks you to do something the only plausible answer is “yes”. Yes, but.

“Yes, but unfortunately this is not quite a 5 minutes job. If I do this I won’t be able to hit the deadline we set during our sprint planning. But if you are happy with this and you have communicated to the right people I’ll be happy to do this”.

I’ve been delivering this line or variations thereof for the best part of a decade. It never fails me.

Communication

Invest a lot of time and effort in communication. Nowadays a lot of this happens in emails, chats, etc, and this gives you the chance to be more mindful about it. Read back what you are about to send (it helps if you read it out loud). Make it as short as possible. Rewrite any ambiguities. Don’t show off.

I’ve done a business writing course on Coursera and I’d recommend it to anybody. It’s a great investment.

Honesty

Always try to be honest, people can tell subconsciously even if they don’t catch you. Even if you get away with it, it’s only a matter of time. Lack of honesty breaks trust, and we are nothing without it.

If you have a problem, communicate. Do you think you won’t make a deadline? Do you think you are doing something that’s not worth your while? Or is there something else that should be done? Speak up!

People are not computers

In the long term, this is a team sport, and “people” is one of the biggest problems to crack. You may be in the business because you like to write software, but to do well in this job you need to deal with people effectively.

Learn how to:

• Persuade people by not creating friction (e.g. “I’m right and you are wrong, and I’m going to prove it to you”) but rather bringing them on a journey with you.
• Build relationships. Gently and tactfully ask personal questions. Ask colleagues to go out. Etc.
• Give in a little sometimes.

… it depends

This has little to do with code reviews, yet it’s some of the best advice you’ll ever find around: it depends. Don’t take this article, or any other articles out there, for gospel.

When you are looking for a review

Do your homework

Do not submit code for reviewing before you reviewed it yourself. It’s annoying. It shouldn’t be the reviewer’s job to tell you to remove print statements, write tests, etc.

I usually review the code before every commit, but when I’m almost ready to submit my code for a review I give it a once-over to make sure it’s ready.

Make sure the tests pass, you didn’t leave TODOs, you are even accomplishing what you set out to, etc.

If you aren’t sure about your code then don’t ask for a code review, ask for an opinion, help, or pair programming. Never submit code you are not sure it’s correct.

The Swiss cheese model refers to a security model, but applies to so much more, including code quality and code review. The less confident you are about your code, the bigger the holes in your slice of cheese.

Make sure the reviewer is happy before progressing

Whatever the process in your company/project/team, make sure the reviewer is happy to proceed before you move forward. Don’t go resolving all the issues they raised and click merge.

When you are reviewing

It takes time

To review code it takes approximately 1/10 of the time it took to write it. Take your time, it’s not a race, and it’s important.

Tailor your review to your audience

When you know your colleagues you’ll start to be able to conduct yourself differently, depending on their strengths and weakness. I know a developer who is thorough, writes tests, etc. I reviewed thousands and thousands of lines of their code, and all I ever found was maybe a forgotten print statement. So now, whenever I review their code, I sit back, scroll a bit faster, and maybe even focus on learning from them. When I review some other people’s code I know that I need to check every comma, insist good code style is maintained, etc.

You are dealing with people

There will be times that you’ll be technically correct. The best kind of correct.

But how should you express yourself?

Let’s be honest, people skills are not rampant in this industry. Computers don’t care how you express your thoughts to them, but people do, and software development is a team sport. Whenever you find something that’s not quite right, please, try to express your thoughts politely.

“This is wrong because…” CTRL+A DEL “Have you considered…”. What’s the difference between these two? One may upset some people, the other is less likely to do so. One is a critic, the other one a suggestion.

Sometimes niceties run short, and you may have to tell people that what they are doing is not good, but being right is not a good reason for being nasty.

It’s not time for debates

Tabs or spaces? Code reviews are not the right venue to establish it! In part because it’s obviously spaces, but also because your opinion doesn’t matter at code review time.

There should be relatively specific code styles for your company/project/team. Hopefully they are up for debate.

You prefer double quotes to single ones? One for the committee, not for a merge/pull request.

See this insightful talk from Raymond Hettinger on PEP8, which dictates the style for Python.

Start from understanding what needs to be done

One thing is to scan some code to find bugs, but you also need to make sure that the code is achieving the right thing. Start from the ticket, or wherever else the code came from, to make sure it’s doing what it should.

Perfect is the enemy of good

My friend James is a ninja 🥷 hacker 👨‍💻, yet he’s not going to pester you to make your code perfect. Why? Because when work needs to be done, good is good enough.

Be like James.

This is just another area where the Pareto principle (A.K.A. 80/20 rules) applies. Don’t sweat the small stuff.

Other general advice

Double tap

Not sure? Ask for more people to review! If either party feels unsure, then it’s fair to say you’d benefit from having someone else reviewing the same code.

I already mentioned the Swiss cheese model. Here you are adding more slices to catch more problems.

Other resources

Smartbear’s Best Practices for Code Review

From an empty folder clone all your public repos using github API. Replace YOUR-GITHUB-USERNAME.

for SSH_URL in $(curl -s https://api.github.com/users/YOUR-GITHUB-USERNAME/repos | grep ssh_url | cut -d'"' -f 4)
do
    git clone $SSH_URL
done

This is a good time to BACKUP THIS ENTIRE FOLDER.

For every repo just cloned, run git filter-branch and check the committer and author email (they are two different things).

I had multiple emails, and each needs to be checked for each case. This looks crazy syntactically, but still easier than an in operator in bash… You’ll need one line to test for each case you may have used like “EmailOne”, “emailone”, “emailTwo”, etc, depending on how you tend to type this.

Force push after this is done. I have commented out this line because you’ll probably want to check what happened (use git log).

for dir in ./*/
do
    cd $dir || exit
    pwd
    FILTER_BRANCH_SQUELCH_WARNING=1 git filter-branch -f --commit-filter '
    if [ "$GIT_COMMITTER_EMAIL" = "ONE.OF@YOUR.EMAILS" ] \
      || [ "$GIT_COMMITTER_EMAIL" = "ANOTHER.ONE.OF@YOUR.EMAILS" ] \
      || [ "GIT_AUTHOR_EMAIL" = "ONE.OF@YOUR.EMAILS" ] \
      || [ "GIT_AUTHOR_EMAIL" = "ANOTHER.ONE.OF@YOUR.EMAILS" ];
    then
        GIT_COMMITTER_EMAIL="i-dont-want@to-be-recuited.thank-you-very-much";
        GIT_AUTHOR_EMAIL="i-dont-want@to-be-recuited.thank-you-very-much";
        git commit-tree "$@";
    else
         git commit-tree "$@";
    fi' HEAD
    #git push -f
    cd ..
done

If you are trying to dodge recruiters maybe you should check out this project that will allow you to filter their emails in Gmail: I don’t want to be recruited, thank you very much on Github.

Then I started working for the NHS, the biggest employer in the UK, and 5th in the world, just after McDonald’s. Seems like in such a big company nobody has time to spell things out, and after more than a year I’m still struggling to catch up on some acronyms. I often come across acronyms that I never bothered or dared to ask about, and despite having developed a sense for that they represent, I still don’t know what they stand for.

When writing code, good sense dictates you should call your variable pageTitle, rather than pt. So why is it ok to abbreviate GPES Data for Pandemic Planning and Research in a nested acronym to GDPPR?

I took a business writing course recently, and one of the key points was that you have to write for your audience. Look, I get it. I review a lot of merge requests, and the temptation to call them MR is strong, but think about your audience. Are you in a group chat with your Product Owner and the New Starter?

Use all the acronyms you are confident your colleagues know, when you are writing to them in private. Maximise understanding everywhere else.

The book invites the reader to progress in whatever order, as reading from front to back is not necessary.

Throughout the book you are prompted to visit other parts to expand on an topic. At the end of each section you are sometimes prompted with challenges that make you reflect on what you just read.

• Programming is a craft. At its simplest, it comes down to getting a computer to do what you want it to do (or what your user wants it to do).
• What Makes a Pragmatic Programmer?
  • Early adopter/fast adapter.
  • Inquisitive.
  • Critical thinker.
  • Realistic.
  • Jack of all trades.
• Care About Your Craft
• “Kaizen” is a Japanese term that captures the conceptof continuously making many small improvements

CHAPTER 1 - A PRAGMATIC PHILOSOPHY

1. The Cat Ate My Source Code
   • TIP 3: Provide Options, Don’t Make Lame Excuses
2. Software Entropy
   • While software development is immune from almost all physical laws,entropy hits us hard
   • TIP 4: Don’t Live with Broken Windows […] Don’t let entropy win.
   • Even with a fire to put out, don’t be the first to break a window!
3. Stone Soup and Boiled Frogs
   • TIP 5: Be a Catalyst for Change
   • TIP 6: Remember the Big Picture
   • Challenge: Sometimes deception is needed to catalyse change, so don’t use it to do harm
4. Good-Enough Software
   • If trade-offs are possible ask for them: how good is this software meant to be?
   • TIP 7: Make Quality a Requirements Issue
   • Often great software today is better than perfect software tomorrow. (MVP, agile)
   • Challenge: Think about the software that you use. Is it perfect? Would you rather wait for the “perfect” version?
5. Your Knowledge Portfolio
   • An investment in knowledge always pays the best interest. (Benjamin Franklin)
   • Knowledge in software is an expiring asset
   • Knowledge is an asset and can be treated like an investment:
     • Learn regularly
     • Diversify your knowledge
     • Learn some new up-and-coming tech
     • Give up on old tech
   • Goals:
     • Learn one new language every year (seems a lot). Different languages will force you to think differently. E.g.: Rust forces you not to use nulls and think of return types as Option and Result.
     • Read a technical book each quarter
     • Take classes
     • Participate in local groups
     • Experiment with different environments
     • Stay current online and offline
   • It doesn’t matter what use you are going to make of your new knowledge, the process of learning will expand your thinking.
   • TIP 9: Critically Analyze What You Read and Hear.
   • How to ask for knowledge: be specific, frame the question carefully and politely, once your question is written down look one more time for the answer, be patient, give back.
6. Communicate!
   • “A good idea is an orphan without effective communication.”
   • “Plan what you want to say. Write an outline”
   • Ask yourself about your audience the WISDOM acrostic (what, interest, sophisticated, detail, own, motivate)
   • Chose a style (short, long, factual, funny, etc)
   • Make it look good
   • if you want people to listen to you listen to them
   • TIP 10: It’s Both What You Say and the Way You Say It
   • Emails are forever

Chapter 2 - A Pragmatic Approach

7. The Evils of Duplication

   • TIP 11: DRY—Don’t Repeat Yourself
   • “It isn’t a question of whether you’ll remember: it’s a question of when you’ll forget.”
   • Duplication can be due to developers feeling there is no other way, without realising it, for laziness or because different developers produced by coincidence the same functionality.
     • Imposed duplication can be worked around by using a pre-processor.
     • Inadverted duplication can be due to unnormalised data.
   • Comments are knowledge too and take part in duplication.
   • Performances may tempt developers to duplicate, however this is just a cheap solution (e.g. some calculated data can be stored due to the expense of being produced, however care needs to be taken to update it if any of the inputs changes)
   • TIP 12: Make It Easy to Reuse
   • Ease or reusing functionality is a step towards de-duplication.

8. Orthogonality

   • Often overlooked but core concept of other methods and techniques.
   • Refers to the decoupling of things so that moving on one line your position projected on the other doesn’t change.
   • TIP 13: Eliminate Effects Between Unrelated Things
   • Productivity gain
     • “Changes are localized, so development time and testing time are reduced”
     • Promote reuse.
     • It’s easier to combine orthogonal components.
   • Reduce Risk
     • Compartamentalise problems.
     • Robustness
     • Probably better tested as tests are easier to write.
     • 3rd party changes have less effect on your system.
   • Layering is a powerful way to achieve orthogonality.
   • Test for orthogonality are easy: ask yourself how many parts of the software would be affected if you had to change any other part. It should be one.
   • Unit testing and documentation is an easy winner when code is orthogonal.
   • OOP can provide with tools for more orthogonality, but also more chances for less of it.

9. Reversibility

   • “Requirements, users, and hardware change faster than we can get the software developed.”
   • TIP 14: There Are No Final Decisions
   • “keep decisions soft and pliable”

10. Tracer Bullets

    • Tracer bullets are used to correct the aim of fire arms in the dark
    • TIP 15: Use Tracer Bullets to Find the Target
    • Like prototyping but keeping the code.
    • Build skeleton of a system

11. Prototypes and Post-it Notes

    • Prototypes don’t need to be on code. Could be on post-its or whiteboard.
    • TIP 16: Prototype to Learn
    • You can prototype anything new, risky, experimental, etc.
    • Prefer high level language, stick with an at least similar language if testing for performances.
    • Architecture wise prototyping is valuable to check for coupling, responsibilities and collaborations of components, interface definition, possible duplications, data access.
    • Make very clear to everybody that it’s disposable code.

12. Domain Languages

    • TIP 17: Program Close to the Problem Domain.
    • Come up with high level languages to help define a problem.
    • Different part of a problem may require their own language.
    • Define a syntax first with a notation such as BNF.
    • Tools such as bison and yacc can convert well defined languages to programming languages.

13. Estimating

    • Practice estimating to be able to get a feel for order go magnitudes.
    • TIP 18: Estimate to Avoid Surprises.
    • The first question when asked for an estimation should be “how accurate?”.
    • The smaller the granularity of the estimations the greater the assumption of degree of accuracy.

    Duration	Quote estimate in
    1–15 days	days
    3–8 weeks	weeks
    8–30 weeks	months
    30+ weeks	think hard before giving an estimate

    • The easiest way to improve on you estimate is to draw from other peoples experience.
    • Build a model for the estimate e.g. variants, building blocks.
    • “Your experience will tell you when to stop refining.”
    • As the estimate becomes more complex you’ll want to hedge your answers.
    • Take notes of you estimate and the actual values. Investigate when there is a substantial difference.
    • TIP 19: Iterate the Schedule with the Code
    • “What to Say When Asked for an Estimate? You say ‘I’ll get back to you.’”

Chapter 3 - The Basic Tools

• Start with basic tools then adopt new ones. Go back to to the basics from time to time to sharpen your skills.

14. The Power of Plain Text
    • TIP 20: Keep Knowledge in Plain Text
    • Cons: slower to computer, takes more space.
    • Pros: easier to remember the meaning of data, flexible, easier to test (e.g.: change data without recompiling).
15. Shell Games
    • GUI are best for simple operation, shell are more powerful.
    • TIP 21: Use the Power of Command Shells.
16. Power Editing
    • TIP 22: Use a Single Editor Well.
    • Make sure that your editor of choice is available on multiple platforms/OS/shells.
17. Source Code Control
    • Source Code Control Systems allows for decentralisation, collaboration, backup, statistics, undoing changes, compartmentalisation,
    • TIP 23: Always Use Source Code Control
    • Use SCCS for everything, not just code. [This may be a bit anachronistic now that a similar effect can be achieved with Google Docs and the like]
    • SCCS allows for automated and repeatable builds.
18. Debugging
    • “Embrace the fact that debugging is just problem solving, and attack itas such.”
    • TIP 24: Fix the Problem, Not the Blame.
    • TIP 25: Don’t Panic.
    • Resist the urge to fix just the symptoms you see. […] Always try to discover the root cause of a problem, not just this particular appearance of it.
    • Bug reporting isn’t an exact science.
    • Accuracy in bug reports is further diminished when they come through a third party
    • Isolate the steps to reproduce the bug
    • In the process of elimination assume you are at fault before a third party. If a third party is at fault you’ll still probably need to isolate the problem as much as possible for a bug report.
    • TIP 26: “select” Isn’t Broken
    • TIP 27: Don’t Assume It—Prove It
    • If it took a long time to fix try to find ways to make it easier for the next time.
    • If the bug came from one person’s misunderstanding see if anyone else had that misunderstanding.
19. Text Manipulation
    • TIP 28: Learn a Text Manipulation Language
20. Code Generators
    • TIP 29: Write Code That Writes Code
    • Passive code generators produce source code that becomes part of the project. They don’t always have to be totally accurate. [e.g.: templating]
    • Active code generators helps to comply with the DRY principle and are meant to be used continuously to feed changes from the input files to the output ones [e.g.: asp.net transforms]

Chapter 4 - Pragmatic Paranoia

• TIP 30: You Can’t Write Perfect Software
• Be defensive of other peoples code, and of your own.

21. Design by Contract
    • “Dealing with computer systems is hard. Dealing with people is even harder.”
    • “Bertrand Meyer developed the concept of Design by Contractfor the language Eiffel.”
    • In DBC there are 3 expectations that needs to be met: preconditions, postconditions and class invariants.
    • TIP 31: Design with Contracts
    • “Be strict in what you will accept beforeyou begin, and promise as little as possible in return”
22. Dead Programs Tell No Lies
    • TIP 32: Crash Early
    • “many times, crashing your program is the bestthing you can do”
23. Assertive Programming
    • TIP 33: If It Can’t Happen, Use Assertions to Ensure That It Won’t
    • Most “assert” should be left in the code even in production.
    • Asserts should have no side effects.
24. When to Use Exceptions
    • “One of the problems with exceptions is knowing when to use them. Webelieve that exceptions should rarely be used as part of a program’snormal flow; exceptions should be reserved for unexpected events”
    • TIP 34: Use Exceptions for Exceptional Problems.
25. How to Balance Resources
    • TIP 35: Finish What You Start
    • Don’t couple code with shared resources
    • “Deallocate resources in the opposite order to that in which you allocate them.”
    • If a series of resources are allocated in more than one place try to allocate them in the same order to avoid deadlocks.
    • Is always a good idea to invest in writing code to check the resource balance, like wrappers that tracks resources.

Chapter 5 - Bend, or Break

26. Decoupling and the Law of Demeter
    • Write ‘shy’ code: don’t reveal yourself to others and don’t interact with too many people.
    • Organise code in cells and limit their interaction like organisations that value privacy
    • TIP 36: Minimize Coupling Between Modules
    • “The Law of Demeter for functions states that any method of anobject should call only methods belonging to: itself, any parameters that were passed in to the method, any objects it created and any directly held component objects”
27. Metaprogramming
    • Get the details out of the code to make it soft and configurable.
    • Metadata is data about data.
    • TIP 37: Configure, Don’t Integrate
    • TIP 38: Put Abstractions in Code, Details in Metadata
    • Writing configuration out of the code allows for decoupling, abstraction, configuring application more easily and changing the configuration without compilation step
    • Decide if it’s worth implementing a mechanism to reload the configuration on the fly. Consider how long-running the application will be and how quick and easy restarting it would be.
28. Temporal Coupling
    • Time is often ignored in software architecture. Time aspects to consider are concurrency and ordering.
    • Workflow needs to be modelled with UML activity diagram or similar.
    • TIP 39: Analyze Workflow to Improve Concurrency.
    • The hungry consumer model consists of workers getting tasks from a queue.
    • TIP 40: Design Using Services.
    • TIP 41: Always Design for Concurrency.
    • Adding concurrency to a system that has not been designed as such is very difficult.
29. It’s Just a View
    • Use events to decouple.
    • Dispatching events from a single routine cause more coupling. Use the publish/subscribe pattern.
    • TIP 42: Separate Views from Models.
    • Use Model-View-Controller (MVC) to separate the model from both the GUI and the controls.
    • MVC typically exists in a GUI context, but the same concept on segregation of concerns can be applied to any kind of programming: Model is the data, the view is a way of interpreting the data, and the controller feeds the data to the view
30. Blackboards
    • A blackboard system is a data storage that allows actors to asynchronously work on shared data.
    • Blackboard systems became popular in artificial intelligence, where problems are large and complex.
    • TIP 43: Use Blackboards to Coordinate Workflow.

Chapter 6 - While You Are Coding

31. Programming by Coincidence
    • “We should avoid pro-gramming by coincidence—relying on luck and accidental successes—in favor of programming deliberately.”
    • There are several reasons why not to program by coincidence:
      1. May not be really working but only looking like it is.
      2. May be an accidental boundary condition and not work all the times.
      3. Undocumented behaviour subject to change.
      4. Possibly slower.
      5. More error prone.
    • “Assumptions that aren’t based on well-established facts are the bane of all projects.”
    • TIP 44: Don’t Program by Coincidence
    • To program deliberately you should:
      • Be aware of what you are doing.
      • Be aware of what you are going to do.
      • Proceed from a plan.
      • Don’t rely on accidents or assumptions. Assume the worse.
      • Document your assumptions (e.g.: design by contract).
      • Test your assumptions.
      • Focus on the important parts.
      • Don’t let existing code/functionality dictate what you are doing. Refactor if necessary.
32. Algorithm Speed
    • It’s important to estimate speed of algorithms when not linear.
    • The O notation determines the upper bounds of algorithms. Because of this it does incur in some precision loss.
    • The big O notation is also uses to model memory or other resources.
    • You should keep in mind the big O notation and ask yourself what scale are you working on to understand what the impact will be.
    • TIP 45: Estimate the Order of Your Algorithms.
    • If you are unsure on the efficiency of your code then run it a few time with different inputs and plot the results.
    • TIP 46: Test Your Estimates.
    • Sometimes is not all about the efficiency: if the inputs are known small it could be better to have easier to write and debug code.
    • Be wary of premature optimisations.
33. Refactoring
    • Building software is organic, much more like gardening than building constructions, but business people are much more comfortable with the latter metaphor.
    • “Rewriting, reworking, and re-architecting code is collectively known as refactoring.”
    • Don’t hesitate to refactor.
    • Good reasons for refactoring: duplication, non-orthodoganl design, outdated knowledge, performance.
    • Time pressure is often used as an excuse for not refactoring.
    • TIP 47: Refactor Early, Refactor Often.
    • Martin Fowler tips on refactoring: don’t add functionality while refactoring; Make sure you are covered by tests and run them often; Take short, deliberate steps.
34. Code That’s Easy to Test
    • “The term “Software IC” (Integrated Circuit) seems to have been invented in 1986 by Cox and Novobilski in their Objective-C book Object-Oriented Programming” and it refers to the practice of writing modular software that can be tested just like individual chips that are then composed together on a board.
    • We can test against the contract.
    • TIP 48: Design to Test
    • Unit tests provide examples on how to use your code.
    • Run the tests often.
    • Use test harnesses (JUnit, xUnit, etc).
    • Debugging may be necessary in production environment, in this case log files, hot keys sequences or web servers to reveal status messages may be the best option.
    • Format log files correctly to help with parson and for readability.
    • “Testing is more cultural than technical”
    • TIP 49: Test Your Software, or Your Users Will
35. Evil Wizards
    • TIP 50: Don’t Use Wizard Code You Don’t Understand
    • Developers routinely use things that don’t understand, but wizard’s code (boilerplate) is not abstracted away like a library or a processor mechanism, it’s interwoven with the developer code.

Chapter 7 - Before the Project

• There is a fine line between specifying too much (analysis paralysis) and not enough (not being ready).

36. The Requirements Pit
    • “Requirements rarely lie on the surface.Normally, they’re buried deep beneath layers of assumptions, miscon-ceptions, and politics.”
    • TIP 51: Don’t Gather Requirements—Dig for Them
    • “A requirement is a statement of somethingthat needs to be accomplished”
    • Document policies should be separated from requirements. E.g. only employee’s supervisors may see employee’s records should be defined as the need for access control in the requirements and specify who can access what(the policies/metadata/configuration) in another document.
    • “It’s important to discover the underlying reason why users do a par-ticular thing, rather than just the way they currently do it. At the endof the day, your development has to solve their business problem, notjust meet their stated requirements. Documenting the reasons behind requirements will give your team invaluable information when makingdaily implementation decisions.”
    • A simple technique to get the requirements right is to do the work of your future users.
    • TIP 52: Work with a User to Think Like a User
    • Don’t over-specify. Requirements are needs.
    • TIP 53: Abstractions Live Longer than Details
    • TIP 54: Use a Project Glossary
    • Make the glossary easily available (e.g., web resource).
37. Solving Impossible Puzzles
    • TIP 55: Don’t Think Outside the Box—Find the Box
    • Whenever faced with a puzzle that seems impossible ask yourself:
      • “Is there an easier way?
      • “Are you trying to solve the right problem, or have you been distracted by a peripheral technicality?”
      • “Why is this thing a problem?”
      • “What is it that’s making it so hard to solve?Does it have to be done this way?
      • “Does it have to be done at all?”
38. Not Until You’re Ready
    • TIP 56: Listen to Nagging Doubts—Start When You’re Ready
    • Listen to your instincts
    • If insure if waiting for the right moment or procrastinating then start a prototype, then you’ll know to start if you fee like you are wasting your time. If prototyping is creating new questions and you encounter snags on the way then you know you weren’t ready.
39. The Specification Trap
    • “Program specification is the process of taking a requirement and reducing it down to the point where a programmer’s skill can take over.”
    • The specification is a record for future developers and an agreements with the user, an implicit contact.
    • Many designers find it difficult to stop specifying. Is naive to assume that the perfect specification can be achieved, and even if the client signs it off you can’t guarantee that it’s is what they actually need and they won’t want to change it.
    • TIP 57: Some Things Are Better Done than Described
    • Having a lose specification allows developers to work their way around certain problems.
    • “spec- ification and implementation are simply different aspects of the same process—an attempt to capture and codify a requirement.”
    • Over-specifying incurs in diminishing or even negative returns.
40. Circles and Arrows
    • TIP 58: Don’t Be a Slave to Formal Methods
    • “Never underestimate the cost of adopting new tools and methods.”
    • TIP 59: Expensive Tools Do Not Produce Better Designs

Chapter 8 - Pragmatic Projects

41. Pragmatic Teams
    • “Teams as a whole should not tolerate broken windows” (see 1.2).
    • Code quality shouldn’t be delegated to one or some members of the team, it should be everybody’s responsibility.
    • The boiling frog problem is even more common in teams. The dilution of responsibilities makes it easier for the scope to increase and the time scales to decrease. Maybe appoint a person to be in charge of this.
    • Communication is important for individuals as much as for teams, which should comunicate as one. It help to generate a branding for teams, to give them identity.
    • A team member could be appointed as librarian to help with the duplication of documentation.
    • It’s a mistake to organise teams based on jobs
    • TIP 60: Organize Around Functionality, Not Job Functions
    • “The project needs at least two “heads”—one technical, the other administrative.”
    • “A great way to ensure both consistency and accuracy is to automate everything the team does.”
42. Ubiquitous Automation
    • “Manual procedures leave consistency up to chance; repeatabilityisn’t guaranteed, especially if aspects of the procedure are open to interpretation by different people.”
    • TIP 61: Don’t Use Manual Procedures
    • Compiling the project should be reliable and repeatable.
    • Automation doesn’t only apply to code, but also administrative tasks and documentation.
43. Ruthless Testing
    • “Most developers hate testing.”
    • TIP 62: Test Early. Test Often. Test Automatically.
    • TIP 63 Coding Ain’t Done ’Til All the Tests Run
    • Unit testing ensures the functionality of a self-contained unit of code.
    • Integration testings verifies the units of code works well together.
    • Validation and verification tests make sure you are building what the client wants
    • Resource exhaustion, errors and recovery needs to be tested too. There are several resources that you can test the lack of: screen resolution, network bandwidth, disk bandwidth, system clock precision, etc.
    • Performance testing include stress testing and load testing. Specialised hardware or software may be necessary.
    • Usability testing are run by real users in real environments.
    • Code quality can be partially tested by measuring cyclomatic complexity, inheritance fan-in and fan-out, response set (number of functions directly invokedby methods of the class) and class coupling ratios. Some of these can only be used by comparison to other pieces of code and so standard deviation is often used.
    • Regression testing compares the outcome of the current test to previous ones or known values. E.g.: making sure bugs don’t resurface.
    • Test data may be real-world one and be collected by competitors systems, or synthetic one that is generated to obtain a big quantity of it or test boundary conditions.
    • GUI tests can be complicated to maintain if the interface is being worked on. In this situation having decoupled code help in reducing the scope of the GUI tests.
    • TIP 64: Use Saboteurs to Test Your Testing
    • Code coverage can help understand if enough have been tested. However, testing 100% of the code lines doesn’t mean perfect testing.
    • TIP 65: Test State Coverage, Not Code Coverage
    • Code should be tested as soon as any production code exists.
    • Test should be run before checking the code in the source repository.
    • When bugs are found a test should be written to avoid it resurfacing.
    • TIP 66: Find Bugs Once
44. It’s All Writing
    • “Pragmatic Programmers embrace documentation as an integral part ofthe overall development process.”
    • TIP 67: Treat English as Just Another Programming Language.
    • TIP 68: Build Documentation In, Don’t Bolt It On.
    • “Code should have comments,but too many comments can be just as bad as too few.”
    • “Even worse than meaningless names are misleading names.”
    • Don’t add to the comments information that can be determined by tools. Like usages, and revision history.
45. Great Expectations
    • A project is successful if it meets the expectations of the clients.
    • TIP 69: Gently Exceed Your Users’ Expectations
    • Surprise the users, in a good way.
46. Pride and Prejudice
    • TIP 70: Sign Your Work
    • Take pride in your work but don’t become prejudiced of it in favour of your coworkers.

Quick reference guide

1. Care About Your Craft
   • Why spend your life developing software unless you care about doing it well?
2. Think! About Your Work
   • Turn off the autopilot and take control. Constantly critique and appraise your work.
3. Provide Options, Don’t Make Lame Excuses
   • Instead of excuses, provide options. Don’t say it can’t be done; explain what can be done.
4. Don’t Live with Broken Windows
   • Fix bad designs, wrong decisions, and poor code when you see them.
5. Be a Catalyst for Change
   • You can’t force change on people. Instead, show them how the future might be and help them participate in creating it.
6. Remember the Big Picture
   • Don’t get so engrossed in the details that you forget to check what’s happening around you.
7. Make Quality a Requirements Issue
   • Involve your users in determining the project’s real quality requirements.
8. Invest Regularly in Your Knowledge Portfolio
   • Make learning a habit.
9. Critically Analyze What You Read and Hear
   • Don’t be swayed by vendors, media hype, or dogma. Analyze information in terms of you and your project.
10. It’s Both What You Say and theWay You Say It
    • There’s no point in having great ideas if you don’t communicate them effectively.
11. DRY—Don’t Repeat Yourself
    • Every piece of knowledge must have a single, unambiguous, authoritative representation within a system.
12. Make It Easy to Reuse
    • If it’s easy to reuse, people will. Create an environment that supports reuse.
13. Eliminate Effects Between Unrelated Things
    • Design components that are self-contained, independent, and have a single, well-defined purpose.
14. There Are No Final Decisions
    • No decision is cast in stone. Instead, consider each as being written in the sand at the beach, and plan for change.
15. Use Tracer Bullets to Find the Target
    • Tracer bullets let you home in on your target by trying things and seeing how close they land.
16. Prototype to Learn
    • Prototyping is a learning experience. Its value lies not in the code you produce, but in the lessons you learn.
17. Program Close to the Problem Domain
    • Design and code in your user’s language.
18. Estimate to Avoid Surprises
    • Estimate before you start. You’ll spot potential problems up front. 19. Iterate the Schedule with the Code Use experience you gain as you implement to refine the project time scales.
19. Keep Knowledge in Plain Text
    • Plain text won’t become obsolete. It helps leverage your work and simplifies debugging and testing
20. Use the Power of Command Shells
    • Use the shell when graphical user interfaces don’t cut it.
21. Use a Single Editor Well
    • The editor should be an extension of your hand; make sure your editor is configurable, extensible, and programmable.
22. Always Use Source Code Control
    • Source code control is a time machine for your work—you can go back.
23. Fix the Problem, Not the Blame
    • It doesn’t really matter whether the bug is your fault or someone else’s—it is still your problem, and it still needs to be fixed.
24. Don’t Panic When Debugging
    • Take a deep breath and THINK! about what could be causing the bug.
25. “select” Isn’t Broken
    • It is rare to find a bug in the OS or the compiler, or even a third-party product or library. The bug is most likely in the application.
26. Don’t Assume It—Prove It
    • Prove your assumptions in the actual environment— with real data and boundary conditions.
27. Learn a Text Manipulation Language
    • You spend a large part of each day working with text. Why not have the computer do some of it for you?
28. Write Code That Writes Code
    • Code generators increase your productivity and help avoid duplication.
29. You Can’t Write Perfect Software
    • Software can’t be perfect. Protect your code and users from the inevitable errors.
30. Design with Contracts
    • Use contracts to document and verify that code does no more and no less than it claims to do.
31. Crash Early
    • A dead program normally does a lot less damage than a crippled one.
32. Use Assertions to Prevent the Impossible
    • Assertions validate your assumptions. Use them to protect your code from an uncertain world.
33. Use Exceptions for Exceptional Problems
    • Exceptions can suffer from all the readability and maintainability problems of classic spaghetti code. Reserve exceptions for exceptional things.
34. Finish What You Start
    • Where possible, the routine or object that allocates a resource should be responsible for deallocating it.
35. Minimize Coupling Between Modules
    • Avoid coupling by writing “shy” code and applying the Law of Demeter.
36. Configure, Don’t Integrate
    • Implement technology choices for an application as configuration options, not through integration or engineering.
37. Put Abstractions in Code, Details in Metadata
    • Program for the general case, and put the specifics outside the compiled code base.
38. Analyze Workflow to Improve Concurrency
    • Exploit concurrency in your user’s workflow.
39. Design Using Services
    • Design in terms of services—independent, concurrent objects behind well-defined, consistent interfaces.
40. Always Design for Concurrency
    • Allow for concurrency, and you’ll design cleaner interfaces with fewer assumptions.
41. Separate Views from Models
    • Gain flexibility at low cost by designing your application in terms of models and views.
42. Use Blackboards to Coordinate Workflow
    • Use blackboards to coordinate disparate facts and agents, while maintaining independence and isolation among participants.
43. Don’t Program by Coincidence
    • Rely only on reliable things. Beware of accidental complexity, and don’t confuse a happy coincidence with a purposeful plan.
44. Estimate the Order of Your Algorithms
    • Get a feel for how long things are likely to take before you write code.
45. Test Your Estimates
    • Mathematical analysis of algorithms doesn’t tell you everything. Try timing your code in its target environment.
46. Refactor Early, Refactor Often
    • Just as you might weed and rearrange a garden rewrite, rework, and re-architect code when it needs it. Fix the root of the problem.
47. Design to Test
    • Start thinking about testing before you write a line of code.
48. Test Your Software, or Your Users Will
    • Test ruthlessly. Don’t make your users find bugs for you.
49. Don’t UseWizard Code You Don’t Understand
    • Wizards can generate reams of code. Make sure you understand all of it before you incorporate it into your project.
50. Don’t Gather Requirements—Dig for Them
    • Requirements rarely lie on the surface. They’re buried deep beneath layers of assumptions, misconceptions, and politics.
51. Work with a User to Think Like a User
    • It’s the best way to gain insight into how the system will really be used.
52. Abstractions Live Longer than Details
    • Invest in the abstraction, not the implementation. Abstractions can survive the barrage of changes from different implementations and new technologies.
53. Use a Project Glossary
    • Create and maintain a single source of all the specific terms and vocabulary for a project.
54. Don’t Think Outside the Box—Find the Box
    • When faced with an impossible problem, identify the real constraints. Ask yourself: “Does it have to be done this way? Does it have to be done at all?”
55. Start When You’re Ready
    • You’ve been building experience all your life. Don’t ignore niggling doubts.
56. Some Things Are Better Done than Described
    • Don’t fall into the specification spiral—at some point you need to start coding.
57. Don’t Be a Slave to Formal Methods
    • Don’t blindly adopt any technique without putting it into the context of your development practices and capabilities.
58. Costly Tools Don’t Produce Better Designs
    • Beware of vendor hype, industry dogma, and the aura of the price tag. Judge tools on their merits.
59. Organize Teams Around Functionality
    • Don’t separate designers from coders, testers from data modelers. Build teams the way you build code.
60. Don’t Use Manual Procedures
    • A shell script or batch file will execute the same instructions, in the same order, time after time.
61. Test Early. Test Often. Test Automatically
    • Tests that run with every build are much more effective than test plans that sit on a shelf.
62. Coding Ain’t Done ’Til All the Tests Run
    • ’Nuff said.
63. Use Saboteurs to Test Your Testing
    • Introduce bugs on purpose in a separate copy of the source to verify that testing will catch them.
64. Test State Coverage, Not Code Coverage
    • Identify and test significant program states. Just testing lines of code isn’t enough.
65. Find Bugs Once
    • Once a human tester finds a bug, it should be the last time a human tester finds that bug. Automatic tests should check for it from then on.
66. English is Just a Programming Language
    • Write documents as you would write code: honor the DRY principle, use metadata, MVC, automatic generation, and so on.
67. Build Documentation In, Don’t Bolt It On
    • Documentation created separately from code is less likely to be correct and up to date.
68. Gently Exceed Your Users’ Expectations
    • Come to understand your users’ expectations, then deliver just that little bit more.
69. Sign Your Work
    • Craftsmen of an earlier age were proud to sign their work. You should be, too.

A quick look at the dev tools network panel showed there were indeed 2 requests, but the response size was different, and the second response preview was empty. According to Chrome the initiator of the request was some javascript at the bottom of the body.

Baffled, I called the front end developer over, but we quickly proved that it wasn’t due to any javascript. The request was fired with javascript disabled, but now the initiator was index.html:infinity, infinity being the line of code where that happened. On my simpler example it actually shows the very last line of the html.

When everything else fails: old style debugging

So….we started taking elements off the page, until it stopped.:

Turns out that style="background-image: url('');" it’s interpreted as “the URL of the background image is an empty string, relative to the current URL”.

You can double check this by opening your tools and going to this example.

Initiator with javascript

Initiator without javascript

What happened is that I don’t enforce uploading images in the CMS, but if none is selected the URL is just null or empty. Writing style="background-image: url('@(Model.Image?.Url)');" is incorrect, the rule should not be in the style attribute if the URL is blank.

The solution is to write a variable for the content of the style attribute, something like:

var imageUrl = Model.Image?.Url;
var style = imageUrl == null
    : string.Empty
    ? $"background-image: url('{imageUrl}');"

Reference

https://bugzilla.mozilla.org/show_bug.cgi?id=473528

As far as writing online goes it’s a big improvement over scribe.io. I’m just not sure that’s enough to make me switch to online writing.

I love the preview. Unfortunately, it’s not good enough as it doesn’t work with all Hugo’s shortcodes and custom ones either. What I would suggest instead is to have a test website. Forestry.io uses the development branch - you simply hook a new website under a test domain! Just make sure it’s not going to be indexed by search engines.

Forestry.io is not responsive or mobile friendly either, so keep that in mind if you wish to blog from your mobile.

Something I wish was also implemented is to be able to move files between folders. I organise them by year/month/day and it usually takes me more than a day to write a new blog post.

The lach of spel cheking when writin the post is very anoying. Not sure why but both Chrome standard spell checking and Chrome plugin Grammarly don’t work when writing the body of the post!

In general, it feels like yet another application designed for Jekyll, that works for Hugo as well.

By the time I finished writing this post I also noticed that it came out of beta! I’m very happy to notice that it still has a free version, with community support and for less than 10 users. I was a bit concerned I was being used as a guinea pig and wasting my time here :)

Couldn’t find a solution online so here is my easy one:

• Go to Google passwords, sign in to your account.
• Open the development tools in your browser, usually with F12. I’ve used Chrome.
• Paste the following code in the console.

// Gets all the elements to be clicked to delete the passwords.
var a = document.getElementsByClassName(“dga”)
// Click all the elements.
for(i=0; i < a.length; i++){a[i].click();}

I wanted this process to be as easy and quick as possible, with as few extra softwares and services as possible. There are a lot of solutions out there like Wercker but I didn’t want more things in my way.

Writing

Local

I write the posts from IntelliJ IDEA, which is my IDE of choice. Screw Sublime, Atom and all the rest! It’s quite heavier but is worth it. You get spell checking, quite good live previews with the Multimarkdown plugin (shame the embedded HTML doesn’t render), git integration, and in general a powerful IDE.

Just to be clear I like Sublime and Atom, but every time I use them there is something wrong. Right now the terminal in Atom doesn’t work for me. There is an open issue for this but in the meantime you get a blinking unmovable cursor staring at you.

I feel that, since Hugo is quite new, the tools haven’t caught up with its popularity yet. Intellij is flexible enough to allow you to have shortcuts live templates for your shortcodes. E.g.:

  <template name=".shortcode" value="{{&lt; $SHORTCODE$ &gt;}}" description="A Hugo shortcode" toReformat="false" toShortenFQNames="true">
    <variable name="SHORTCODE" expression="" defaultValue="" alwaysStopAt="true" />
    <context>
      <option name="OTHER" value="true" />
    </context>
  </template>

This allows me to type .s, press enter (if the live template .shortcode is selected), type the name of the shortcode and its parameters and press enter to keep typing without having to type too many symbols or having to move your cursor.

I keep switching between IntelliJ and the localhost page on my browser, where my hugo server is showing how the end result will be (just launch “hugo server” from the root folder). If you have the page open you don’t even need to refresh it thanks to Hugo’s live reload feature (and don’t even have to save the file since IntelliJ does it when it loses focus). This is very quick to do, which is particularly nice when you want to make final tweaks to make sure your post will display as you want.

Online

If you are using Github and want to write from your browser, or you are not at home, you can use prose.io. It’s a software developed for Jekyll, but works just fine with Hugo. You get some nice shortcuts to format your text with markdown in case you are not too familiar with it. It also allows you to upload images which are committed to your repo immediately. I don’t find it quite as powerful as IntelliJ but it’s a nice option.

You can have a look at my prose configuration to get you started. It’s important to know that prose.io can only generate content with yaml metadata. You will have to configure Hugo to do the same by adding MetaDataFormat: yaml.

I’ve looked at many more free online content editor:

• sofish
• webhook
• contentful
• prismic
• stackedit
• dillinger

I found them actually extremely good…just not very compatible with Hugo.

Unfortunately I couldn’t find any online resource to write and preview Hugo content, so editing content locally and preview it with Hugo server is still the best option for me. I reckon you could host a test environment to preview your draft, deploying with a different branch, by adding -buildDrafts to your hugo or hugo server commands.

Hopefully some tool that works perfectly with Hugo will come out soon. Spf13, the creator of Hugo, is thinking about creating one.

Deployment

I can deploy my website in 2 ways:

• Push you branch to the repo on the server.
• Push the master branch to the main repo. In my case this is on Github but can work with pretty much anything else.

These both trigger a small script which I’ve adapted from this tutorial on Digitalocean.

#!/bin/bash

# Better be specific rather than using $HOME because it wouldn't work with all users.
GIT_REPO=/home/draga/go-web
WORKING_DIRECTORY=$GIT_REPO/public
PUBLIC_WWW=/home/draga/public_html
BACKUP_WWW=/home/draga/backup_html

set -e

# Clean working dir.
rm -rf $WORKING_DIRECTORY
# Backup current website. Use -z if moving across network to save bandwidth.
rsync -aq $PUBLIC_WWW/ $BACKUP_WWW
# Restore backup if an error occurs from now on.
trap "echo 'A problem occurred.  Reverting to backup.'; rsync -aq --del $BACKUP_WWW/ $PUBLIC_WWW; rm -rf $WORKING_DIRECTORY" EXIT

# fetch repo to make sure it's up to date if working with remote webhook.
cd $GIT_REPO
git fetch
git checkout origin/master
# Build the website. GO HUGO!
/usr/bin/hugo -s $GIT_REPO -d $WORKING_DIRECTORY
# Mirror the output of Hugo to the directory where the website is hosted.
# Use -c to copy only files that have changed to avoid messing with webhost caches.
# Use -z if moving across network to save bandwidth.
rsync -aqc --delete $WORKING_DIRECTORY/ $PUBLIC_WWW
# Ask Google webmaster tools to parse your sitemap.
curl https://google.com/webmasters/sitemaps/ping?sitemap=https://stefano.chiodino.uk/sitemap.xml
curl https://www.bing.com/ping?sitemap=https%3A%2F%2Fstefano.chiodino.uk/sitemap.xml
# Disable trap.
trap - EXIT

I used the method described in the tutorial above for a while, but it bothered me to push twice since I had to type the password for my ssh key (I’ve disabled the password access to the server and can now only be accessed with the key). Also what if I wasn’t home or wanted to use prose.io?

Solution: git(hub) webhooks!

Thanks to github.com/adnanh/webhook, little software written in go, you can have you server listen on a port and execute a script when invoked.

I currently have it connecting in https, with a secret key, and executing the script when the master branch is pushed.

Now I can even use Github itself to edit my posts. Pretty neat!

Hosting

Now this was the long fun part. I wanted it all so it took a lot of learning, hence the fun.

I heard of nginx a lot and some research showed that it seems to be the go-to solution. Here are some, more performance related, details of how it performs for me: server load test.

I’ve then enabled the pagespeed module which is very complex and heavy, but definitively worth it! The website now scores 100/100 in Google PageSpeed, both in mobile and desktop!

I score 99/100 in GTmetrix just because there is a bug in the pagespeed module (1064) and the very header is added twice, and for some reason GTmetrix seems to think that is not there…? Or maybe is because pagespeed seems to add it on subsequent reloads. Another small penalty is for the G analytics code being cached for just 2 hours, it’s out of my control and don’t think is worth self hosting it.

YSlow seems to be mostly concerned of the lack of CDN.

You can find all the scripts that I’ve used to set up my server on github. They are ordered in the same way they are in the filesystem, so you should get the idea. There is a script to install nginx with the brotli and pagespeed module, directives to use webhook as a service, the entire nginx configuration, etc.

You may look down on a $5 machine but I’ve found it to be more than enough for my need.

I’m serving “static” content that has been generated by Hugo

I recently ran some load testing at work for a newly launched website so I decided to test this $5 server. I’ve been using loader.io since its basic usage is free.

The test

The server responds to a certain number of clients every second for a full minute.

The majority of the users must receive the page in < 5 secs. Only the html is loaded.

Plain HTML

10.000 requests a second! (that is the maximum that loaded.io goes on a free plan)

Enable strong HTTPS

How strong you say?

As expected enabling https is taking its toll. The server can’t accommodate less than half of the requests, “just” 4.000.

Full on PageSpeed on strong HTTPS

I’ve then enabled Google’s PageSpeed module for Nginx and enabled every performance related filter!

I’ve enabled 27 extra filters on top of the 34 enabled by default, leaving just 7 out that were just for compatibility or counterproductive, hell I’ve even enabled the filter to make the G analytics script async when it’s already implemented that way.

Result: a quite dramatic 150 clients/sec 😀

Here is the list of filters that I’ve enabled:

pagespeed EnableFilters responsive_images;
pagespeed EnableFilters outline_css;
pagespeed EnableFilters outline_javascript;
pagespeed EnableFilters move_css_above_scripts;
pagespeed EnableFilters move_css_to_head;
pagespeed EnableFilters rewrite_style_attributes;
pagespeed EnableFilters prioritize_critical_css;
pagespeed EnableFilters make_google_analytics_async;
pagespeed EnableFilters canonicalize_javascript_libraries;
pagespeed EnableFilters inline_google_font_css;
pagespeed EnableFilters local_storage_cache;
pagespeed EnableFilters convert_to_webp_animated;
pagespeed EnableFilters insert_image_dimensions;
pagespeed EnableFilters inline_preview_images;
pagespeed EnableFilters resize_mobile_images;
pagespeed EnableFilters remove_comments;
pagespeed EnableFilters collapse_whitespace;
pagespeed EnableFilters elide_attributes;
pagespeed EnableFilters extend_cache_pdfs;
pagespeed EnableFilters sprite_images;
pagespeed EnableFilters rewrite_domains;
pagespeed EnableFilters trim_urls;
pagespeed EnableFilters remove_quotes;
pagespeed EnableFilters defer_javascript;
pagespeed EnableFilters dedup_inlined_images;
pagespeed EnableFilters lazyload_images;
pagespeed EnableFilters insert_dns_prefetch;

Brotli (max compression)

Just add Accept-Encoding: br to loader.io request headers and… 75 clients / sec. Not bad considering that I’ve enabled the maximum (11) level of compression!

..and, if you are curious about the compression, my homepage file sizes are (method from Mozilla’s brotli post ):