Hacker News Reader

> And there's the risk of the 'not so competent programmer', who knows how to fix stuff, without thinking far enough.

I would actually claim that majority of non-seasoned programmers fall into this category.

It's rare to see an engineer who would actively set out to destroy or cripple the system they are working on - but it is incredibly common to see one fix the problem they have at hand, using what happens to be available, and make the overall system just a tiny bit less pleasant to work with. Or understand. Let alone maintain.

Repeat the above a hundred times and your codebase would make Lovecraft take note. If each such modification reduces the quality just 0.5%, after 100 rounds you're looking at an aggregate damage of 40%.

> It seems to be a necessary evil for a company to grow

Yep, the needs of a company change when and if it grows. Early days, a small team "getting shit done" is probably what you want to find your place in the market, make early customers happy, etc. But as you scale on all axes: time, headcount, headcount turnover, customer count, feature count and so on, that early pile of shit that got done can start to bog you down. Even worse if no one recognises the need to change and continues adding to the pile.

I've seen a few really brilliant engineers struggle with this in various ways: 1. Start hating their job but being confused because they love the company -- not realising that the company has become a very different beast to the early days. 2. Struggling to get out of the "get shit done" mentality and just floundering. Even becoming a net negative contributor in some cases.

Worth remembering this I think in an industry where rapidly changing companies are so common. Your company might be a good fit _now_ but that does not mean it will stay that way!

I think the biggest issue with the grandparent comment's approach is that it makes things extremely difficult for newcomers as was already mentioned. Turnover is inevitable in an organization and that means that eventually there will be a point where the person who wrote the initial code is no longer at the company. Touching that code is a pretty big liability if no one really understands how it works and that bogs down productivity a ton. Another reason why sometimes rewriting something is the right answer.

What do you feel destroys “liberty” about planning and documentation?

That hasn’t been my experience (in general; had some bad companies for sure).

It just takes time, a lot of time. And meetings, endless meetings about what to make and how. Constant reviews of the progress and the code. And documenting everything.

I don't think, that this is necessarily bad. I even think, that this is a must for a large team. But it changes the way you code.

Right now I have the time and opportunity to 'form' the code the way I want. I can try different approaches, rip out or rewrite bad code and add features as I see fit. That's what I call liberty. I don't feel like a raw coder. Instead I feel like an artist in my own universe I where I'm in charge.

This feeling can get lost, when you need to request, plan, control and review every single change in coordination with multiple team members. You're not in charge anymore. You're not the artist, but a cog in the wheel.

I think some people like one way or the other. But it's hard to transition.

None of this is impossible in an organization where you are expected to document your work once it's finished!

> Instead I feel like an artist in my own universe I where I'm in charge.

But, but: it's not actually your universe, and you aren't actually in charge.

In practice, rewriting bad code and adding features "as you see fit" is roughly the same as going rogue. If the bad code works, then whether to rewrite it (and when) comes down to cost/benefit, and some engineer exercising their "liberty" is unlikely to get that right. The features some engineer decides to implement may be features that neither the organisation or its customers need; but someone will still have to be designated to maintain (or remove) them.

If you want liberty, start your own organisation.

> If you want liberty, start your own organisation.

Over the years, I’ve discovered a that what I really value is fully grasping a problem domain, deciding what customer problems are worth solving, and then aligning a team on a common vision of appropriate systems architecture to solve those problems. As a result I’ve ended up doing exactly this: I tend to move to organizations where I am at liberty to do this while still having the role of an individual contributor.

To my way of thinking documenting the work is vitally important, even more important than planning in some respects. Or maybe we could say planning is just another form of documenting what we're doing (or trying to do).

Sure, writing code is the stimulating creative part. And purifying code, making it elegant, polishing the creation to a brilliant sheen is highly rewarding. By contrast, documenting what's been done is tedious, boring, a gigantic pain, a total drag. Yet if it's not adequately documented all that creative effort will inevitably amount to nothing but a reason to hate its creator.

Furthermore, is it really possible to write superb documentation for lousy code? The effort to document the work is a kind of quality check on the work.

Can't say how many times it's come back to bite me where it hurts. Looking at stuff I finished 6 months, or God forbid, 6 years ago, poorly documented programs invariably prompt a shameful recognition that I have no idea what the hell I did. At least when someone else wrote it I can justify feeling indignant at the "mess" I have to figure out. But when it's my own, that's just sad.

Of course the work we leave behind (at the end of a job, retirement, etc.) will usually be resumed by someone. Excellent documentation is our finest legacy. Consider how it supports moving a project forward when the code's author isn't there to "explain" how it works.

And if we're honest with ourselves, writing cogent documentation is hard, often much harder than writing code which is why it's such a brutal task. OTOH doing something hard is a good reason to tell oneself "A big accomplishment! Good for me!" Something to feel good about!

A rule I aim to live by: the workday isn't over until I record what I just did and the reasons for doing it the way it was done.

I find it easier to document everything when I picture myself returning to it, and not remembering how to even run it locally. I'm not a fan of extensive documentation (neither when writing nor when reading), but I try to always communicate with future self how to proceed. Strangely enough, this seems to help others too. :-) On code reviews I also push back on anything that I can't use from reading the docs. If I, as a reviewer, don't know how to use an API, what chance does the next dev have?

Sound like a solid approach. No surprise your documentation helps everyone including yourself, all of us are truly in the same boat. Now the trick is convincing other programmers to do what you do, if they did the world would indeed be a much better place. ;)

That's what the second part (code reviews) is about. "Can you explain to me how to run this? Actually, can you just write it down and put it in this README?" But yes, it is an ongoing struggle. :-)

Meetings are like a stupid sort. You can figure everything out after an infinite number of them.

A well run series of meetings is like a bubble sort.

In my experience, lack of planning and docs strictly reduces liberty, because everyone is afraid to do anything but the most conservative thing, even when more radical work is clearly needed.

Matches my experience. I've lost count of the number of times I've seen people ask "why did they decide to do it this way" or "does this value in the test meet some requirement, or is it a bug?", without finding an answer because it is not documented and whoever did it left the company years ago.

If your options are fully vested by that time, there is a fair chance to find another company at the same stage of growth.