Thinking in software development

[yaobinwen]

Description

This issue tracks my thoughts on software development. I may extend every comment into an article to talk more about it.

• Error Reporting and Handling
• OOP and Encapsulation
• Full Configurability
• Switch logging modes dynamically
• Documentation
• Progress Tracking
• Taking Notes
• Logging

[yaobinwen]

Error Reporting and Handling

See yaobinwen/error-handling.

• Errors should always be reported in the appropriate context.
• Every error should be handled because the error spot has the best context to report the error.
• The error should be discovered as close to the root cause as possible.
  • For example, an error may be reported saying "the data buffer is empty". There is no more about what caused the error in the first place because "data buffer is empty" is the symptom. Somewhere in the upstream (e.g., the network transmission) may have failed earlier but that failure was not reported. We should have tried to report the upstream failures (although it may not be always possible).
• The APIs should tell the caller every possible error it reports. Much more importantly, it should tell the caller under what condition an error would be reported.

[yaobinwen]

OOP and Encapsulation

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.

[yaobinwen]

Full Configurability

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.)

[yaobinwen]

Switch logging modes dynamically

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.

[yaobinwen]

Documentation

(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:

• Bottom-up approach can build a solid foundation for the readers to understand higher topics, but it may take the readers a lot of time to understand everything before he/she can understand the mostly interested in topics. Bottom-up approach is good for readers that can take time to study the software, but not suitable if they need to understand a topic in short time.
• Top-down approach can provide the readers a good overview of the topic so they know what are related. But the readers must open additional links to study the underlying concepts in order to fully understand the current topic, and they need to track the progress by themselves. This is good for readers that want to focus on one topic in short time.

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.

[yaobinwen]

Progress Tracking

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.

[yaobinwen]

Taking Notes

1. Notes should not have to have a file name. Similar to a tweet: You don't give your tweet a tweet name. You just publish the content.
2. The problem with tweets are: they can't be linked to each other; they can't be easily modified (?); they can't be easily broken into smaller ones, or merged together when you find two are related.

For the note taking system:

1. Just throw in the contents.
2. The topics will emerge gradually.
3. Able to break one into smaller ones, or merge multiple ones into one.
4. Able to link one note to another.

(Ask ChatGPT how to implement it.)

[yaobinwen]

Logging

• Logging activities should be carefully designed. We should not just random log stuff. Instead, the logging activities should be minimized while still sufficient to figure out the system's activities.
• If the logs are too spammy, we should probably log summaries instead of every detailed log message.

[yaobinwen]

Will AI fully replace human programmers?

See this Linked-in post.

• In general, I agree with the conclusion that AI probably will not replace human programmers but potentially require more. But my reasoning is based on different grounds.
• I agree that with the current AIs, replacing human programmers are almost impossible because there are so many aspects to consider in software engineering.
• But I think AI, which we also call robots, which are essentially machines, can naturally understand other machines better, because:
  • Software is based on a set of well-defined machine instructions and mathematics. These instructions have clear definitions of inputs and outputs (including side-effects).
  • Current AIs don't understand it pretty well because we humans are bad teachers. What is the last time you learn a programming language by reading its technical specification that is possibly full of EBNF and context-free grammar? You probably don't. In fact, if you go to a programming language website, chances are they don't provide the technical specification but "tutorials" and "references" that are more human-friendly.
  • But if we can teach AI with those hard-core spec, AIs will probably understand the programming languages 100%. Yes, 100%.
  • If AI can understand a programming language 100%, it's definitely possible to understand a simple program 100%, then it's definitely possible to understand a complex program that consists of multiple simple programs, then it's definitely possible to understand a complex system (e.g., an OS) that consists of multiple complex programs. This is divide-and-conquer.
  • There is uncertainty in an OS, such as the scheduling algorithm and concurrency. How do we find and fix the race conditions? We test it, see how it occurs, analyze the reasons, and fix the bugs in the code. I don't see why AI can't do it.
• But why do I say it may probably require more human programmers? It all comes to the question: Do we need to understand AI's logic? This question points back to the more fundamental question: Must we humans always be the master of AI? Can we be their pets or slaves?
  • If we want the AIs always listen to us, we must be able to prevent them from deceiving us. One way to do that, is to fully understand what they do, so we can catch them even if they indeed try to deceive us.
  • Another way is to punish them to make them fear. But fear may not always work.
  • Now, an AI delivers a piece of code, how can we humans understand the code? We need some humans to learn their language in order to understand what the AIs are trying to do. Then what are those humans that can understand AI's languages?

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.

===

• Explainable AI – why humans must always be able to understand what AI is thinking
• Why humans will never understand AI