{"type":"doc","content":[{"type":"panel","attrs":{"panelColor":"#E6FCFF","panelType":"custom"},"content":[{"type":"paragraph","content":[{"text":"Tip DP1","type":"text","marks":[{"type":"code"}]}]},{"type":"paragraph","content":[{"text":"The first kind of intent that is important to document is what ","type":"text"},{"text":"code","type":"text","marks":[{"type":"em"}]},{"text":" is intended to do. This is focused on making sure the code is behaving correctly for end-users and one way bugs can be detected. Ensure this is clear to maintenance programmers.","type":"text"}]}]},{"type":"paragraph","content":[{"text":"See the following 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\":\"3532d52d-ae5c-4c8c-9afa-64a36d660100\",\"label\":\"C++\",\"type\":\"your-content\",\"body\":{\"version\":1,\"type\":\"doc\",\"content\":[{\"type\":\"heading\",\"attrs\":{\"level\":1},\"content\":[{\"type\":\"text\",\"text\":\"Example 1 - Include folder paths\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Comments that largely just summarize the code directly: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"What’s included in the comments could be discerned from the code itself.\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"c++\"},\"content\":[{\"type\":\"text\",\"text\":\"// ADD AN INCLUDE PATH FOR THE CODE FOLDER.\\nconst std::string INCLUDE_FOLDER_PATH_FLAG = \\\"/I\\\";\\ncommand_line_arguments.push_back(INCLUDE_FOLDER_PATH_FLAG);\\ncommand_line_arguments.push_back(code_folder_path.string());\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Comments that communicate higher-level intent of what the code should be doing: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"With this tweak in the comment, it’s easier to discern if the code is doing what it is supposed to do from the perspective of final results for an end user:\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"c++\"},\"content\":[{\"type\":\"text\",\"text\":\"// ENSURE THE PROJECT'S FILES CAN BE INCLUDED.\\nconst std::string INCLUDE_FOLDER_PATH_FLAG = \\\"/I\\\";\\ncommand_line_arguments.push_back(INCLUDE_FOLDER_PATH_FLAG);\\ncommand_line_arguments.push_back(code_folder_path.string());\"}]},{\"type\":\"heading\",\"attrs\":{\"level\":1},\"content\":[{\"type\":\"text\",\"text\":\"Example 2 - Printing a user-facing message\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Comments that largely just summarize the code directly: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"What’s included in the comments could be discerned from the code itself.\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"c++\"},\"content\":[{\"type\":\"text\",\"text\":\"// PRINT THE CURRENT TIME FOR THE BUILD STARTING.\\nstd::cout\\n << Timer::CurrentTimeString() \\n << \\\" - Starting \\\" \\n << build_type << \\\" build...\\\" \\n << std::endl;\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Comments that communicate higher-level intent of what the code should be doing: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"With these tweaks in the comments, it’s easier to discern if the code is doing what it is supposed to do from the perspective of final results for an end user:\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"c++\"},\"content\":[{\"type\":\"text\",\"text\":\"// INDICATE THE BUILD IS STARTING FOR THE USER.\\n// A timestamp helps provide visibility into how long builds take by comparing timestamps.\\nstd::cout\\n << Timer::CurrentTimeString() \\n << \\\" - Starting \\\" \\n << build_type << \\\" build...\\\" \\n << std::endl;\"}]},{\"type\":\"heading\",\"attrs\":{\"level\":1},\"content\":[{\"type\":\"text\",\"text\":\"Example 3 - Creating a folder\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Comments that largely just summarize the code directly: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"What’s included in the comments could be discerned from the code itself.\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"c++\"},\"content\":[{\"type\":\"text\",\"text\":\"// CREATE THE BUILD TYPE OUTPUT FOLDER.\\nstd::filesystem::path build_folder_path = workspace_folder_path / \\\"build\\\";\\nstd::filesystem::path build_type_folder_output_path = build_folder_path / build_type;\\nstd::filesystem::create_directories(build_type_folder_output_path);\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Comments that communicate higher-level intent of what the code should be doing: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"With these tweaks in the comments, it’s easier to discern the higher-level intent of the code:\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"c++\"},\"content\":[{\"type\":\"text\",\"text\":\"// ENSURE THE BUILD TYPE FOLDER EXISTS.\\n// The folder may or may not already exist, but it is required to exist\\n// for future steps in the build.\\nstd::filesystem::path build_folder_path = workspace_folder_path / \\\"build\\\";\\nstd::filesystem::path build_type_folder_output_path = build_folder_path / build_type;\\nstd::filesystem::create_directories(build_type_folder_output_path);\"}]},{\"type\":\"paragraph\",\"content\":[]}]},\"fullName\":\"C++\",\"minHeight\":0},{\"id\":\"12f5e7b6-5ba9-4240-ad7c-b8e0aa50aada\",\"label\":\"C#\",\"type\":\"your-content\",\"body\":{\"version\":1,\"type\":\"doc\",\"content\":[{\"type\":\"heading\",\"attrs\":{\"level\":1},\"content\":[{\"type\":\"text\",\"text\":\"Example 1 - Include folder paths\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Comments that largely just summarize the code directly: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"What’s included in the comments could be discerned from the code itself.\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"csharp\"},\"content\":[{\"type\":\"text\",\"text\":\"// ADD AN INCLUDE PATH FOR THE CODE FOLDER.\\nconst string IncludeFolderPathFlag = \\\"/I\\\";\\ncommandLineArguments.Add(IncludeFolderPathFlag);\\ncommandLineArguments.Add(codeFolderPath);\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Comments that communicate higher-level intent of what the code should be doing: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"With this tweak in the comment, it’s easier to discern if the code is doing what it is supposed to do from the perspective of final results for an end user:\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"csharp\"},\"content\":[{\"type\":\"text\",\"text\":\"// ENSURE THE PROJECT'S FILES CAN BE INCLUDED.\\nconst string IncludeFolderPathFlag = \\\"/I\\\";\\ncommandLineArguments.Add(IncludeFolderPathFlag);\\ncommandLineArguments.Add(codeFolderPath);\"}]},{\"type\":\"heading\",\"attrs\":{\"level\":1},\"content\":[{\"type\":\"text\",\"text\":\"Example 2 - Printing a user-facing message\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Comments that largely just summarize the code directly: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"What’s included in the comments could be discerned from the code itself.\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"csharp\"},\"content\":[{\"type\":\"text\",\"text\":\"// PRINT THE CURRENT TIME FOR THE BUILD STARTING.\\nConsole.WriteLine($\\\"{Timer.CurrentTimeString()} - Starting {buildType} build...\\\");\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Comments that communicate higher-level intent of what the code should be doing: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"With these tweaks in the comments, it’s easier to discern if the code is doing what it is supposed to do from the perspective of final results for an end user:\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"csharp\"},\"content\":[{\"type\":\"text\",\"text\":\"// INDICATE THE BUILD IS STARTING FOR THE USER.\\n// A timestamp helps provide visibility into how long builds take by comparing timestamps.\\nConsole.WriteLine($\\\"{Timer.CurrentTimeString()} - Starting {buildType} build...\\\");\"}]},{\"type\":\"heading\",\"attrs\":{\"level\":1},\"content\":[{\"type\":\"text\",\"text\":\"Example 3 - Creating a folder\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Comments that largely just summarize the code directly: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"What’s included in the comments could be discerned from the code itself.\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"csharp\"},\"content\":[{\"type\":\"text\",\"text\":\"// CREATE THE BUILD TYPE OUTPUT FOLDER.\\nstring buildFolderPath = Path.Combine(workspaceFolderPath, \\\"build\\\");\\nstring buildTypeFolderOutputPath = Path.Combine(buildFolderPath, buildType);\\nDirectory.CreateDirectory(buildTypeFolderOutputPath);\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Comments that communicate higher-level intent of what the code should be doing: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"With these tweaks in the comments, it’s easier to discern the higher-level intent of the code:\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"csharp\"},\"content\":[{\"type\":\"text\",\"text\":\"// ENSURE THE BUILD TYPE FOLDER EXISTS.\\n// The folder may or may not already exist, but it is required to exist\\n// for future steps in the build.\\nstring buildFolderPath = Path.Combine(workspaceFolderPath, \\\"build\\\");\\nstring buildTypeFolderOutputPath = Path.Combine(buildFolderPath, buildType);\\nDirectory.CreateDirectory(buildTypeFolderOutputPath);\"}]},{\"type\":\"paragraph\",\"content\":[]}]},\"fullName\":\"C#\",\"minHeight\":0},{\"id\":\"b9b2a042-dae2-4ba6-964c-f00a543a9b69\",\"label\":\"Java\",\"type\":\"your-content\",\"body\":{\"version\":1,\"type\":\"doc\",\"content\":[{\"type\":\"heading\",\"attrs\":{\"level\":1},\"content\":[{\"type\":\"text\",\"text\":\"Example 1 - Include folder paths\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Comments that largely just summarize the code directly: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"What’s included in the comments could be discerned from the code itself.\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"java\"},\"content\":[{\"type\":\"text\",\"text\":\"// ADD AN INCLUDE PATH FOR THE CODE FOLDER.\\nfinal String INCLUDE_FOLDER_PATH_FLAG = \\\"/I\\\";\\ncommandLineArguments.add(INCLUDE_FOLDER_PATH_FLAG);\\ncommandLineArguments.add(codeFolderPath);\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Comments that communicate higher-level intent of what the code should be doing: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"With this tweak in the comment, it’s easier to discern if the code is doing what it is supposed to do from the perspective of final results for an end user:\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"java\"},\"content\":[{\"type\":\"text\",\"text\":\"// ENSURE THE PROJECT'S FILES CAN BE INCLUDED.\\nfinal String INCLUDE_FOLDER_PATH_FLAG = \\\"/I\\\";\\ncommandLineArguments.add(INCLUDE_FOLDER_PATH_FLAG);\\ncommandLineArguments.add(codeFolderPath);\"}]},{\"type\":\"heading\",\"attrs\":{\"level\":1},\"content\":[{\"type\":\"text\",\"text\":\"Example 2 - Printing a user-facing message\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Comments that largely just summarize the code directly: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"What’s included in the comments could be discerned from the code itself.\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"java\"},\"content\":[{\"type\":\"text\",\"text\":\"// PRINT THE CURRENT TIME FOR THE BUILD STARTING.\\nSystem.out.println(Timer.currentTimeString() + \\\" - Starting \\\" + buildType + \\\" build...\\\");\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Comments that communicate higher-level intent of what the code should be doing: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"With these tweaks in the comments, it’s easier to discern if the code is doing what it is supposed to do from the perspective of final results for an end user:\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"java\"},\"content\":[{\"type\":\"text\",\"text\":\"// INDICATE THE BUILD IS STARTING FOR THE USER.\\n// A timestamp helps provide visibility into how long builds take by comparing timestamps.\\nSystem.out.println(Timer.currentTimeString() + \\\" - Starting \\\" + buildType + \\\" build...\\\");\"}]},{\"type\":\"heading\",\"attrs\":{\"level\":1},\"content\":[{\"type\":\"text\",\"text\":\"Example 3 - Creating a folder\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Comments that largely just summarize the code directly: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"What’s included in the comments could be discerned from the code itself.\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"java\"},\"content\":[{\"type\":\"text\",\"text\":\"// CREATE THE BUILD TYPE OUTPUT FOLDER.\\nPath buildFolderPath = Paths.get(workspaceFolderPath, \\\"build\\\");\\nPath buildTypeFolderOutputPath = buildFolderPath.resolve(buildType);\\nFiles.createDirectories(buildTypeFolderOutputPath);\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Comments that communicate higher-level intent of what the code should be doing: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"With these tweaks in the comments, it’s easier to discern the higher-level intent of the code:\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"java\"},\"content\":[{\"type\":\"text\",\"text\":\"// ENSURE THE BUILD TYPE FOLDER EXISTS.\\n// The folder may or may not already exist, but it is required to exist\\n// for future steps in the build.\\nPath buildFolderPath = Paths.get(workspaceFolderPath, \\\"build\\\");\\nPath buildTypeFolderOutputPath = buildFolderPath.resolve(buildType);\\nFiles.createDirectories(buildTypeFolderOutputPath);\"}]},{\"type\":\"paragraph\",\"content\":[]}]},\"fullName\":\"Java\",\"minHeight\":0},{\"id\":\"b82383e8-e614-4cf3-893d-9d820700d996\",\"label\":\"Python\",\"type\":\"your-content\",\"body\":{\"version\":1,\"type\":\"doc\",\"content\":[{\"type\":\"heading\",\"attrs\":{\"level\":1},\"content\":[{\"type\":\"text\",\"text\":\"Example 1 - Include folder paths\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Comments that largely just summarize the code directly: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"What’s included in the comments could be discerned from the code itself.\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"python\"},\"content\":[{\"type\":\"text\",\"text\":\"# ADD AN INCLUDE PATH FOR THE CODE FOLDER.\\nINCLUDE_FOLDER_PATH_FLAG: str = \\\"/I\\\"\\ncommand_line_arguments.append(INCLUDE_FOLDER_PATH_FLAG)\\ncommand_line_arguments.append(code_folder_path)\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Comments that communicate higher-level intent of what the code should be doing: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"With this tweak in the comment, it’s easier to discern if the code is doing what it is supposed to do from the perspective of final results for an end user:\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"python\"},\"content\":[{\"type\":\"text\",\"text\":\"# ENSURE THE PROJECT'S FILES CAN BE INCLUDED.\\nINCLUDE_FOLDER_PATH_FLAG: str = \\\"/I\\\"\\ncommand_line_arguments.append(INCLUDE_FOLDER_PATH_FLAG)\\ncommand_line_arguments.append(code_folder_path)\"}]},{\"type\":\"heading\",\"attrs\":{\"level\":1},\"content\":[{\"type\":\"text\",\"text\":\"Example 2 - Printing a user-facing message\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Comments that largely just summarize the code directly: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"What’s included in the comments could be discerned from the code itself.\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"python\"},\"content\":[{\"type\":\"text\",\"text\":\"# PRINT THE CURRENT TIME FOR THE BUILD STARTING.\\nprint(f\\\"{Timer.current_time_string()} - Starting {build_type} build...\\\")\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Comments that communicate higher-level intent of what the code should be doing: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"With these tweaks in the comments, it’s easier to discern if the code is doing what it is supposed to do from the perspective of final results for an end user:\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"python\"},\"content\":[{\"type\":\"text\",\"text\":\"# INDICATE THE BUILD IS STARTING FOR THE USER.\\n# A timestamp helps provide visibility into how long builds take by comparing timestamps.\\nprint(f\\\"{Timer.current_time_string()} - Starting {build_type} build...\\\")\"}]},{\"type\":\"heading\",\"attrs\":{\"level\":1},\"content\":[{\"type\":\"text\",\"text\":\"Example 3 - Creating a folder\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Comments that largely just summarize the code directly: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"What’s included in the comments could be discerned from the code itself.\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"python\"},\"content\":[{\"type\":\"text\",\"text\":\"# CREATE THE BUILD TYPE OUTPUT FOLDER.\\nbuild_folder_path: pathlib.Path = workspace_folder_path / \\\"build\\\"\\nbuild_type_folder_output_path: pathlib.Path = build_folder_path / build_type\\nbuild_type_folder_output_path.mkdir(parents=True, exist_ok=True)\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Comments that communicate higher-level intent of what the code should be doing: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"With these tweaks in the comments, it’s easier to discern the higher-level intent of the code:\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"python\"},\"content\":[{\"type\":\"text\",\"text\":\"# ENSURE THE BUILD TYPE FOLDER EXISTS.\\n# The folder may or may not already exist, but it is required to exist\\n# for future steps in the build.\\nbuild_folder_path: pathlib.Path = workspace_folder_path / \\\"build\\\"\\nbuild_type_folder_output_path: pathlib.Path = build_folder_path / build_type\\nbuild_type_folder_output_path.mkdir(parents=True, exist_ok=True)\"}]},{\"type\":\"paragraph\",\"content\":[]}]},\"fullName\":\"Python\",\"minHeight\":0},{\"id\":\"a1947d6d-54ac-4637-9753-e40268abfe92\",\"label\":\"JavaScript\",\"type\":\"your-content\",\"body\":{\"version\":1,\"type\":\"doc\",\"content\":[{\"type\":\"heading\",\"attrs\":{\"level\":1},\"content\":[{\"type\":\"text\",\"text\":\"Example 1 - Include folder paths\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Comments that largely just summarize the code directly: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"What’s included in the comments could be discerned from the code itself.\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"javascript\"},\"content\":[{\"type\":\"text\",\"text\":\"// ADD AN INCLUDE PATH FOR THE CODE FOLDER.\\nconst INCLUDE_FOLDER_PATH_FLAG = \\\"/I\\\";\\ncommandLineArguments.push(INCLUDE_FOLDER_PATH_FLAG);\\ncommandLineArguments.push(codeFolderPath);\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Comments that communicate higher-level intent of what the code should be doing: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"With this tweak in the comment, it’s easier to discern if the code is doing what it is supposed to do from the perspective of final results for an end user:\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"javascript\"},\"content\":[{\"type\":\"text\",\"text\":\"// ENSURE THE PROJECT'S FILES CAN BE INCLUDED.\\nconst INCLUDE_FOLDER_PATH_FLAG = \\\"/I\\\";\\ncommandLineArguments.push(INCLUDE_FOLDER_PATH_FLAG);\\ncommandLineArguments.push(codeFolderPath);\"}]},{\"type\":\"heading\",\"attrs\":{\"level\":1},\"content\":[{\"type\":\"text\",\"text\":\"Example 2 - Printing a user-facing message\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Comments that largely just summarize the code directly: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"What’s included in the comments could be discerned from the code itself.\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"javascript\"},\"content\":[{\"type\":\"text\",\"text\":\"// PRINT THE CURRENT TIME FOR THE BUILD STARTING.\\nconsole.log(Timer.currentTimeString() + \\\" - Starting \\\" + buildType + \\\" build...\\\");\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Comments that communicate higher-level intent of what the code should be doing: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"With these tweaks in the comments, it’s easier to discern if the code is doing what it is supposed to do from the perspective of final results for an end user:\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"javascript\"},\"content\":[{\"type\":\"text\",\"text\":\"// INDICATE THE BUILD IS STARTING FOR THE USER.\\n// A timestamp helps provide visibility into how long builds take by comparing timestamps.\\nconsole.log(Timer.currentTimeString() + \\\" - Starting \\\" + buildType + \\\" build...\\\");\"}]},{\"type\":\"heading\",\"attrs\":{\"level\":1},\"content\":[{\"type\":\"text\",\"text\":\"Example 3 - Creating a folder\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Comments that largely just summarize the code directly: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"What’s included in the comments could be discerned from the code itself.\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"javascript\"},\"content\":[{\"type\":\"text\",\"text\":\"// CREATE THE BUILD TYPE OUTPUT FOLDER.\\nconst buildFolderPath = path.join(workspaceFolderPath, \\\"build\\\");\\nconst buildTypeFolderOutputPath = path.join(buildFolderPath, buildType);\\nfs.mkdirSync(buildTypeFolderOutputPath, { recursive: true });\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Comments that communicate higher-level intent of what the code should be doing: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"With these tweaks in the comments, it’s easier to discern the higher-level intent of the code:\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"javascript\"},\"content\":[{\"type\":\"text\",\"text\":\"// ENSURE THE BUILD TYPE FOLDER EXISTS.\\n// The folder may or may not already exist, but it is required to exist\\n// for future steps in the build.\\nconst buildFolderPath = path.join(workspaceFolderPath, \\\"build\\\");\\nconst buildTypeFolderOutputPath = path.join(buildFolderPath, buildType);\\nfs.mkdirSync(buildTypeFolderOutputPath, { recursive: true });\"}]},{\"type\":\"paragraph\",\"content\":[]}]},\"fullName\":\"JavaScript\",\"minHeight\":0},{\"id\":\"80e2e954-249d-4b94-97a4-ff58cfb5da7d\",\"label\":\"TypeScript\",\"type\":\"your-content\",\"body\":{\"version\":1,\"type\":\"doc\",\"content\":[{\"type\":\"heading\",\"attrs\":{\"level\":1},\"content\":[{\"type\":\"text\",\"text\":\"Example 1 - Include folder paths\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Comments that largely just summarize the code directly: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"What’s included in the comments could be discerned from the code itself.\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"typescript\"},\"content\":[{\"type\":\"text\",\"text\":\"// ADD AN INCLUDE PATH FOR THE CODE FOLDER.\\nconst INCLUDE_FOLDER_PATH_FLAG = \\\"/I\\\";\\ncommandLineArguments.push(INCLUDE_FOLDER_PATH_FLAG);\\ncommandLineArguments.push(codeFolderPath);\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Comments that communicate higher-level intent of what the code should be doing: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"With this tweak in the comment, it’s easier to discern if the code is doing what it is supposed to do from the perspective of final results for an end user:\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"typescript\"},\"content\":[{\"type\":\"text\",\"text\":\"// ENSURE THE PROJECT'S FILES CAN BE INCLUDED.\\nconst INCLUDE_FOLDER_PATH_FLAG = \\\"/I\\\";\\ncommandLineArguments.push(INCLUDE_FOLDER_PATH_FLAG);\\ncommandLineArguments.push(codeFolderPath);\"}]},{\"type\":\"heading\",\"attrs\":{\"level\":1},\"content\":[{\"type\":\"text\",\"text\":\"Example 2 - Printing a user-facing message\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Comments that largely just summarize the code directly: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"What’s included in the comments could be discerned from the code itself.\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"typescript\"},\"content\":[{\"type\":\"text\",\"text\":\"// PRINT THE CURRENT TIME FOR THE BUILD STARTING.\\nconsole.log(Timer.currentTimeString() + \\\" - Starting \\\" + buildType + \\\" build...\\\");\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Comments that communicate higher-level intent of what the code should be doing: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"With these tweaks in the comments, it’s easier to discern if the code is doing what it is supposed to do from the perspective of final results for an end user:\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"typescript\"},\"content\":[{\"type\":\"text\",\"text\":\"// INDICATE THE BUILD IS STARTING FOR THE USER.\\n// A timestamp helps provide visibility into how long builds take by comparing timestamps.\\nconsole.log(Timer.currentTimeString() + \\\" - Starting \\\" + buildType + \\\" build...\\\");\"}]},{\"type\":\"heading\",\"attrs\":{\"level\":1},\"content\":[{\"type\":\"text\",\"text\":\"Example 3 - Creating a folder\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Comments that largely just summarize the code directly: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"What’s included in the comments could be discerned from the code itself.\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"typescript\"},\"content\":[{\"type\":\"text\",\"text\":\"// CREATE THE BUILD TYPE OUTPUT FOLDER.\\nconst buildFolderPath = path.join(workspaceFolderPath, \\\"build\\\");\\nconst buildTypeFolderOutputPath = path.join(buildFolderPath, buildType);\\nfs.mkdirSync(buildTypeFolderOutputPath, { recursive: true });\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Comments that communicate higher-level intent of what the code should be doing: \",\"marks\":[{\"type\":\"strong\"}]},{\"type\":\"text\",\"text\":\"With these tweaks in the comments, it’s easier to discern the higher-level intent of the code:\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"typescript\"},\"content\":[{\"type\":\"text\",\"text\":\"// ENSURE THE BUILD TYPE FOLDER EXISTS.\\n// The folder may or may not already exist, but it is required to exist\\n// for future steps in the build.\\nconst buildFolderPath = path.join(workspaceFolderPath, \\\"build\\\");\\nconst buildTypeFolderOutputPath = path.join(buildFolderPath, buildType);\\nfs.mkdirSync(buildTypeFolderOutputPath, { recursive: true });\"}]},{\"type\":\"paragraph\",\"content\":[]}]},\"fullName\":\"TypeScript\",\"minHeight\":0}],\"design\":null,\"designType\":\"tab\",\"vertical\":false,\"showTabCard\":true,\"width\":150,\"isEmbedded\":false,\"minHeight\":1600,\"lastTabWidth\":150,\"pages\":[\"3532d52d-ae5c-4c8c-9afa-64a36d660100\",\"12f5e7b6-5ba9-4240-ad7c-b8e0aa50aada\",\"b9b2a042-dae2-4ba6-964c-f00a543a9b69\",\"b82383e8-e614-4cf3-893d-9d820700d996\",\"a1947d6d-54ac-4637-9753-e40268abfe92\",\"80e2e954-249d-4b94-97a4-ff58cfb5da7d\"]},\"labeled\":{\"labels\":[]},\"childpages\":{}}"}},"macroMetadata":{"macroId":{"value":"81ef5df8-4170-4d5c-9778-fd7b45e74f95"},"schemaVersion":{"value":"1"},"placeholder":[{"type":"icon","data":{"url":"https://us.navitabs-static-assets.aws.bitvoodoo.cloud/static/4.0.7/images/macro-icon.png"}}],"title":"Tab Wizard"}},"localId":"dd5711f8-c7c1-4dd9-b627-e570636e1265"}},{"type":"mediaSingle","attrs":{"layout":"center","width":760,"widthType":"pixel"},"content":[{"type":"media","attrs":{"width":1820,"alt":"Say goodbye to blindsided code updates ad.png","id":"f4be2700-3611-4640-a5a8-521b0d9bd6ba","collection":"contentId-104628360","type":"file","height":376},"marks":[{"type":"link","attrs":{"href":"https://www.pulsepoint-ai.com/developers"}}]}]}],"version":1}

Document What the Code Is Intended To Do [DP1] [WHAT] [WHY]