We need to write code that is optimized for communication and clarity. We have a number of tools we can use to craft communicative code.
1. Variable and function names. These should be descriptive and never deceptive. For example, I've seen metric tons of code like this `const json = makeSomeApiCall(params)` where the contents of `json` is a the decoded response data and not a JSON string. This code is deceptive and obfuscatory. But if you write `const decodedFooResponse = makeSomeApiCall(params);` then you are accurately describing what the value is. This is particularly import in untyped/loosely typed languages where the value of the variable could be anything.
2. Code structure and layout. When writing prose, we achieve clarity through structure. Code is no different. Keep related things together. Avoid run-ons. In other words, write code that has smallish functions, with smallish interfaces, it's easier to reason about how the code will behave. Avoid unnecessary mutation of values--repeated mutation of the same value is particularly pernicious. Use white space to create visual separations of distinct ideas. Use abstraction and encapsulation to keep code focused. Avoid deeply nested conditionals, flattening the tree whenever possible. And a million other strategies that can all help.
3. Tests. Tests can be documentation, but they certainly aren't always. They also aren't convenient documentation--what they offer isn't going to show up in your editor when you inspect a method. Unit tests are a nice way of recording verifiable expectations for behavior. But if the test code is complicated or poorly organized, all it does is compound the misery of working on a messy codebase.
4. Comments are distinct from documentation here. Comments are little side notes like "this implementation is a bit of a hack. It is brittle because .... but we decided to keep it because X. See someURL for contemporaneous discussion." They tell us why a thing is the way it is or about some sort of risk or unexpected detail.
4. Documentation is absolutely a part of making code understandable. These docs are primarily going to be used in an IDE/editor when viewing function signature data. Ideally you can write JavaDoc/TSDoc/POD or similar inline docs. Examples are worth their weight in gold.
We should be using all our tools to write communicative code. We don't need every technique for every line or block, but over the scope of a package or project, we should judiciously employ them all. Every line added comes with a concomitant maintenance cost--we must ensure that every line we add is worth that cost.
1. Variable and function names. These should be descriptive and never deceptive. For example, I've seen metric tons of code like this `const json = makeSomeApiCall(params)` where the contents of `json` is a the decoded response data and not a JSON string. This code is deceptive and obfuscatory. But if you write `const decodedFooResponse = makeSomeApiCall(params);` then you are accurately describing what the value is. This is particularly import in untyped/loosely typed languages where the value of the variable could be anything.
2. Code structure and layout. When writing prose, we achieve clarity through structure. Code is no different. Keep related things together. Avoid run-ons. In other words, write code that has smallish functions, with smallish interfaces, it's easier to reason about how the code will behave. Avoid unnecessary mutation of values--repeated mutation of the same value is particularly pernicious. Use white space to create visual separations of distinct ideas. Use abstraction and encapsulation to keep code focused. Avoid deeply nested conditionals, flattening the tree whenever possible. And a million other strategies that can all help.
3. Tests. Tests can be documentation, but they certainly aren't always. They also aren't convenient documentation--what they offer isn't going to show up in your editor when you inspect a method. Unit tests are a nice way of recording verifiable expectations for behavior. But if the test code is complicated or poorly organized, all it does is compound the misery of working on a messy codebase.
4. Comments are distinct from documentation here. Comments are little side notes like "this implementation is a bit of a hack. It is brittle because .... but we decided to keep it because X. See someURL for contemporaneous discussion." They tell us why a thing is the way it is or about some sort of risk or unexpected detail.
4. Documentation is absolutely a part of making code understandable. These docs are primarily going to be used in an IDE/editor when viewing function signature data. Ideally you can write JavaDoc/TSDoc/POD or similar inline docs. Examples are worth their weight in gold.
We should be using all our tools to write communicative code. We don't need every technique for every line or block, but over the scope of a package or project, we should judiciously employ them all. Every line added comes with a concomitant maintenance cost--we must ensure that every line we add is worth that cost.