Hacker News Reader

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?

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.

> 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

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".

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

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