https://docs.all-hands.dev/ logo
Join Slack
Powered by
another thing that I think will be generally helpf...
# proj-agent-canvas
n
another thing that I think will be generally helpful to the team as a whole ..... have a list of variable names, types, and content that spans the product.. as in: > if you use the variable 'mcp_name' it should be a string/varchar bounded to (Nchars) and should contain the unstyled string representation of the label associated with the 
MCP_CONNECTION_ID
lookup key .... you can store that string as whateverthehell you want internally if you wish, ... we're not sayin you must use this variable name to store this variable value ..... but rather saying > These variable names have significance across many facets of our plumbing and componentry..... and we want to help ensure that your muscle memory from working on one part of the stack will not HURT you while working within another A great example of WHY I'm offering this guidance:
in some data systems, there's a datatype for 
UUID
.... in others, there are not.
in systems where there isn't.... one often sees a uuid value stored as an Nchar string .... which ... sure whatever.
a problem manifested which took a LOT MORE eng resources than it arguably should have to identify .... because of the ways our brains work
SPROCKETS A, B, and C all interoperate on the servicing of a GIZMO.... SPROCKET A generates the GIZMO's ID.... and stores the id as SPROCKET_A's ' handle for the data struct relating to said GIZMO....
SPROCKET A connects to SPROCKET C and stores a relationship between WIDGET_123 and GIZMO_N
SPROCKET B connects to SPROCKET C, fetches a row relating to WIDGET_123 and shits the bed.
the underlying problem was SPROCKETA, SPROCKETB and SPROCKETC all called the string identifier of that datastruct '`GIZMO_ID`' HOWEVER... SprocketB used the datatype 
UUID
and SPROCKETS A and B used Nchar varchar ....
not all valid N_char varchar strings are valid UUIDs 🙂
this aint rocket science, of course ... but NOBODY paused to ask if the datatype was the same because it was a mental shortcut everyone overlooked.
SO.... adopting a SHORT list of 'we are consciously leveraging the consistency of this stringlabel to associate an implicit datatype and significance across the entirety of the tool to make everyones' lives less painful at 0300 when shits broke and we're trying to figure out what's wrong .... . it's easy to go too far with this concept .... and undermine a significant portion of the value of microservice independence ..... so it should be used sparingly ..... but.... there ARE certain scenarios wherin one may want to be able to consistently reference a thing across multiple orthogonal constructs and contexts
[= the opinions shared here are just my damned stinkin opinions and should be consumed with as much salt as you deem appropriate.. because what the hell do I know? 🙂 =]
c
Good point! Yes, I always look for some consistency across names, types, usages, but there's a lot of room to improve
n
having a 'these variables are important to the entire platform / myriad components and so they're reserved/have explicit meaning.... ' list has a few downsides .... here's how this can bite you: you are now asserting an explicit 'truth' in perpetuity. enforcing and maintaining this truth becomes a bit of a chore at times... you must curate an exceptions list (because there's always an exception) Am implicit truth/promise has a little more wiggle room... as you're not overtly saying THIS WILL ALWAYS BE ... making sure that peeps are aware of this, and keeping it clear/clean in PRs etc... can become tedious .... documenting the WHY this was decided is important, so that you have a mechanism of evaluating if the initial reasons are still true .... (coz IDK about you, but I can barely remember what I was doing last week, much less 9 mos ago 😉 )
Open in Slack
PreviousNext
Powered by