{"type":"doc","content":[{"type":"panel","attrs":{"panelColor":"#E6FCFF","panelType":"custom"},"content":[{"type":"paragraph","content":[{"text":"Tip VP1","type":"text","marks":[{"type":"code"}]}]},{"type":"paragraph","content":[{"text":"It can be easy for many programmers to fall back to naming variables based on the particular programming constructs available in a programming environment. However, for ","type":"text"},{"text":"all of the reasons mentioned previously","type":"text","marks":[{"type":"link","attrs":{"href":"https://edensoftlabs.atlassian.net/wiki/spaces/edensoftlabs/pages/90538081"}}]},{"text":", prefer naming variables in the problem domain over the solution domain.","type":"text"}]}]},{"type":"paragraph","content":[{"text":"Examples:","type":"text"}]},{"type":"extension","attrs":{"layout":"default","extensionType":"com.atlassian.confluence.macro.core","extensionKey":"navitabs-tab-wizard","parameters":{"macroParams":{"__bodyContent":{"value":"{\"type\":\"custom\",\"custom\":{\"tabs\":[{\"id\":\"1371cc10-133a-4dad-afc9-3cc35bc04d16\",\"label\":\"C++\",\"type\":\"your-content\",\"body\":{\"version\":1,\"type\":\"doc\",\"content\":[{\"type\":\"heading\",\"attrs\":{\"level\":1},\"content\":[{\"type\":\"text\",\"text\":\"Example 1 - Avoiding solution “key” and “value” terminology\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Original code with poor names focused on the solution domain:\",\"marks\":[{\"type\":\"strong\"}]}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"c++\"},\"content\":[{\"type\":\"text\",\"text\":\"const std::string KEY = \\\"PROGRAM_FILEPATH\\\";\\nstd::string value = std::getenv(KEY.c_str());\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Environment variables are typically stored in some kind of “map” data structure, which conventionally has “keys” that can be used to look up particular “values.” Such terminology is used in the code above, but it doesn’t communicate any meaning of the actual data to a reader.\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Improved problem domain names: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"Names rooted in the problem domain at the level of abstraction for this particular code are better. The reader now knows that what is being looked up is based on an “environment variable name”, so he/she can actually go explore a computer system outside the code to see what that environment variable might be. The value retrieved from the environment variable is now more self-evident from the \"},{\"type\":\"text\",\"text\":\"program_filepath\",\"marks\":[{\"type\":\"code\"}]},{\"type\":\"text\",\"text\":\" name.\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"c++\"},\"content\":[{\"type\":\"text\",\"text\":\"const std::string PROGRAM_FILEPATH_ENVIRONMENT_VARIABLE_NAME = \\\"PROGRAM_FILEPATH\\\";\\nstd::string program_filepath = std::getenv(\\n PROGRAM_FILEPATH_ENVIRONMENT_VARIABLE_NAME.c_str());\"}]},{\"type\":\"heading\",\"attrs\":{\"level\":1},\"content\":[{\"type\":\"text\",\"text\":\"Example 2 - Providing more meaning than “input” and “output”\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Original code with a name overly focused in the solution domain: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"This name is focused on the process of the code itself having \\\"inputs\\\" and expected \\\"outputs,\\\" along with the \\\"map\\\" data structure, without any communication of problem domain meaning for this data:\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"c++\"},\"content\":[{\"type\":\"text\",\"text\":\"const std::map INPUT_TO_OUTPUT_TEXT_MAP = \\n{\\n { \\\"Hello\\\", \\\"Hola\\\" },\\n // ...\\n};\\nTestTextTranslation(INPUT_TO_OUTPUT_TEXT_MAP);\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Improved problem domain name: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"This name now communicates the problem domain meaning of the data:\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"c++\"},\"content\":[{\"type\":\"text\",\"text\":\"const std::map ORIGINAL_TEXTS_WITH_TRANSLATED_TEXTS = \\n{\\n { \\\"Hello\\\", \\\"Hola\\\" },\\n // ...\\n};\\nTestTextTranslation(ORIGINAL_TEXTS_WITH_TRANSLATED_TEXTS);\"}]},{\"type\":\"heading\",\"attrs\":{\"level\":1},\"content\":[{\"type\":\"text\",\"text\":\"Example 3 - More specific problem domain information than “result”\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Original code with a name overly focused in the solution domain: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"The variable for the return value is very generic, focusing on the solution of running a command and some \\\"result\\\" being returned from that:\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"c++\"},\"content\":[{\"type\":\"text\",\"text\":\"std::string command_result = Command::RunAndGetStandardOutput(\\n get_service_logs_command);\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Improving the name to be rooted more in the problem domain: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"From the function call, we can see that \\\"standard output\\\" is returned, so including at least \\\"output\\\" would be one step in improving the name. However, we can go one step further in orienting this variable name in the problem domain. If the intent of the command is to get the logs of a service, then the natural standard output would be those logs, so we can name the variable for the return value after that.\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"c++\"},\"content\":[{\"type\":\"text\",\"text\":\"std::string service_logs = Command::RunAndGetStandardOutput(\\n get_service_logs_command);\"}]},{\"type\":\"heading\",\"attrs\":{\"level\":1},\"content\":[{\"type\":\"text\",\"text\":\"Example 4 - Identifying the type of binary data in an array\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Original code with a name overly focused in the solution domain: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"This is a very literal interpretation of what the code itself is doing in the variable name. \\\"Byte\\\" may be fine in some circumstances, but \\\"array\\\" is almost certainly thinking about the particular way these bytes are stored in the code, which may change or be unnecessary in code that is just trying to specify binary bytes for something.\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"c++\"},\"content\":[{\"type\":\"text\",\"text\":\"constexpr std::array BYTE_ARRAY = \\n{\\n // ...\\n};\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Improved name to identify the problem domain meaning of this particular data: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"The variables name has been improved to more specifically identify the meaning of the array of bytes in the problem domain (related to image data in this case).\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"c++\"},\"content\":[{\"type\":\"text\",\"text\":\"constexpr std::array BITMAP_IMAGE_DATA_BYTES = \\n{\\n // ...\\n};\"}]},{\"type\":\"heading\",\"attrs\":{\"level\":1},\"content\":[{\"type\":\"text\",\"text\":\"Example 5 - Avoiding the solution domain “iterator” word\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"This is an example showing one way some data might be serialized into a particular binary format. The first byte of the serialized data contains the length (in bytes) of the string, with subsequent bytes containing the actual string's character bytes.\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"The initial setup code for this is immediately below (before contrasting bad/good examples later down):\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"c++\"},\"content\":[{\"type\":\"text\",\"text\":\"constexpr std::size_t SERIALIZED_DATA_BUFFER_SIZE = 255;\\nconst std::string TEXT = \\\"Some Text\\\";\\nstd::vector serialized_data_buffer(SERIALIZED_DATA_BUFFER_SIZE);\\nserialized_data_buffer.at(0) = static_cast(TEXT.length());\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Original code with a name overly focused in the solution domain: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"\\\"Iterator\\\" is a very computer-science word, and this particular variable name is focused entirely on that in relation to some \\\"entry\\\" in a container.\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"c++\"},\"content\":[{\"type\":\"text\",\"text\":\"auto iterator_at_second_entry = std::begin(serialized_data_buffer) + 1;\\nstd::copy(std::begin(TEXT), std::end(TEXT), iterator_at_second_entry);\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Improved name shifted to be more in the problem domain: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"The below variable name has been improved to communicate more of the core \\\"what\\\" in the problem domain of this code and also uses a less computer science-specific term than \\\"iterator.\\\" In many cases, iterators are like pointers, so you want to name them in reference to what they point to. However, in cases where the notion of some \\\"position\\\" within a container is important to communicate, using more common words than \\\"iterator\\\" can help with understanding what is going on.\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"c++\"},\"content\":[{\"type\":\"text\",\"text\":\"auto serialized_data_buffer_text_start_position = \\n std::begin(serialized_data_buffer) + 1;\\nstd::copy(\\n std::begin(TEXT), \\n std::end(TEXT), \\n serialized_data_buffer_text_start_position);\"}]},{\"type\":\"heading\",\"attrs\":{\"level\":1},\"content\":[{\"type\":\"text\",\"text\":\"Example 6 - Avoiding “predicate” and “function” words\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Original code with names overly focused in the solution domain: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"Both \\\"predicate\\\" and \\\"function\\\" words are solution domain terms, and the names here overly focus on those without indications of what problem domain concepts are involved.\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"c++\"},\"content\":[{\"type\":\"text\",\"text\":\"auto predicate_function = [](int item_count)\\n{\\n constexpr int MAX_ITEM_COUNT = 10;\\n return item_count > MAX_ITEM_COUNT;\\n};\\nbool predicate_occurred = WaitForPredicate(\\n predicate_function, \\n WAIT_TIME_IN_SECONDS);\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Improved names focused more in the problem domain: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"The \\\"predicate\\\" and \\\"function\\\" terminology have been replaced with terms more focused on the problem domain of this code (items). The focus on some names have been changed to focus on concepts like \\\"conditions\\\" and \\\"time\\\" that would be more likely to be familiar to a non-programmer audience.\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"c++\"},\"content\":[{\"type\":\"text\",\"text\":\"auto check_if_max_items_exceeded = [](int item_count)\\n{\\n constexpr int MAX_ITEM_COUNT = 10;\\n return item_count > MAX_ITEM_COUNT;\\n};\\nbool max_items_exceeded_within_wait_time = WaitForCondition(\\n check_if_max_items_exceeded, \\n WAIT_TIME_IN_SECONDS);\"}]},{\"type\":\"paragraph\",\"content\":[]}]},\"fullName\":\"C++\",\"minHeight\":3725},{\"id\":\"ff4ea1d6-9b00-458b-804e-796574e744db\",\"label\":\"C#\",\"type\":\"your-content\",\"body\":{\"version\":1,\"type\":\"doc\",\"content\":[{\"type\":\"heading\",\"attrs\":{\"level\":1},\"content\":[{\"type\":\"text\",\"text\":\"Example 1 - Avoiding solution “key” and “value” terminology\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Original code with poor names focused on the solution domain:\",\"marks\":[{\"type\":\"strong\"}]}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"csharp\"},\"content\":[{\"type\":\"text\",\"text\":\"const string KEY = \\\"PROGRAM_FILEPATH\\\";\\nstring value = Environment.GetEnvironmentVariable(KEY);\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Environment variables are typically stored in some kind of “map” data structure, which conventionally has “keys” that can be used to look up particular “values.” Such terminology is used in the code above, but it doesn’t communicate any meaning of the actual data to a reader.\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Improved problem domain names: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"Names rooted in the problem domain at the level of abstraction for this particular code are better. The reader now knows that what is being looked up is based on an “environment variable name”, so he/she can actually go explore a computer system outside the code to see what that environment variable might be. The value retrieved from the environment variable is now more self-evident from the \"},{\"type\":\"text\",\"text\":\"programFilepath\",\"marks\":[{\"type\":\"code\"}]},{\"type\":\"text\",\"text\":\" name.\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"csharp\"},\"content\":[{\"type\":\"text\",\"text\":\"const string ProgramFilepathEnvironmentVariableName = \\\"PROGRAM_FILEPATH\\\";\\nstring programFilepath = Environment.GetEnvironmentVariable(\\n ProgramFilepathEnvironmentVariableName);\"}]},{\"type\":\"heading\",\"attrs\":{\"level\":1},\"content\":[{\"type\":\"text\",\"text\":\"Example 2 - Providing more meaning than “input” and “output”\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Original code with a name overly focused in the solution domain: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"This name is focused on the process of the code itself having \\\"inputs\\\" and expected \\\"outputs,\\\" along with the \\\"map\\\" data structure, without any communication of problem domain meaning for this data:\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"csharp\"},\"content\":[{\"type\":\"text\",\"text\":\"var inputToOutputTextMap = new Dictionary\\n{\\n { \\\"Hello\\\", \\\"Hola\\\" },\\n // ...\\n};\\nTestTextTranslation(inputToOutputTextMap);\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Improved problem domain name: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"This name now communicates the problem domain meaning of the data:\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"csharp\"},\"content\":[{\"type\":\"text\",\"text\":\"var originalTextsWithTranslatedTexts = new Dictionary\\n{\\n { \\\"Hello\\\", \\\"Hola\\\" },\\n // ...\\n};\\nTestTextTranslation(originalTextsWithTranslatedTexts);\"}]},{\"type\":\"heading\",\"attrs\":{\"level\":1},\"content\":[{\"type\":\"text\",\"text\":\"Example 3 - More specific problem domain information than “result”\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Original code with a name overly focused in the solution domain: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"The variable for the return value is very generic, focusing on the solution of running a command and some \\\"result\\\" being returned from that:\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"csharp\"},\"content\":[{\"type\":\"text\",\"text\":\"string commandResult = Command.RunAndGetStandardOutput(getServiceLogsCommand);\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Improving the name to be rooted more in the problem domain: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"From the function call, we can see that \\\"standard output\\\" is returned, so including at least \\\"output\\\" would be one step in improving the name. However, we can go one step further in orienting this variable name in the problem domain. If the intent of the command is to get the logs of a service, then the natural standard output would be those logs, so we can name the variable for the return value after that.\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"csharp\"},\"content\":[{\"type\":\"text\",\"text\":\"string serviceLogs = Command.RunAndGetStandardOutput(getServiceLogsCommand);\"}]},{\"type\":\"paragraph\",\"content\":[]}]},\"fullName\":\"C#\",\"minHeight\":3725},{\"id\":\"61c39a07-de01-44ba-be6d-4210322d3bc4\",\"label\":\"Java\",\"type\":\"your-content\",\"body\":{\"version\":1,\"type\":\"doc\",\"content\":[{\"type\":\"heading\",\"attrs\":{\"level\":1},\"content\":[{\"type\":\"text\",\"text\":\"Example 1 - Avoiding solution “key” and “value” terminology\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Original code with poor names focused on the solution domain:\",\"marks\":[{\"type\":\"strong\"}]}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"java\"},\"content\":[{\"type\":\"text\",\"text\":\"final String KEY = \\\"PROGRAM_FILEPATH\\\";\\nString value = System.getenv(KEY);\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Environment variables are typically stored in some kind of “map” data structure, which conventionally has “keys” that can be used to look up particular “values.” Such terminology is used in the code above, but it doesn’t communicate any meaning of the actual data to a reader.\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Improved problem domain names: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"Names rooted in the problem domain at the level of abstraction for this particular code are better. The reader now knows that what is being looked up is based on an “environment variable name”, so he/she can actually go explore a computer system outside the code to see what that environment variable might be. The value retrieved from the environment variable is now more self-evident from the \"},{\"type\":\"text\",\"text\":\"programFilepath\",\"marks\":[{\"type\":\"code\"}]},{\"type\":\"text\",\"text\":\" name.\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"java\"},\"content\":[{\"type\":\"text\",\"text\":\"final String PROGRAM_FILEPATH_ENVIRONMENT_VARIABLE_NAME = \\\"PROGRAM_FILEPATH\\\";\\nString programFilepath = System.getenv(PROGRAM_FILEPATH_ENVIRONMENT_VARIABLE_NAME);\"}]},{\"type\":\"heading\",\"attrs\":{\"level\":1},\"content\":[{\"type\":\"text\",\"text\":\"Example 2 - Providing more meaning than “input” and “output”\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Original code with a name overly focused in the solution domain: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"This name is focused on the process of the code itself having \\\"inputs\\\" and expected \\\"outputs,\\\" along with the \\\"map\\\" data structure, without any communication of problem domain meaning for this data:\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"java\"},\"content\":[{\"type\":\"text\",\"text\":\"Map inputToOutputTextMap = new HashMap<>();\\ninputToOutputTextMap.put(\\\"Hello\\\", \\\"Hola\\\");\\n// ...\\ntestTextTranslation(inputToOutputTextMap);\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Improved problem domain name: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"This name now communicates the problem domain meaning of the data:\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"java\"},\"content\":[{\"type\":\"text\",\"text\":\"Map originalTextsWithTranslatedTexts = new HashMap<>();\\noriginalTextsWithTranslatedTexts.put(\\\"Hello\\\", \\\"Hola\\\");\\n// ...\\ntestTextTranslation(originalTextsWithTranslatedTexts);\"}]},{\"type\":\"heading\",\"attrs\":{\"level\":1},\"content\":[{\"type\":\"text\",\"text\":\"Example 3 - More specific problem domain information than “result”\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Original code with a name overly focused in the solution domain: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"The variable for the return value is very generic, focusing on the solution of running a command and some \\\"result\\\" being returned from that:\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"java\"},\"content\":[{\"type\":\"text\",\"text\":\"String commandResult = Command.runAndGetStandardOutput(getServiceLogsCommand);\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Improving the name to be rooted more in the problem domain: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"From the function call, we can see that \\\"standard output\\\" is returned, so including at least \\\"output\\\" would be one step in improving the name. However, we can go one step further in orienting this variable name in the problem domain. If the intent of the command is to get the logs of a service, then the natural standard output would be those logs, so we can name the variable for the return value after that.\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"java\"},\"content\":[{\"type\":\"text\",\"text\":\"String serviceLogs = Command.runAndGetStandardOutput(getServiceLogsCommand);\"}]},{\"type\":\"paragraph\",\"content\":[]}]},\"fullName\":\"Java\",\"minHeight\":3725},{\"id\":\"a1cfcaf7-a8d0-47b4-ba6b-7904dcee3c73\",\"label\":\"Python\",\"type\":\"your-content\",\"body\":{\"version\":1,\"type\":\"doc\",\"content\":[{\"type\":\"heading\",\"attrs\":{\"level\":1},\"content\":[{\"type\":\"text\",\"text\":\"Example 1 - Avoiding solution “key” and “value” terminology\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Original code with poor names focused on the solution domain:\",\"marks\":[{\"type\":\"strong\"}]}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"python\"},\"content\":[{\"type\":\"text\",\"text\":\"KEY: str = 'PROGRAM_FILEPATH'\\nvalue: str = os.environ[KEY]\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Environment variables are typically stored in some kind of “map” data structure, which conventionally has “keys” that can be used to look up particular “values.” Such terminology is used in the code above, but it doesn’t communicate any meaning of the actual data to a reader.\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Improved problem domain names: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"Names rooted in the problem domain at the level of abstraction for this particular code are better. The reader now knows that what is being looked up is based on an “environment variable name”, so he/she can actually go explore a computer system outside the code to see what that environment variable might be. The value retrieved from the environment variable is now more self-evident from the \"},{\"type\":\"text\",\"text\":\"program_filepath\",\"marks\":[{\"type\":\"code\"}]},{\"type\":\"text\",\"text\":\" name.\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"python\"},\"content\":[{\"type\":\"text\",\"text\":\"PROGRAM_FILEPATH_ENVIRONMENT_VARIABLE_NAME: str = 'PROGRAM_FILEPATH'\\nprogram_filepath: str = os.environ[PROGRAM_FILEPATH_ENVIRONMENT_VARIABLE_NAME]\"}]},{\"type\":\"heading\",\"attrs\":{\"level\":1},\"content\":[{\"type\":\"text\",\"text\":\"Example 2 - Providing more meaning than “input” and “output”\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Original code with a name overly focused in the solution domain: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"This name is focused on the process of the code itself having \\\"inputs\\\" and expected \\\"outputs,\\\" along with the \\\"map\\\" data structure, without any communication of problem domain meaning for this data:\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"python\"},\"content\":[{\"type\":\"text\",\"text\":\"input_to_output_text_map: dict[str, str] = {\\n \\\"Hello\\\": \\\"Hola\\\",\\n # ...\\n}\\ntest_text_translation(input_to_output_text_map)\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Improved problem domain name: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"This name now communicates the problem domain meaning of the data:\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"python\"},\"content\":[{\"type\":\"text\",\"text\":\"original_text_with_translated_texts: dict[str, str] = {\\n \\\"Hello\\\": \\\"Hola\\\",\\n # ...\\n}\\ntest_text_translation(original_text_with_translated_texts)\"}]},{\"type\":\"heading\",\"attrs\":{\"level\":1},\"content\":[{\"type\":\"text\",\"text\":\"Example 3 - More specific problem domain information than “result”\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Original code with a name overly focused in the solution domain: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"The variable for the return value is very generic, focusing on the solution of running a command and some \\\"result\\\" being returned from that:\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"python\"},\"content\":[{\"type\":\"text\",\"text\":\"command_result: str = Command.run_and_get_standard_output(get_service_logs_command)\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Improving the name to be rooted more in the problem domain: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"From the function call, we can see that \\\"standard output\\\" is returned, so including at least \\\"output\\\" would be one step in improving the name. However, we can go one step further in orienting this variable name in the problem domain. If the intent of the command is to get the logs of a service, then the natural standard output would be those logs, so we can name the variable for the return value after that.\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"python\"},\"content\":[{\"type\":\"text\",\"text\":\"service_logs: str = Command.run_and_get_standard_output(get_service_logs_command)\"}]},{\"type\":\"paragraph\",\"content\":[]}]},\"fullName\":\"Python\",\"minHeight\":3725},{\"id\":\"528da6b6-a308-458c-8fd4-b3afdc4e0707\",\"label\":\"JavaScript\",\"type\":\"your-content\",\"body\":{\"version\":1,\"type\":\"doc\",\"content\":[{\"type\":\"heading\",\"attrs\":{\"level\":1},\"content\":[{\"type\":\"text\",\"text\":\"Example 1 - Avoiding solution “key” and “value” terminology\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Original code with poor names focused on the solution domain:\",\"marks\":[{\"type\":\"strong\"}]}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"javascript\"},\"content\":[{\"type\":\"text\",\"text\":\"const KEY = 'PROGRAM_FILEPATH';\\nconst value = process.env[KEY];\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Environment variables are typically stored in some kind of “map” data structure, which conventionally has “keys” that can be used to look up particular “values.” Such terminology is used in the code above, but it doesn’t communicate any meaning of the actual data to a reader.\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Improved problem domain names: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"Names rooted in the problem domain at the level of abstraction for this particular code are better. The reader now knows that what is being looked up is based on an “environment variable name”, so he/she can actually go explore a computer system outside the code to see what that environment variable might be. The value retrieved from the environment variable is now more self-evident from the \"},{\"type\":\"text\",\"text\":\"programFilepath\",\"marks\":[{\"type\":\"code\"}]},{\"type\":\"text\",\"text\":\" name.\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"javascript\"},\"content\":[{\"type\":\"text\",\"text\":\"const PROGRAM_FILEPATH_ENVIRONMENT_VARIABLE_NAME = 'PROGRAM_FILEPATH';\\nconst programFilepath = process.env[PROGRAM_FILEPATH_ENVIRONMENT_VARIABLE_NAME];\"}]},{\"type\":\"heading\",\"attrs\":{\"level\":1},\"content\":[{\"type\":\"text\",\"text\":\"Example 2 - Providing more meaning than “input” and “output”\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Original code with a name overly focused in the solution domain: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"This name is focused on the process of the code itself having \\\"inputs\\\" and expected \\\"outputs,\\\" along with the \\\"map\\\" data structure, without any communication of problem domain meaning for this data:\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"javascript\"},\"content\":[{\"type\":\"text\",\"text\":\"let inputToOutputTextMap = {\\n \\\"Hello\\\": \\\"Hola\\\",\\n // ...\\n};\\ntestTextTranslation(inputToOutputTextMap);\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Improved problem domain name: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"This name now communicates the problem domain meaning of the data:\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"javascript\"},\"content\":[{\"type\":\"text\",\"text\":\"let originalTextsWithTranslatedTexts = {\\n \\\"Hello\\\": \\\"Hola\\\",\\n // ...\\n};\\ntestTextTranslation(originalTextsWithTranslatedTexts);\"}]},{\"type\":\"heading\",\"attrs\":{\"level\":1},\"content\":[{\"type\":\"text\",\"text\":\"Example 3 - More specific problem domain information than “result”\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Original code with a name overly focused in the solution domain: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"The variable for the return value is very generic, focusing on the solution of running a command and some \\\"result\\\" being returned from that:\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"javascript\"},\"content\":[{\"type\":\"text\",\"text\":\"let commandResult = Command.runAndGetStandardOutput(getServiceLogsCommand);\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Improving the name to be rooted more in the problem domain: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"From the function call, we can see that \\\"standard output\\\" is returned, so including at least \\\"output\\\" would be one step in improving the name. However, we can go one step further in orienting this variable name in the problem domain. If the intent of the command is to get the logs of a service, then the natural standard output would be those logs, so we can name the variable for the return value after that.\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"javascript\"},\"content\":[{\"type\":\"text\",\"text\":\"let serviceLogs = Command.runAndGetStandardOutput(getServiceLogsCommand);\"}]},{\"type\":\"paragraph\",\"content\":[]}]},\"fullName\":\"JavaScript\",\"minHeight\":3725},{\"id\":\"a9427e99-277e-4cd2-8ace-b2448dca2fe1\",\"label\":\"TypeScript\",\"type\":\"your-content\",\"body\":{\"version\":1,\"type\":\"doc\",\"content\":[{\"type\":\"heading\",\"attrs\":{\"level\":1},\"content\":[{\"type\":\"text\",\"text\":\"Example 1 - Avoiding solution “key” and “value” terminology\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Original code with poor names focused on the solution domain:\",\"marks\":[{\"type\":\"strong\"}]}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"typescript\"},\"content\":[{\"type\":\"text\",\"text\":\"const KEY: string = 'PROGRAM_FILEPATH';\\nconst value: string = process.env[KEY];\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Environment variables are typically stored in some kind of “map” data structure, which conventionally has “keys” that can be used to look up particular “values.” Such terminology is used in the code above, but it doesn’t communicate any meaning of the actual data to a reader.\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Improved problem domain names: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"Names rooted in the problem domain at the level of abstraction for this particular code are better. The reader now knows that what is being looked up is based on an “environment variable name”, so he/she can actually go explore a computer system outside the code to see what that environment variable might be. The value retrieved from the environment variable is now more self-evident from the \"},{\"type\":\"text\",\"text\":\"programFilepath\",\"marks\":[{\"type\":\"code\"}]},{\"type\":\"text\",\"text\":\" name.\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"typescript\"},\"content\":[{\"type\":\"text\",\"text\":\"const PROGRAM_FILEPATH_ENVIRONMENT_VARIABLE_NAME: string = 'PROGRAM_FILEPATH';\\nconst programFilepath: string = process.env[PROGRAM_FILEPATH_ENVIRONMENT_VARIABLE_NAME];\"}]},{\"type\":\"heading\",\"attrs\":{\"level\":1},\"content\":[{\"type\":\"text\",\"text\":\"Example 2 - Providing more meaning than “input” and “output”\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Original code with a name overly focused in the solution domain: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"This name is focused on the process of the code itself having \\\"inputs\\\" and expected \\\"outputs,\\\" along with the \\\"map\\\" data structure, without any communication of problem domain meaning for this data:\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"typescript\"},\"content\":[{\"type\":\"text\",\"text\":\"let inputToOutputTextMap: { [key: string]: string } = {\\n \\\"Hello\\\": \\\"Hola\\\",\\n // ...\\n};\\ntestTextTranslation(inputToOutputTextMap);\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Improved problem domain name: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"This name now communicates the problem domain meaning of the data:\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"typescript\"},\"content\":[{\"type\":\"text\",\"text\":\"let originalTextsWithTranslatedTexts: { [key: string]: string } = {\\n \\\"Hello\\\": \\\"Hola\\\",\\n // ...\\n};\\ntestTextTranslation(originalTextsWithTranslatedTexts);\"}]},{\"type\":\"heading\",\"attrs\":{\"level\":1},\"content\":[{\"type\":\"text\",\"text\":\"Example 3 - More specific problem domain information than “result”\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Original code with a name overly focused in the solution domain: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"The variable for the return value is very generic, focusing on the solution of running a command and some \\\"result\\\" being returned from that:\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"typescript\"},\"content\":[{\"type\":\"text\",\"text\":\"let commandResult: string = Command.runAndGetStandardOutput(getServiceLogsCommand);\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Improving the name to be rooted more in the problem domain: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"From the function call, we can see that \\\"standard output\\\" is returned, so including at least \\\"output\\\" would be one step in improving the name. However, we can go one step further in orienting this variable name in the problem domain. If the intent of the command is to get the logs of a service, then the natural standard output would be those logs, so we can name the variable for the return value after that.\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"typescript\"},\"content\":[{\"type\":\"text\",\"text\":\"let serviceLogs: string = Command.runAndGetStandardOutput(getServiceLogsCommand);\"}]},{\"type\":\"paragraph\",\"content\":[]}]},\"fullName\":\"TypeScript\",\"minHeight\":3725}],\"design\":null,\"designType\":\"tab\",\"vertical\":false,\"showTabCard\":true,\"width\":150,\"isEmbedded\":false,\"minHeight\":3825,\"lastTabWidth\":150,\"pages\":[\"1371cc10-133a-4dad-afc9-3cc35bc04d16\",\"ff4ea1d6-9b00-458b-804e-796574e744db\",\"61c39a07-de01-44ba-be6d-4210322d3bc4\",\"a1cfcaf7-a8d0-47b4-ba6b-7904dcee3c73\",\"528da6b6-a308-458c-8fd4-b3afdc4e0707\",\"a9427e99-277e-4cd2-8ace-b2448dca2fe1\"]},\"labeled\":{\"labels\":[]},\"childpages\":{}}"}},"macroMetadata":{"macroId":{"value":"7e2734a3-538c-4ed9-bd27-ea861176fdb8"},"schemaVersion":{"value":"1"},"placeholder":[{"type":"icon","data":{"url":"https://us.navitabs-static-assets.aws.bitvoodoo.cloud/static/4.0.6/images/macro-icon.png"}}],"title":"Tab Wizard"}},"localId":"759efbcd-fa4e-4452-a54b-91a214ec0de0"}},{"type":"mediaSingle","attrs":{"layout":"center","width":760,"widthType":"pixel"},"content":[{"type":"media","attrs":{"width":1822,"alt":"Tap into your teams collective wisdom ad.png","id":"f5fd0ac9-66aa-469c-8293-b13700058181","collection":"contentId-101449799","type":"file","height":377},"marks":[{"type":"link","attrs":{"href":"https://www.pulsepoint-ai.com/developers"}}]}]}],"version":1}

Focus on the Problem Domain Over the Solution Domain [VP1]