Hacker News Reader

Comment by gavinhoward | Hacker News Reader

I am one of the programmers that like to make dissectable code. In fact, I've included a whole manual, with my most famous project, that is entirely about dissecting the code. [1]

And I will certainly do the same in my current project.

Some of the most delightful moments I've had are when someone emails me with questions that indicate they've read my code, such as mentioning specific comments or asking about something in that dissection manual.

I consider it a badge of honor if people think my code is good enough to study.

[1]: https://git.gavinhoward.com/gavin/bc/src/commit/75cf2e3358b5...

View on HN

I think if we sat over beers we’d find some common ground.

I sometimes like to think of good code as short stories. Badly factored code is like a novelization of a story. Too long with too many side quests and you only find out at the end that the butler didn’t do it. Whether that pleases or infuriates is a gamble.

Excessively terse code that requires broad life experiences to unpack? It’s interpreted by every observer to mean something different. Like a haiku, or even a song, the story being told is unclear. Beautiful, moving, but unclear.

I much prefer short stories. A little flavor text, but no time for more than two clever ideas at once.

I think we would find common ground, yes. That would be fun! But I'll be the designated driver and stay sober. :)

I've often thought that code should tell a story about what the system is supposed to do and if the story is not clear, that will probably be reflected in a system that does not work well.

> I think if we sat over beers we’d find some common ground.

I love this response and wish every disagreement could start with this perspective.

code is such a weird thing. Its business logic, its infrastructure, its short stories, its documentation. I also think of it like investments and debts

its so many things and so complicated.

Code is just an analog for life and its duality.

Its all those things and none of those things.

Code is code. Humans are the ones with the obsession of abstracting and categorizing things to make ourselves feel better. In reality, none of those things actually exist

It's also really bad contract law.

when you think you have a good story to tell you will make it work no matter what.

Epic poems like The Iliad or Baghavad Ghita or the bible are not immaculately retold from scratch but depend heavily on repetition and context cues.

Code is the same.

I like that the whole project seems to be motivated out of spite for a particular individual on IRC.

Heh, yeah.

Although that person was actually mostly right about me; that project is the only real success I've had in my line except getting married and staying married. (And quite frankly, that's just because my wife seems to like me more than I deserve.)

Family > computers. Besides, what portion of people get any of their programs pulled into even a single other project?! An accepted PR is more than 99% of the world will ever contribute to software development!

We probably owe the existence of a nontrivial amount of software to a lot of stupid pointless IRC arguments :P

I quite like https://docs.arc42.org/ for a good framework regarding documentation of software projects. Section 8 is especially useful https://docs.arc42.org/section-8/ with nice topic suggestions.

Just had a look. That is a wonderful intro document for your code base.

Thank you very much!

Inspiring

Reply on news.ycombinator.com