Ask HN: Have you ever inherited a code base you thought was well done? I see and hear a lot of complaints around inheriting code bases that are less than stellar. If anyone has, I'd love to hear about cases where you inherited a "good" code base, whatever that may mean: awesome test coverage, good documentation, solid organization, consistent styling/formatting, abundant best practices, whatever! |
The thing that struck me about the code is how well scorched the whole thing is. Portability is great, structure is clean, comments are good. When I came in, there were no tests, so I started adding them, but overall it’s been the best code base I’ve gotten to work with.
I ripped it off and replaced with a compiler with waay better performance. It was appreciated but I think my code, while more effective wasn't as nice to look at.
The codebase was just… normal, it was fine. Really two simple for there to be anything I would object to.
It was, however, my first exposure to Gatsby. I had struggled in the past with the older approaches to React SSR, absolutely eye-opening, changed everything about the way I work.
I have seen that a lot of devs simply see code that was not written by them as wrong. So they tend to rewrite it to fit their mental model of what good is.
I wonder how much time is lost in this
As for what that looks like - it's hard to say. I would not say I commonly find "good" documentation or organization. Sufficient test coverage has been common and extremely helpful (especially b/c tests are often implicit documentation about how functionality is expected to proceed).
I would generally say that well done code has a flow that follows the conventions of the languages & libraries that it uses. Being able to appreciate the flow means that, whatever direction you want to go, you know how to pivot from the current state.
When I get "bad" code it's code that I can't actually work on until I do weeks or months of work trying to understand what the original intent was.
The classes were small (< 100-200 LOC), they fit together well, and the code was well tested. It was a SyncML parsing library developed in-house in Objective-C.
What helped, I believe, was him coming from a Ruby / RoR background (extensive OOP usage) and the fact that this was his 2nd attempt at writing this, after he wrote a similar library in Ruby.
I think about some code to this day and try to emulate wherever possible. Although I think the guy that wrote it was also a very smart person and experienced programmer, so I don't beat myself up if I can't quite make it to that standard.
I've seen and personally experienced that again and again.
While you don't always have the luxury of doing it, I think we make a bit too much from the "Second-syndrome effect" -- that says building it a second time will invariably be over-engineered -- and not enough from "build one to throw away" -- ironically both are from Fred Brooks.
Also under-estimate the value of domain knowledge, understanding the use cases and what needs to be done. If you've already built a thing (OR have intimate knowledge of a thing), and you know where it succeeded and failed, you can often use that knowledge to figure out the elegant design that will fail less and succeed more.
I inherited a codebase where the backend is written in Kotlin (using Micronaut) and the frontend in react
Both the backend and frontend are very clean and i learnt so many new cool things just by reading the code.
The code is so easy to follow and understand, and the architecture is very nice
The frontend's consists of react functional components that are are written in a way that makes them very reusable and configurable; each component can be extensively configured with props, making it very rare to have to create new components
The backend is structured into independent microservices and it is therefore very extendible and the microservices themselves are small and easy to modify
Since it was written in a language and framework for which I have no particular expertise, I'm judging this purely off the things I do know -- the rough structure of an MVC, and database design. Maybe the way they used the framework is poor, but it looked decent to my untrained (in language and framework) eyes.
I inherited a large code base in Scheme (Lisp) from two PhD engineering domain experts. One of them had been a systems programmer before grad school, and had built the foundation from scratch, including an entire complex Web backend and frontend framework, including continuation-based Web forms UI serving, and a versioned ORM with a meta layer (extensible by customer sites using an early browser-based Web UI builder), etc..
The system evolved for over a decade, with a very small and super-productive team, and was able to respond very rapidly to new requirements.
One more conventional Web example: when we needed to be in AWS, we owned and understood the underlying framework intimately, it had good abstraction layers where we needed it, we could code the protocols and understand the distributed systems changes, and just do it... which also got us the side honor of being the first system to get a particular federal security certification for AWS.
Another Web example: when we needed a handheld app, we were able to get into the guts of the meta layer, and do an HTML5 Offline app. A large part of which was generated dynamically, as a semantic translation of complex Web forms from the meta layer to idiomatic smartphone and tablet UI. (Admin user had previously painted a form with particular spatial layout with rich controls for knowledge capture in desktop and occasionally modified it, a new algorithm did structure recovery of grouping and ordering of those fields, mapped them to modern device-responsive handheld controls more usable on small touchscreens, and the system updated the generated app package for JIT updating as necessary.)
There were numerous other examples of how the code base evolved to growing functionality and operational requirements, but those two might be most recognizable.
Of course, part of it was the team and how we were managed. And part of it was that the code base gave the team a very smart head start with a powerful foundation that let it churn out functionality at a high rate early on, yet was also amenable to evolution with a very small team. I think these parts were complementary, and affected each other.
So I don't think that a good codebase does any one particular thing well, it just avoids the bad parts of bad codebases. Via negativa in practice.
1) I was working for a small company that did contracts related to graphics and printing. At some point we were asked to evaluate a MacOS (8 or 9) extension from Extensys. I don't recall what the extension did beyond the general thing that all extensions do, which is patch some system routines to update their functionality. But the code was incredibly clean and clear. Despite having never written a Mac system extension before and having only a vague understanding of the process of doing so, I was easily able to follow the code and understand how it worked. Unfortunately, we ended up not taking whatever the job was (probably just updating the extension for a more recent OS or something), so I didn't actually get to work on it.
2) Many years ago I sold some video filters for popular video editing programs (Final Cut Pro, After Effects, etc.). Eventually I sold my IP to a competitor and went to work for someone else. Fast forward ~12 years, and I'm at a trade show, when I see some 3rd company still selling my products! I don't know if that means my code was actually good, but it survived for at least 12 years after I stopped working on it, so I guess someone was at least able to figure it out.
The code isn't exactly easy to understand, but that's inherent to the complexity of the domain. But there's a lot of elegance to a lot of the data structures and how well optimised they are for the problem at hand.
And Stockfish' way of utilising multiple cores is simply beautiful to me. There are all sorts of algorithms for parallellisation of the Principal Variation Search algorithm at the core of Stockfish's search, to do with distributing nodes between threads and so on and so forth.
If you go read Stockfish, it might seem like it's just running ncpu separate single-threaded searches. Because that really is what it's doing. Which seems crazy at first.
But what it does is it has a shared, effectively constant time(technically O(n) where n is 3, the number of entries per cluster) lookup hash table for caching search results, keyed by the node. And it's even lockless. And then each thread has its own set of statistics generated through search, which then influences the order in which that thread visits nodes because they're used for move ordering heuristics. And there's some other heuristics where the thread might jump straight from searching depth n to n+2, to inject some more randomness.
So there is a distribution of different nodes to different threads. It's just an emergent property of fairly simple things happening in each thread, whether they got a cache hit or miss, etc.
The reason this is so elegant is that the search algorithm itself is much simpler this way because it doesn't care about what other threads are doing. It looks at the transposition table, that's all, everything past that is good old single threaded programming. Then there's a very simple bit of code at the end that does a vote for the best move, based on evaluation and various other statistics(like the number of times the thread has changed its mind on the best move).
What excites me so much about this is that you could in theory do wildly different things in different threads. They only have to agree on what goes into the transposition table, what it means, and how to vote at the end. Stockfish doesn't do that, so that's one of the things I've been trying to explore in my own project.
The previous developers done a great job of documenting and structuring the system in a way that made it easy for me to migrate it onto something maintainable.
If there was enough developers floating around to make it viable to maintain in ColdFusion it would still be going now and doing a great job too!
And the testing! It came with its own testing DSL that allowed you to specify templates of expected XML results and check that the actual response from the live web service matched the template. A new test could be written in a handful of lines. The test suite was HUGE and comprehensive, and when adding a new test it was easy to find a group of similar tests to put it in. I never enjoyed writing test code as much as I did on that project, and that's how it should be for every project.
And the truth is I've probably been responsible for bad code that others have inherited, especially early in my career. My favorite way back then was to over-engineer and gold plate. I've also been the "over commenting guy" at times in the past. Thankfully I've mostly recovered from those ailments. Admitting it truly is the first step.
Now, I have a lot more patience for what I used to consider "bad code". I don't get too worked up by SOLID principles or other design issues, although I strive for a well-designed code base when I have a say in the matter (ie. greenfield or refactoring).
The thing that gets to me now is if the developer shows a complete lack of understanding of the language: Like they use concurrency, but they don't understand concurrency; Or they misuse an ORM and fall prey to the N+1 problem.
Those are sort of fundamental problems in my view, and indicate a developer who was in over his or her head.
It had no testing and documentation was little more than a brief overview in the internal wiki so at first it didn't feel very welcoming. But then the code turned out to be quite well organized and approachable. I added to it a couple of features that had been ignored for some time and the code really made sense. It guided you quickly towards the correct places you'd need to work on.
Ultimately the project itself was somewhat flawed because nobody wants to layout and maintain e-mail templates, specially when somebody insists that they want "100% pixel-perfect coverage on all e-mail clients including Outlook Express 5.01" -in 2014-.
In no way am I faulting the original authors. They designed a system for precisely what was requested and it worked beautifully. My point is that "well done" can change meaning based on the environment. There were spots in the architecture/organization that made valid assumptions that turned out to no longer be valid and had to be re-worked to accommodate the changes. They were correct in not laying out that flexibility in the first place, but it still represented an in congruence between the problem domain and the solution.
I don't mean just in terms of indentation, variable-naming, etc., but also in deeper ways, such as decisions about when to create new functions or extend object structures. Other clues relate to decisions about balancing code flexibility and execution speed, and also about what steps along the journey require road signs.
It's hard to define these things, but I find that the quality of code integration becomes evident when I'm sufficiently immersed in the code that takes the form of a communication between coders.
Not everything was perfect, but it was much better than the code changed by future generations which tried to mess it up with almost every commit, in the name of "it's good enough", "consistent style is not needed as I can still read the code", "what tests?", "we can refactor later"...
I had one project I inherited that was fairly clean. The codebase was well structured, tests existed and would run, there was documentation in place and it was relevant.
I have personal preferences that were fairly different from the original authors (namely - they chose coffeescript, and had a fascination with single line methods and chaining) but I can't really fault them a ton there - to each their own.
It helped that it was a very small project, so there just wasn't much space to get lost in the weeds, but it's still probably one of the better organized legacy code bases I've been handed.
Everything else made sense at the time it was written. Sure it may have outgrown it's usefulness today but if something chugs along for a few years I'm not going to call it bad code, just bad for the current situation, it was fine when it was authored.
I think the reason it was good is that nothing was too integrated. You had of course scripts who integrated multiple others (mostly Ansible roles tbh), and that could be complex to understand, but everything else was great.
So: keep everything small?
I think this has to do with a common mindset among developers. If they don't immediately recognize familiar patterns and structures then it's the fault of the code. Many folks value readability and believe that code should be written for other humans to read and understand. Yet what we consider readable varies greatly among individuals, programming languages, and communities.
More experienced programmers won't be so easy to jump to conclusions. They may realize that it takes time to understand why code is written or structured a certain way. They recognize that it will take time to learn and appreciate the code.
However experienced programmers also develop a sense of taste and style. They build opinions based on experience and if they see a pattern in use that they associate with negatively then it's likely they will not have a good opinion of the code base.
Less experienced programmers are trying to build their sense of taste and style and will associate with whatever they perceive makes them superior. They often have an immediate and strong reaction to a code base. Their opinions and feedback are often couched in absolute terms.
Personally I've inherited great code bases. One of my favourites was a messy, old C++ web application written in the 90s by someone without much experience at the time. It didn't use any standard libraries, had no tests and documentation was non-existent. It used the file system as the database storing XML files all over the place. A single-threaded CGI application: something I wasn't unfamiliar with.
You would think I would have held my nose while dealing with this code base. Yet I consider it a good one because the team that came before me did a lot of work to wrap this monstrous code base in Python and started writing tests for it: a lot of tests.
Those tests enabled them to start synchronizing the data the application normally stores in XML files into a Postgres database. When I came on I had a completely different idea of what legacy software was. The engineer handing the project over to me gave me their dog-eared copy of Michael Feathers' Working Effectively with Legacy Code.
I like that code base because I learned a lot from it. I kept adding more tests and started adding more functionality and replacing the old C++ bits slowly but surely. Eventually we were able to get rid of the XML stuff, the email system, and replace it with Python code. The application was running the whole time and making the company money. It was a great learning experience.
One of the qualities I've come to value the most in an engineer is tenacity. When someone inherits a code base and can roll up their sleeves and make it something better than it was before: that's someone I want to work with.
Too many developers raise their hands, complain that this code is terrible, and suggest re-writing it. Or they burn out and find new jobs else where. Me? I like to stick around, figure things out, and make them go to 11.
Past me however, is a total c##t that seems to take joy in solving their problems by making them a massive problem for me when the chewingum and dollar store masking tape inevitably fall off.
I get that. I also inherited some very awful code in my first job (almost 20 years ago) by some developers who misunderstood basic concepts of programming. They had such fundamental gaps that I (right out of college) was able to clean up their mess in a few hours.
> Too many developers raise their hands, complain that this code is terrible, and suggest re-writing it. Or they burn out and find new jobs else where. Me? I like to stick around, figure things out, and make them go to 11.
I agree completely. I get the best job satisfaction making things go to 11.
It's easy to spend a day with a codebase (that others spent years writing) and call it "bad". I'd argue it even feels pretty good to take that stance of superiority. But you're viewing it with literally zero of the context of the time in which it was written. You see none of the constraints, none of the pressures, none of the alternatives presented in the moment.
Particularly for a young or small company, if you're "inheriting" a codebase it's because it's existed and been in operation for a while. Yes, it may still be bad. But I would advise taking time to consider whether it's actually, within the lens of yesterday (or 2 years ago)... good?
I recently inherited a code base which was developed by some devs-for-hire while the company started building up the team to take over (including me).
I met the last remaining dev-for-hire for the handover and got the impression that the company paid very very close attention to how many hours they billed and which meetings they were allowed to attend, and 0 attention to the code they produced as long as it worked.
Thankfully, the code was actually working well enough - and the thing that I appreciated most of all was the fact that at lots and lots of places in the code, there were frank comments like
// This is completely undefined as of yet. I'm just implementing this how I think it should work, you can probably delete this and start over if it no longer makes sense.
That’s an interesting way to put it. I think that might be a good rule of thumb to help future maintenance: Avoid unintentionally erecting Chesterton’s fences.
survival is far too low of a bar. We want delighted customers, low churn on employees, low minimum bar of required IQ to understand it (easier hiring, less stress), inexpensive modifications + improvements.
Survival is only sufficient for cash strapped startups on borrowed time&money because if survival fails, then the future no longer matters.
But as soon as the future seems probable there is _much much_ better aims than just surviving.
Correct. I sometimes invite coworkers to partake in a thought experiment where they anthropomorphize the company (and/or codebase) they work at imagining, if it were a person, what state of health would it be in? This usually engenders a chuckle or two of some sort as they picture someone whom, though they are surviving, is otherwise in seriously poor health and does well to illustrate to them that if they were this individual they would likely be striving to significantly improve their quality of life and not just merely maintain status-quo of still having a pulse being the measure of success.
The next target then is acquisition or an IPO which is then followed up by quarterly earnings. It’s always survival first unfortunately
I think that's underselling the problem. A bad codebase is a codebase that isn't what it should be. Just because there are reasons, even legitimate reasons, as to why the codebase is what it is, that doesn't mean it isn't bad. Constraints can be bad and bad constraints make a bad codebase.
In my opinion, thorough documentation is a minimum. If a codebase doesn't have documentation, then it is automatically bad.
Software/programming/whatever you want to call it is about three things: (1) instructing a computer, (2) communicating between humans, (3) encoding knowledge of a domain. If a codebase fails at any one of those three, then it is a bad codebase. Too often, people only view a codebase in the lens of (1), in that if for the most part it does the thing it's supposed to, then that's enough.
Or was lucky enough that all the choices they made did not blow up yet.
I totally understand the value of technical debt. But I have also seen in the wild cases where people thought the codebase was great simply because they hadn't run into cases where its rotten core would be exposed.
Yet.
Other than to soothe egos, this almost never matters, because the person inheriting someone else’s code doesn’t live 2 years ago and can’t be blamed for not having the prior context (establishing that context is the job of the original author and is why documentation matters).
If you find yourself in the thankless position of having to reverse engineer intent and especially if you have an unsympathetic manager ready to lecture you about how you should magically read the mind of the original author, start looking for a new job and hack/slash away as much of the old code as possible to do the job that you’re asked to do.
Well put! When I was younger I would call codebases bad after a couple days of working with them. Now, it takes more like a couple months to fully form my opinion, although it's less about "Is this codebase good or bad?" and more like "What refactoring opportunities do we have to make this more maintainable and which ones make sense (from a bang-for-the-buck / prioritization perspective)?"
For example, I've worked on a huge C# product that has been developed in various epochs by up to 100 people at a time. When I was working on it, it was around 10 years old. Certain parts of it were in good shape, others had stuff like a 5k+ line OnPaint() method for a table cell that was doing data processing in place and had stuff like "if ((value == -2) && (type == someTableType) && (userOptions.SomeFlag == SomeEnum) && (someOtherColumn.Value == "something")) { value = paintCheckBox(enabled) }" and such.
Of course, that code was doing what it was supposed to (at least in general), and it had gotten to this state during a really bad delay where bug fixes/features had to be churned out to reach an important release date - so in some sense it was "good". But in the sense of being possible to change without a major re-write (of that particular area I mean) or without introducing 3 bugs for obscure combinations of features, it was really bad code.
But there is another context in which we might evaluate code, something like, “how far the code is from ideal, where ideal is the state the code would end up in if we could push a magic button to refactor the entire codebase, for free, to perform identical functionality and reduce both operational risk and the cost of future development”
Or, more succinctly: how clean is the codebase? Clean code has a cost, and sometimes it isn’t worth paying. That one off bash script that runs once every few months perhaps isn’t worth tidying up. I think the author is really asking about clean codebases.
I’ve seen it time and time again, with myself, colleagues above and below my grade, and devs I’m mentoring.
Chestertons Fence is a very important concept to have deeply engrained in your mind.
Of course, with experience, you get better at designing solutions to add some "optionality" in case things change, but it's a trade-off that you can't always make, nor should you always make.
While this is true and compassionate, I think bad code is still a bad code. It'd be dishonest to call a bad code a good code.
I agree though that from time to time circumstances simply wouldn't allow developers to take the time to write good code and/or address tech debts. This problem I feel would need to be catered at management level. If companies were to attract great talents, they would need to maintain certain standard of code quality and empower their developers to do clean ups/refactors every once in a while.
"good" is incredibly subjective, and subjectivity is temporal in nature. there been times when I thought code wasn't"good" at the time of inheritance, but several years later, found appreciation for it. Perhaps not enough to consider it good...but some appreciation.
I've tried to let go of classifying code as good or bad, or any other subjective means.
Non-exhaustive list of things I'm more concerned with these days:
- How long does it take for a new hire to onboard and be productive?
- How quickly are we able to respond with bug fixes?
- Do we have enough test tooling to have high enough fidelity coverage to say we've implemented something, or that an issue is fixed?
- How observable is it in production?
- How reproducible are any issues?
- How accurate is the documentation?
- Is there enough test coverage to be able to reimplement a portion with confidence?
You can probably take all of those things and distill it down into a "good/bad", but I think in general it's better to look at specific concerns that are managed over time.
I'm less concerned about the current state of the code, and far more concerned with how easily I can change the state of the code without incident.
This is great, it’s the most concise definition of clean code I can think of: how easily can I change the code in ways that the system as a whole changes only in ways I intended.
I hated it, on my young and inexperienced eyes “everything was a mess”. It didn’t follow any good practice. The code didn’t have any layer, most of the code was written in the view and it didn’t follow the DRY principle, it had just a few libraries to share some code, so there was a lot of repetition.
Of course, I started “improving” it. I chose a layered architecture, I wrote several generic classes to implement the repository pattern, since I was a solo developer it took me a while to migrate big pieces of code to my new implementation.
Bugs came and went and I started noticing something. Even though my implementation was “beautiful”. I hated to fix bugs on the new and “improved” code base. To debug I had to jump around a lot. The bug was always hidden. And sometimes my changes could affect other places in the code base so I had to be really careful. In the other hand fixing bugs in the old implementation was pretty straightforward and it rarely broke other places.
The project came to an end. The company bought a CRM that had more features so they shut the old code base down.
All my efforts to improve the code were a waste of time. They wasted my time, not only because it was not going to be used in the future, but because even if it lived longer my changes added unnecessary complexity to the code base. This complexity made it difficult to work on a really simple project, it made it fragile and it was simply not fun.
I learned a lot. I don’t judge code bases anymore. Now I can see the benefits of “ugly” code.
Pretty code is often pretty because the ugly part is hidden, like the piping in your bathroom.
I know where I'd much rather have a bug (leak), personally.
I had those familiar feelings of "I could never write code like this" or "I'd never have thought to do it like that!" or "This person must really know their shit". Turns out it was me all along and I'd just forgotten I'd done it all.
Grokking it and modifying it after 2-something years was actually simple as I'd left good comments, abstractions, and even reasonable unit test coverage (even integrated with GitHub actions that run on push) so changes were a breeze.
There has to be a life lesson there somewhere.
Can it really be called old considering the very modern tech stack?
I think I'm actually getting better at it, at least in some ways... but not totally sure there aren't others I'm not quite as brilliant.
Every variable and function was explained in a series of physical manuals in excruciating, and up-to-date, detail. The manuals had index lists by name, function, type and concept, making it ridiculously easy to find exactly what you were looking for. The documentation felt almost like reading Knuth's Art of Programming. It explained not just how a function worked, but also the dependencies and how they worked on that particular hardware, including pieces of the FORTRAN standard library.
On top of that nugget of most people's fantasies, there was actually a test suite! It wasn't written by the original authors, and had been pieced together over the years. But it was a testsuite for code running on a mainframe the size of a small room. Since when do you ever get tests for code written in the 70s!?
Working for CommBank was hard - the standards for absolutely everything that they have and do are A-grade. A single complaint from a coworker or customer can land you in front of a review board. But the work they produced, at least what I saw, is absolutely worth it.
Holy crap. Not sure whether I would love this or be destroyed by it haha.
Actually once I was lucky enough to join a company where the code was written well, had good test coverage, the team implemented good code reviews, required tests on bug fixes and features, etc. The pandemic was the five hundred year storm to their leveraged business model (hospitality business targeting business travelers) and they folded within months.
At the next job I created the backend code from scratch and was the primary maintainer. I left it in pretty good shape with good test coverage. There were plenty of things I'd have done differently given the chance though. Hopefully the next guy doesn't curse me.
At the current job things are a mess again. I'm working on improving it. Git blame has me at having modified/added 8000 lines in the backend Python code since I joined three months ago. Slowly digging out of the hole as it caves in around me.
For about a week my daily standup would be something along the lines of “I deleted 34,000 lines of code yesterday.”
In the end I think I threw away about 200k lines out of 350k.
In the span of the next few months I think we ended up identifying one method I’d removed that was still in use.
And qu’elle-surprise, the team’s velocity picked way up, people were suddenly way more willing to make bigger changes or even refactor, etc. People just really needed to get picked up out of the hole far enough that they could see the light and they ran with it from there.
It never became _good_ code, but it became much more manageable. Even if you can’t justify good code for the sake of good code, code good enough to actually be worked on is a must.
The list came out of a COBOL "DBMS" system that had a 64kb table limit. They had more names to print than that.
The stack of hacks consisted of scripts that ran trough all the tables of the "members list" DB (multiple floppies were doable, by the time i got it they had a hard drive), creating text "dump" files of the bits that went to the printer; more scripts to assemble those dumps and reformat them (in GWBASIC), and finally a script that fed one record at a time through the pretty printer formatting program and printed it out.
My contribution was figuring out a way to feed the "pretty printer" multiple records per run; instead of invoking the chain once per record. saved days for the entire print run.
It was a horrible stack and it wasn't fun to work with and I cussed the people who had implemented it; however: given the constraints when it was built and the resources of the people using it; it was incredibly cool. Until I saw it I'd have said it wasn't possible with that collection of parts, but it functioned as required and did so for a decade. Eventually it was replaced with WordPerfect doing a mail merge operation; the people wearing the name badges complained that the font wasn't as pretty.
1) Working (professionally) on a project that happens to be open source: https://github.com/metabase/metabase/
2) Coming to a Rails project mostly written by a very senior 7-person team. There was still a fair amount of jank (mostly from seed-round assumptions that weren't holding up when I joined after the Series A) but it still followed The Rails Way and nothing was too gross. It also helped that everyone important was still at the company and available for questions.
PS on (2): Seven of those original eight dev are now gone, including me; the median years of experience has gone from 8-10 to 0-3; the team size is at least 40 and I think more; and my understanding from friends still at the company is that the codebase is in general a flaming mess.
End results was an easy to maintain code and very extensible. But also it taught me a lot on how to architect things, what patterns to pick, etc. To this date, I've never worked on games with a code base as good as this one. Instead I'm doomed to see all the problems those games have in terms of architecture... (sometimes I can help solve some of them, when I'm granting enough time, but it's rarely a priority for companies, since there's no user facing changes and can induce regressions)
I had the chance to port the code to C# for some R&D in Unity, although I didn't really know C# at that time... but because the code base was so well split into libraries that made sense for the game, I could port them and test them separately and was able to progress much faster than expected. First with a client running as a console app, then later in Unity.
My love for that code base went as far as giving a lecture at the local University about its architecture and the patterns used in it :)
Fun fact: The libraries in Dofus are named after Discworld references, the world rendering library is named Atuin for example. A terrible idea in retrospective for new developers joining the team who had to idea what Discworld was!
I wonder if it would be legally ok now that I've left that company to write a blog post about the content of that lecture. (taking into consideration that it's trivial to decompile the client code out of the game SWF file)
I haven't worked or saw that code base for more than 4 years, but I could probably just jump back right in it without problems.
I do this because I received a project with this note, and it stuck with me as an excellent idea; a letter to future explorers.
Yes!
This is what comments (and READMEs etc) are for. Not explaining the what, ie how your programming language works (unless you're doing something most engineers wouldn't know). But explaining why they were made.
// Workaround for https://github.com/org/project/issues/263I think this is actually one of the under-rated most valuable aspects of github (and probably other similar systems), things it's changed the most -- that everything has a URI that can be linked to, including in code comments. And a reason I could never deal with "just git and email patches" without a web UI that gives everything a URI that can be linked to from text.
I especially like leaving links to issues in third-party open source dependencies. If someone comes along later and wants to change the thing that was a workaround to a bug -- they are easily started on the trail to figure out if the bug has been fixed, in what version of the dependency, etc.
after a sufficient time spent meditating on the construction techniques of that project’s chesterton’s fence, most codebases i’ve seen become much more reasonable. Once i’ve spent enough time using it myself instead of just reading it, design decisions or organic evolutions start to make sense.
A good-faith humility is a good attitude to have as a reader, but it only really comes with professional maturity. Un-curling the sneering lip most of us seem to pick up in our late teens takes, in my experience, about a decade in a relatively attentive person.
some are still truly horrific, but they’re relatively rare.
What makes code good is "How hard is it to fix issues" and "How easy is it to understand". You can have well documented code which ultimately is hard to understand. You can have well organized code which ultimately makes fixing issues with said code hard.
In order to know if a code base is good, you have to experience maintaining it. You can't (easily) know a code base is bad with cursory glances to mental checkboxes about it.
The metric I use for good code now a days is "How often does this wake me up in the middle of the night?" Good code is code that doesn't cause my employer to pester me off hours.
First was all the scaffolding/framework and inter-process/server protocol code was meticulous and beautiful. As a young c/c++ favoring engineer, I was very impressed and my design thinking was influenced a lot by this, for a long time.
Second, there were these deep algorithm implementations for digital image processing pipelines and also dicom data protocol implementation stuff. These "plugins" or "processing elements" were heavily optimized to squeeze out every last microsecond out of the start-to-finish execution wall time. So the code was hard to follow just by reading. Also, there's no way to understand this code without knowing the domain knowledge (studying the Matlab implementation of the image processing algorithm – to understand that required having a basic theoretical understanding of signal/image processing concepts).
But this was great as different engineers/teams could work on different deep algorithm processing elements and the framework/scaffolding ensured there were no leakages or undue blast-radius of any messy bugs.
A decade later I found myself staring at a very large php codebase. This codebase had a lot of sprawl but no depth. It was messy (bad idioms, wasteful of resources, functionally buggy etc) but it was easy to read and understand. PHP + the framework/scaffolding we had was very forgiving of these mistakes. The application would continue to chug along even with a lot of warnings and some data induced errors. It took some mental attitude adjustment to not lose it every time I saw crazy stuff like 3-level nested for-loops that would unpack an array of huge serialized objects and iterate over their elements only to not use the results for any final response rendering at all.
Gotta say I was amazed at not only the quality of the code base, but also the engineers there. Very balanced, mature, collaborative, kind and really the one place I learnt most about good software engineering. It was a C++ codebase with just the right amount of abstractions that you could expand when needed. No fancy syntax magic. Impressive debugabbility!
Folks at WMS gaming thanks for an amazing learning experience and patience despite me being an entitled little $h1t who was a pain to work with!
It wasn't that the code itself was badly or well written so much as the concepts of how each process was isolated from each other, the communication protocol was well established and the external dependencies were kept to a minimum.
Data structures were chosen for ease of understanding rather than (run-time) efficiency which was the appropriate choice for this application. The application(s) relied heavily on various other scripts and the operating system to establish a (secure) network communication, offloading a lot of the complexity from the application to the operating system (where it belongs, in my opinion).
I recently update/ported the code base to work on more modern hardware and, besides some minimal updates and fixes, it worked well.
The code base was 10+ years old and mostly written in a combination of C and shell.
I am sure you know how to do it differently, and more like how you prefer to do it, but that is not the same thing at all.
Legacy software is successful software. You are never asked to maintain failed software. Only software that is successfully generating $ years after it was originally developed.
So be humble. Show a bit of respect. And don't automatically assume that you are some super genius who knows how to do everything better.
And remember that other equally unenlightened developers will look at your code and go WTF and complain about how crap your code is. Don't be like them.
When we sit down to an inherited code base, we don't know what they were doing, so it looks terrible. There might be a very simple key that you'll never figure out until you've spent a lot of time reading the code. If you go adding code that doesn't jive with the hidden premises, there will be conflicts that you create, which you'll blame on the old code, even though it was your lack of understanding that created it.
I think their inexperience and lack of hubris made them go to a lot of effort to be idiomatic in a language they were using for the first time.
The project lead was incredibly impressed that I was able to make a solid contribution check-in on my first day :-)
At work, not so much, as it's mostly very rushed, badly designed software.
What's stopping you in improving the situation? Time pressure or unwilling colleagues?
For example, I inherited a large code base I while back and thought the classic "I can do better than this". After a few hours of hacking together a demo, only then could I appreciate the existing code base and how nice it actually was.
I think in general I look for a good level of abstraction - but not too an insane level. The best measure is how quickly you can understand it, and how long it takes for you to contribute to it.
IMO many legacy systems were coded to "good" standard for their time. This reflected the choices of idioms, styles, and robustness criteria.
Properly maintained codebase carries those conventions forward. When it's augmented to present day expectations, it's supposed to be done in non-destructive way possibly. There could be seams but not scars all over.
In my experience, the onus is on the inheritors to try and make and effort to keep the legacy code alive yet consistent.
Alas, those assigned to maintenance are often too junior to recognize the consistency let alone care about it. Thus the codebase degrades into a patchwork of "I've been there" marks.
Of course, languages vary on how much they have a "standard way" of doing things.
IMO one kind of "bad code" is code where i need to know about >3 things/places to change 1 thing. Where features get splayed across N places instead of being able to live in their 1 spot + direct consumers.
IME Rails codebases are a few months with a mediocre team or a few bad choices away from becoming an absolute garbage fire, and all the magic in Rails is part of why even a little of that sort of activity does so much damage.
Amazing for starting from scratch solo or with a very small team. Dangerous (mind: not necessarily bad, just dangerous) under basically all other scenarios, including ones that that sort of ideal situation might develop into. In particular, a great deal of discipline and excellent taste is required to maintain the kind of legibility and reliability other languages & frameworks can give you "for free".
I expect a Rails project has the best hope of remaining good at a business that's got solid funding for an in-house team from day 1, and has good retention for that team. However, lots of startups or experimental ventures by larger firms experience a lot of thrashing and turnover in the early days, and often go through one or more periods of heavy outsourcing, while also being the kind of resource-constrained enterprise for which Rails is extremely tempting.
Arguably Rails is still the right call for them, if it gets them to market fast, but those kinds of places consistently end up hit with slow, expensive, risky feature development just as they're starting to get traction, much earlier than the usual "eh, needing to replace this will be a good problem to have" phase, and part of that's because Rails falls apart so fast if you color outside the lines at all.
Unfortunately many developers think they're more clever than the standards (and as a medium to display their cleverness, they find Ruby quite accommodating)
But I would say that the danger is that you can break rules in bizarre unpredictable ways, which I've done myself and then gone WTF when going back to those projects years later.
It's also kind of annoying to set up and upgrade, lots of middleware to manage, but that's the case for almost every framework.
I always mention this when I'm hiring: our codebase is "old", but the code is actually well written and tested. I've seen worse code in projects that are just a couple of months old.
Curious - what version of Rails is it running on?
Totally agree. Part of what makes it so difficult is design isn't a one size fits all thing. The valuable part of experience is knowing when to and when not to apply a design pattern or "best practice".
Probably the most frustrated I've been in a code change is when a single line resulted in 10+ test files being updated (adding a parameter to a method call used in one place in the code...) This provided no actual benefit to the project at as a whole and was mostly just code churn.
What's worse, I've also seen places where there are a bunch of extra code paths added to support tests! In other words, code was made MORE complex simply to support tests. That's getting the cart before the horse.
Not to mention the times I've had to dedicate a significant part of my time fixing tests for a project because they intermittently fail (hurray for `Thread.sleep` in a test...) I wasn't going to work on the project when it would randomly fail unrelated to the code I wrote.
All this is to say like my original comment, there's no one metric you can look at and say "yeah, this is good code".
I work in PHP every day, and this is something I've picked up from seeing other resources online. PHP with its automatic casting and loose type comparisons is forgiving. This would be great for getting things to run quickly and making it easy for early web development for a beginner, and I think this has a lot to do with PHP's success and ability to get new developers interested back in the late 90s and early 00s.
The issue with this is it encourages bad behavior if there isn't a style guide for the team in place. Sure, we can pass around a string representation of our integers and it doesn't matter because PHP will handle casting for us whenever, but this leads to sloppy and hard to read code in my experience.
Modern PHP has leaned towards a more powerful type system (relative to its previous). I'm really happy with the static typing that the language has added in and I think that's a huge reason for a lot of the old gross PHP code.
Another one is the easy intermingling of server code and HTML. Again, this is powerful for fast and newby development, but ends up introducing complexity and mess. Writing a SQL query inside of a loop inside of a <table> tag? You can't tell me that isn't at least a little confusing to look at.
Fine language with a good trajectory, and it's legacy helped shape the web, but damn can you get your hands dirty.
For any mid engineers who run away from spaghetti, I’ve learned identifying and solving that spaghetti problem can be a huge leap forward in your career towards management/leadership roles provided you find the right company and are able to solve the spaghetti issues.
This is a great rule of thumb. I often find I unintentionally do that all the time and then I have to figure out why I did something I did. Trying to avoid that with good comments, documentation, etc. earlier in my career would have been a great practice.
I find I often think something is so common-sensical that I would never forget and then come back a while later and have completely forgotten.
As in, "put some traffic cones around that hack" meaning make sure there is a comment or appropriate error message or something that will make it clear to posterity that this is a known temporary sketchy situation, not an accidentally load bearing wall"
Another (in-house, salaried) contributor to the project I took over added a error message (in a very specific error handler for exactly one REST endpoint), and I quote
raise Exception("could not load data because of error")When you operate software, you realize all the little things a developer can do to make the operator's life much easier or harder. I always thought this was the "true meaning of DevOps" -- thinking of how to make it easy to operate the software at dev/design time, as if it were an old school shrinkwrapped application like Windows 95... but instead it got turned into writing terraform or something haha.
> "all the magic"
The "magic" factor in RoR is much less than, say, iOS development in XCode. And RoR has the benefit of being text-based, so whatever functionality you're looking for, you can be sure it's in a text file somewhere.
> made even worse by dynamic typing
This is a feature Ruby shares with the #1 and #2 most used programming languages.
> how bad a time you'll have if the test suite's absent, or stale & neglected
I agree that having no tests or bad tests guarantees a bad time, but I'd say it's pretty standard for even the bad codebases to be covered pretty consistently with unit tests. The Rails community has, by and large, accepted unit tests as part of our shared culture, so if your developers adhere to Rails convention, they will maintain decent test overage. That's a strength of RoR, not a weakness.
Because if he's the only one that understands the error message, he's the only one that can fix the problem.
That's how you get credit with the suits if something breaks.
No one ever notices a stable application. A programmer fixing a problem that no one understands? That must be a very smart person indeed.
I'm being needlessly cynical at this point. This was just one person at one company. Overall, I do think that given the right incentives, what you describe can happen. But it does not someone in leadership to care. And that's a hard sell to me.
Noooooo. A ton of things simply aren't defined until the program's running. "What even is this?" is frequently a question that's hard to answer without running the project (hope it's in a runnable state, then!)—even figuring out whether something's from Rails or from some other module (which one? Start googling or have fun poking at the Rails console against a running copy of the code until you figure it out) can be a pain. There's far less runtime metaprogramming magic in any other ecosystem I've worked in, which is lots and lots of them (including iOS). It's everywhere in Rails.
[EDIT] Also:
> The Rails community has, by and large, accepted unit tests as part of our shared culture, so if your developers adhere to Rails convention, they will maintain decent test overage. That's a strength of RoR, not a weakness.
Yes, tests are good! A culture of testing is good! But not every language/framework suffers so greatly from absent or bad tests as Rails does. Such heavy dependence on them is not a strength of Rails (though the culture of testing is).
Funny, none of those things sound bad to me, but just like part of the job :D Could be Stockholm Syndrome?