Hacker News new | ask | show | jobs
by danbruc 46 days ago
The source code is not the specification, the source code is an implementation of the specification. The specification tells you what happens, the source code tells you how it happens. Ideally you also have some additional documentation for the why.
1 comments
Twey 46 days ago
As any four-year-old can tell you, ‘why’ is infinitely recursive. ‘What’ from the perspective of level n is ‘how’ looking down from level n+1 and ‘why’ looking up from level n-k.
link
danbruc 46 days ago
That usually does not matter in practice because you quickly reach a level of sufficient understanding.

We usually use UUIDs for this type of object but we have to send those objects to the legacy system XYZ, which only supports IDs with up to sixteen characters and is case insensitive, so we generate sixteen character random alphanumeric strings with uppercase letters which provides 82 bits of entropy.

Could you go deeper? Sure. Why do we have to send those objects to XYZ? Why does the legacy system still exist? Why does it not support UUIDs? Why is there no secondary key specifically for that system? Why are we using UUIDs?

But most likely you do not have to spell all those out. The point of a why is to explain why something is not what one would expect, you explain on top of some common knowledge. Everyone involved might know what XYZ does and why some objects have to get send there. If not, that is probably written down elsewhere. Why is the system using UUIDs? Maybe written down in the design for the persistence layer.

link
Twey 45 days ago
Sure, I'm not suggesting we need to go into infinite regress for every explanation! I'm saying that you should bear in mind that you _are_ in the middle of an infinite stack, and what is a ‘how’, a ‘what’ or a ‘why’ is just a function of your current position in it relative to the thing you're talking about. In the ID generation code you might want to explain why you're using this weird format here instead of a more standard format (because it needs to be passed to legacy system XYZ). But if you go up a step or two to where the ID is passed to XYZ in code, that ‘why’ has become a ‘what’ — the calling code acts as a ‘specification’ for the behaviour of that ID generation code.
link