Hacker News Reader

Comment by nosefurhairdo | Hacker News Reader

I've handed off a few services I built with minimal oversight or documentation. The receiving teams have been able to make changes without my involvement and everyone is happy.

I believe the only reason I've been successful in this is because I agonize over simplicity. There are times during the development of any project where one might be tempted to hack around an issue, or commit the ugly code that seems to work. These are the rough edges that inheritors of a codebase use as evidence that a blank slate would be preferable. They're also the bits where the underlying business logic becomes murky. My goal is for the code to be so clear that documentation would feel redundant.

This approach of course takes more time and requires that your management trusts you and is willing to compromise on timelines. It's extremely rewarding if you can sell it and deliver.

View on HN

I have the same experience, and I agree that simplicity leads to success. The more things software can do, the harder it is to reason about what it's supposed to do. It's very much the IQ bell curve meme: junior developers only solve the problem at hand, mid-level developers build powerful, but complex frameworks which can solve the problem at hand but also potential future problems, and senior "X10" developers only solve the problem at hand.

> There are times during the development of any project where one might be tempted to hack around an issue, or commit the ugly code that seems to work. These are the rough edges that inheritors of a codebase use as evidence that a blank slate would be preferable.

Yes, one thing I've learned is to never underestimate the power of inertia in a codebase. When adding functionality, 99% of developers will go for the path of least resistance, which is mimicking whatever patterns already exist. To loop back to the article, this is often due to lack of full understanding; the default assumption is that because something is written in a certain way, that it's the best way. This isn't true; it may not even be the correct way! But copying what already exists has an element of safety built into it, without needing to spend the effort to deeply understand existing code (which tends to be developers' least favorite activity).

So if you put in an ugly hack, or have a code structure which doesn't make sense, expect that to persist for years, or decades.

I don’t think it’s up to the developers only to decide. If we are working in a sprint, if all my manager cares about is “shipping impact”, then I’m not going to spend time on things that won’t benefit me in my performance review. I’ll take the shortcuts. Now, if management knew what we know, sure certainly everyone would benefit from that… but that’s not the real world.

> without needing to spend the effort to deeply understand existing code

Or, more importantly, explain to others why you're deviating from "standard"

Deviating from the "standard" can make it harder for another maintainer to understand what's going on.

IMO setting up reasonable patterns for others to follow is part of a good design. I'm not saying that I personally am great at it - it's an ideal!

I think you are right though - very non-understandable things tend to persist because nobody wants to touch them.

> IMO setting up reasonable patterns for others to follow is part of a good design.

Which is why we used to study a book called Design Patterns.

What you've said echoes the concept behind the quote "I didn’t have time to write you a short letter, so I wrote you a long one." This, or some variation of it, has been around for quite a while. I think this reveals a fundamental truth about knowledge based work that is inherent to humans. Purposeful simplicity is harder than accidental complexity.

> This approach of course takes more time and requires that your management trusts you and is willing to compromise on timelines.

I would say that most management and even most programmers don't see the value in this. In my experience focusing on simplicity gives much better long-term results but it has higher and more unpredictable upfront cost. Blasting code onto main is seen as being more productive even though long-term it seems to have much higher overall costs.

Documentation is useful, when done well. The code is always the authority, and there are very many ways the correct logic can be constructed. How it is constructed is the difference between good enough and excellent.

And getting "compromise on timelines" is a most sublime political art. It requires the combination of both a humble, competent manager and an established, successful engineer worthy of trust.

Congratulations on your success on those two varied fronts!

I think it depends on who the documentation is intended for. I often let public facing documentation be the source of truth for expected behavior unless it's infeasible to coerce the system to that behavior. If the latter does occur, the documentation gets updated.

If the question is what does the software actually do, then of course the code, toolchain, and runtime are the authority.

Good point. I was only speaking to targeting other developers.

Thank you! I am indeed very fortunate to have a great manager.

It needs to answer the "why" question most IMO. I can read code and see "how" and perhaps guess "what" but the "why" is missing.

It also doesn't have to be that detailed - just a one line comment at the top of a file saying why it's there and what for can make an immense difference to the time it takes to understand code.

Class comments are great too if they have in them everything that's NOT in a ChatGPT summary :-). i.e. I can paste code into ChatGPT myself to get a summary if I really wanted to so I don't need that - but I need all the things it doesn't tell you which is basically why the class exists and what it's intended for.

The lower down the hierarchy it goes the less comments matter IMO.

simplicity is a noble ambition, but let it not impede progress, for it is subjective and subject to discretion. The art to be learned and practiced is knowing when to cut corners and where to be relentless with yourself and demand that of others.

Getting v0.1 out, albeit with murky code and iterating to v2.5 with 10 paying customers is the way to progress. The hard, non-science part is getting management to spend billable hours for no short term benefit. Thats the key skill.

> I've handed off a few services I built with minimal oversight or documentation. The receiving teams have been able to make changes without my involvement and everyone is happy.

I struggle to believe this. Perhaps my personal situation, inheriting a 150k line embedded C programme, which started sprouting weird bugs when ported from X86 -> ARM.

> minimal oversight or documentation

