HACKER Q&A
📣 vagab0nd

How to force myself to write maintainable code?


When working on one-man side projects, I easily get into the prototyping mindset, and do minimum amount of work to get the code working. It's ok for actual prototyping, but obviously I suffer greatly after the product is shipped, as the code is neither maintainable nor testable. I tell myself every time: "Next time I'm gonna write better code and thoroughly test it", but it never happens.

I think I'm capable of writing better code, but just so deep in the habit of "hacking" that I can't be bothered to. What are some ways to force myself to write good code from the beginning?


  👤 Jtsummers Accepted Answer ✓
Write more tests. That's probably the best way for me. Writing tests forces me to write testable code. Which usually means higher quality code. It's hard to write tests for low quality code because you end up having fragile tests (having to change the tests because of changes in the program itself). Ideally the tests should be more like oracles, they should always work (at least until you decide to make a major redesign, not just a refactor).

Depending on your language of choice, if it has tools to initialize and manage packages/system/whatever-deliverables, make use of that to ensure good practice within the context of that language.

Build a CI/CD pipeline, even if it's just local. Most of my code never really leaves my machine (even though I use git for everything I write). I usually have a monitor running (either built into the language tooling like with `dotnet watch test` or just homegrown with `fswatch`) that executes tests/builds with every file save.

Pairing the previous two paragraphs, to avoid rewriting those scripts/tools every time I've forced myself into a habit of using good, standard organization for projects. By incorporating more testing (whether full-on TDD or not), I have to maintain the code quality a bit more.


👤 yesenadam
After I learnt about refactoring, decades too late, mainly from Refactoring and Clean Code, I spent at least a week refactoring a program of maybe a few hundred lines. It was amazing how much even such a short program can be improved in every way. It's the same as the difference between a horrible first draft of an article/essay and the 20th draft. Since then, I program in a way that's already "semi-refactored", and far clearer. And refactor/improve as I go. A lot of bugs and potential problems become apparent. The difference in my programs before/after is like night and day. And they're incomparably easier to understand when I return to them a year later. That was after 25 years of leaving it at the first draft stage, so people can change, don't worry! "To write clean code, you must first write dirty code and then clean it." Exactly as for prose writers, noone writes a good first draft. You write something bad then edit it again and again.

Also, I've always known that the more time spent with pen and paper before starting to type, the less time it will take and the better organized and thought-out the program will be.

To be specific about the refactoring/clean code, it's basic stuff like: Use spacing to make maths clearer (e.g. write 2x4 + 7, not 2x4+7). Functions that do one thing, with names that perfectly describe what they do. Variables perfectly named, used for one thing, grouped appropriately in data structures. Move comments into code. (Not "//this bit computes the size" but put it in a function called ComputeSize.) No magic numbers. Basic stuff that somehow I'd never focused on before...

I'm not into "forcing myself" to do anything, that doesn't sound like a good way of thinking about it! But maybe taking one of your messy programs and editing/refining it until it can't be improved further will inspire you like it did me.


👤 giantg2
You could ask someone to review your code. Then you can refactor.

You could comment the hacked parts of the code. This will allow others or yourself to understand the novel implementation at a later time. I have encountered those sorts of comments before and they are helpful to understand the code and add a new trick to my knowledge.