Open yaobinwen opened 1 year ago
OOP promotes encapsulation, saying that the API users should not have to know the implementation details. This only works if the API is fully documented. Many times, when the users run into a problem, they do not have the sufficient information to understand the internal behaviors especially when the documentation cannot explain the observed behaviors. In this case, the users should be able to look into the implementation details to figure out what is going wrong.
In other words, encapsulation works well only when the implementation details can be easily obtained when necessary.
The software should be broken into small reusable pieces to avoid duplicated code. The final software is integrated by putting all the pieces together. (In fact, COM has been trying to do this because it provides binary level interface.)
We don't want to write too many log messages (e.g., the debug level) for release builds. However, we should make it easy to re-enable debug level logging at run time, so the users don't need to recompile the code.
Envoy's runtime configuration seems to work this way.
(Refer to yaobinwen/document-shredded.)
The knowledge should be presented in levels: Lower levels are more fundamental than the upper levels. In other words, in order to understand the upper levels, one needs to understand lower levels.
However, sometimes a few concepts may be related with each other and cannot be divided into levels. In this case, they should be put into a "focus group" to allow the learners to study them altogether.
If possible, the knowledge should be presented in a "graph" to make it easier for the users to figure out what else should be studied. Using a lot of external links is not the best way.
In other words, maybe we should let the readers read the documentation bottom-up, not top-down. However, they have pros and cons:
Example: I'm reading Envoy's documentation. This page talks about "listeners" but in order to understand it, I must read a few other external links: filter_chain
, filter_chain_match
, filter
. I wish the documentation could have explained them before I have to study listeners.
Every part of the software that potentially take long time to finish should probably provide some kind of progress update mechanism, so the caller can tell the progress and send feedback to the caller's caller.
For the note taking system:
(Ask ChatGPT how to implement it.)
See this Linked-in post.
Possibly, we call them "programmers".
===
In the early days, programmers must understand hardware and write code for the hardware. When OS became more mature, programmers nowadays no longer need to understand hardware that much but learn how to program using the services that the OSs provide. In the future, we probably do AI-oriented programming.
===
Description
This issue tracks my thoughts on software development. I may extend every comment into an article to talk more about it.