Why? Why do you not have documentation?

> I've been successful in this is because I agonize over simplicity

I will break this down: "I've been successful in this " I do not believe this statement

> I agonize over simplicity

I wonder if the subordinates in your organisation who are not allowed to criticise you, wish you had agonised over documentation (I do not know what power you have over the folks who follow you, I am hypothesising it is a lot)

Documentation is very hard. It is harder than writing code because there is no parsing of documentation, no demonstration of correctness.

Inaccurate, or lazy, documentation can be worse than useless, but no documentation condemns the system to a slow death

I wish my fellow computer programmers would stop making excuses for not doing the extremely hard work of documenting what they were thinking they were doing when they (inevitably) did something slightly differnent

> Why? Why do you not have documentation?

> Documentation is very hard. It is harder than writing code because there is no parsing of documentation, no demonstration of correctness.

You answered your own question :)

> You answered your own question :)

So "do not do the hard parts"?

That is very unprofessional

Achieving desired result is professional. And achieving desired result without doing the hard parts is not only professional, but smart and actually kind of awesome.

> Achieving desired result is professional.

No. It is geeking out, part of the job...

> achieving desired result without doing the hard parts is not only professional, but smart and actually kind of awesome.

That is a menace. I think I am working on code you wrote

It is the opposite of professional. It is amateur, irresponsible dilettantism

"Professional" is doing what they're paying you for, end of story.

Most employers have less than zero interest in paying coders to document in my experience. If they want documentation to exist, they hire a technical writer.

Sadly, I've never met an employed tech writer (and no, journalists don't count).

You're not being paid to document, you're being paid for writing maintainable code (in decent places at least) and it's your job as a professional to decide how much documentation that includes. In my opinion the idea that good code is "self-documenting" is a myth.

> ...to fight and conquer in all your battles is not supreme excellence; supreme excellence consists in breaking the enemy’s resistance without fighting

There is a limited time available. The root comment was getting success with other means. Adding good documentation would have costed much more time. That might have made their projects less successful in this case.

> Adding good documentation would have costed much more time

That is the problem

Not that it is true, it is not, for many reasons. It is a problem that is believed

costed more = it would take time. you have magic ways in which good documentation can be created without any time at all allocated to the effort?

The cheapest time to add documentation is when you have the information in your head because you just worked on it. Nobody is demanding an essay for every method, but just write down what went through your head when you implemented weird hack #17 or found out that the API you're calling does something surprising.

The main challenge is that you would need to write the documentation for a person who might have never used this particular software before.

The information that is in your head might be nonsense for this person, and there is chance that it is not reducing the time it takes to understand in a meaningful way.

It's a best effort thing - as anything in software.

waste of time too

Unprofessional to who, exactly? Like a sister comment says, an understandable system was built, so it seems like a strong professional relationship existed.

Every codebase is going to have different definitions of "professional standards".

Totally fair to be skeptical; there's no way I can convince you that my coworkers would agree with what I've claimed here. I do still interact with many of the folks that inherited my code though, and on multiple occasions they've expressed how my services have been easier to work on than others.

Will also note I have no subordinates. In most cases I've handed these services off to teams with more seniority/higher rank than myself.

Re: documentation, I suspect the embedded C and adjacent systems you work on warrant docs more than the web app plumbing work that I do. I've done brief write-ups with some diagrams, but I wouldn't know how to document further without just restating what is already clear from the code.

I somewhat agree with you, I don't understand the disdain many programmers have for documentation.

Every company I've worked had parts of the codebase that were full of complicated business logic whose purpose was totally non-obvious, or complex interactions with outside APIs etc. I took care to document those things carefully so they would be understandable.

> I somewhat agree with you, I don't understand the disdain many programmers have for documentation.

I also agree with this person for the most part. For all I know the original poster might indeed be successful with their approach, but in general having docs of some sort is a good idea.

I think most devs have the sometimes mistaken belief (coupled with some arrogance/cargo culting) that code should be self-documenting, skipping over the part where they can document WHAT but not the WHY in as much detail as would be needed to tell the full story.

Sometimes a simple comment explaining the basis for doing things a certain way, a Markdown README/ADR in the same repo, or even a link to a particular Jira issue (to even indicate that one with useful stuff exists, in the midst of thousands of others) will all be better and save someone a headache in the case of them missing out on important context.

The correct amount of documentation is as little as you can get away with (without being apathetic or ignorant of the developer experience of others in the project that don't know all that you do), but not zero. The code naming conventions and structure, as well as even code tests (both correctness, how it should work and how to use it) and any automation (e.g. Dockerfiles that detail the dependencies, or something like Ansible playbooks that detail the needed environment, or systemd service file definitions, or even your project files and build scripts) might explain a lot about it, but not all.

The bugs coming from porting from X86 to ARM may be related to memory order. ARM has weaker memory order than X86. You may need to add memory barriers or synchronization. Of course there are other causes.

With no further context, I think good ol' UB is more likely. Every C codebase I've seen that's not scrutinized with tooling to detect UB, is full of UB.

> tooling to detect UB

My tooling is not showing anything.

What tooling do you recommend?

Reply on news.ycombinator.com