Hacker News Reader

There’s another way out of this problem, but you have to focus on making the code dead obvious and simplify the tools for working with it.

That work doesn’t just pay off in rampup time. True, people can figure things out quicker. It’s easier for early career developers to transition to senior positions. It’s less likely for someone to vastly overrun estimates for tricky new features when the code is well factored. But it’s also about scaling your company up.

When your company gets bigger, you will have more than one project. You need to be able to remove people from project A without killing it, and occasionally bring people back to project A at a later date.

These things have been a constant source of drama everywhere I’ve worked where there “wasn’t enough time” to follow my recommendations. The projects grind to a halt and eventually they lose so many of the old people they have to start over. But it’s the same management style so the process repeats.

Do you have any more details on your recommendations?

At least one of them will be something similar to: write boring code. Document just a little more than you think you need to (be that in self-descriptive variables or actual comments). Don't get fancy unless actual measured performance dictates it, and when you do so, make sure you document both the why (which test indicated this was necessary) and the how (this is what we did, exactly, to make it perform better).

Get variable and method/function names right. They matter more than most comments. I remember a code base I inherited

    if avail > 0:

I could never reason well about that. Then I changed it to

    if available_hosts > 0:

and eventually into

    if number_of_hosts_to_scan > 0:

Technically this would be enough

    if number_of_hosts_to_scan:

but it's less clear.

I'm not afraid to type long variable names because the editor has autocomplete. I don't type much and I don't make typos.

If the function is called scan_hosts, then if the parameter is n, it's more or less obvious to me that n it's number of hosts to scan. I'm willing to read a block comment to remind me what n is.

nHosts according to a popular naming standard and using camel case.

Some issues could be:

1. It is not obvious to everyone. 2. Another integral parameter called k is added later on. Now which is which? 3. Another guy might call all his integral parameters k. n and k are used for the same thing all over the code-base. An outsider might initially think they are different. 4. Names which are descriptive of their use are obvious to everyone by definition.

It may not be obvious to strictly everyone, but that should be reasonably obvious to anyone with enough context to have any business touching that code.

Uncle Bob’s Clean Code.

Write code like you’ll have to debug it at 2 am. Some day you will.

This works better for established companies than startups, once they know the pain of the first option. However, when on a 6 month runway, it may not be rational to optimize for 6 years, when you aren’t even guaranteed product/market fit.

I specialize in long life software, so I agree with you, but I understand the alternative.

> I specialize in long life software

How does one market themselves in this specialization?

I'd look at Corgibytes as an example - it's not how I market myself as much as what problems I gravitate toward, with the alternative being startups.

> It's small teams that were together from the start. Going through the initial setup of a project makes all the difference. When people come later, they lack the intuition that comes with being around when all the structural decisions were made. Early people make tradeoffs and bake good and bad practices into the pipeline, later people are told not to touch certain things because it's more complicated than it looks or will break something else that doesn't seem explicitly connected.

I've also seen this happen and agree with your analysis that it's probably not related to the programming language - it seems more like a problem with how the thought process behind those decisions is (not) recorded.

Short of making every project (and the codebase it results in) live for a short enough time to guarantee that nobody new will ever have to look at it, we've got to collectively do a better job of being able to explain the "wtf did you do that?!" aspect of development.

Your last sentence reminded me of "The only valid measurement of code quality: WTFs/minute": https://www.osnews.com/story/19266/wtfsm/

A readme (in plain language) in every folder helps a lot. Either that or it's replaying every commit from the start. Maybe tools can be made for this.

http://akkartik.name/post/wart-layers

As it happens, my current project that uses it has a Readme in every folder: https://github.com/akkartik/mu

I don’t think it’s about tools as much as culture - whether it’s a readme, a wiki or a chat log that’s not full of talk about the weather and scones (no, really), people have to be suitably incentivised to work that way. Something that isn’t a customer-deliverable (they aren’t going to directly care if you don’t record the weird business process that led to you implementing feature X the way you did; they don’t have a comparison which tells them that if it was recorded, changes could’ve been quicker/cheaper/less risky) is at risk of being cut as soon as there’s a hint of time pressure to get something out the door.

It’s coincidental that doing things in less of a “let’s all get in a room and talk about it for 3 hours” way should make keeping remote workers in the loop easier too.

I've been chasing project longevity (particularly in infrastructure like languages and OSs) for a long time, and came up with a prerequisite: http://akkartik.name/about

This quest took me from programming in Lisp, to C, and now to raw machine code. I'm hoping to build back up to high level languages, but with key implementation features that enable outsiders to comprehend a codebase.

https://github.com/akkartik/mu/blob/master/subx/Readme.md

Part of that is the difference from having a system with paying customers vs a new system still trying to gain them. Risk for changes increases with success and for devs who don’t own the company they can’t make hard calls as easily.

I would have to agree with this wholeheartedly, thanks for adding it. Yes, risk tolerance drops over time as a business solidifies, and hyper productivity is partly a function of high tolerance for risk. Risk tolerance goes down at the same time that sales and technical debt and complexity and team size all go up, so I think losing the feeling of hyper productivity over time the more successful a company is, is both natural and inevitable.

Agreed: On the one hand, the anecdotes in this article are not structured in such a way that allows one to say that it must be the language difference, rather than people issues, that accounts for the difference in outcome. They present less of a conundrum if you don't assume the former.

On the other hand, C++ seems to be strictly more complex than Python, and if so, it would not be surprising for there to be cases where the latter can be applied more quickly.

Peter Naur has written before about the problems of ramping up new people on old codebases: http://akkartik.name/naur.pdf

I think this is the essential tech debt (and so shows up the essential problem with that framing; you aren't so much going into debt as selling yourself into slavery, because the debt will never be repaid).

I work on this problem:

https://news.ycombinator.com/item?id=19533179

https://news.ycombinator.com/item?id=19533139

Now that is interesting, thank you!

> Typically it takes a year at a new company before I'm moderately useful.

WTF? What kind of companies are these? How are they successful in the slightest?