Q1: “Here is 95% of the logic” — In what contexts is such a documentation considered complete? Answered at the end.
When we programmers read source code and document the “business logic” implemented thereby, we are sometimes tempted to write “My write-up captures the bulk of the business logic. I have omitted minor details, but they are edge cases. At this stage we don’t need to worry about them”. I then hope I have not glossed over important details. I hope the omitted details are just fine prints. I was proven wrong time and again.
Sound byte: source code is all details, nothing but details.
Sound byte: Everything in source code is important detail until proven otherwise. Except the obvious redundant code, the “proof” usually takes endless effort, so in reality, Everything in source code is important detail.
The “business logic” we are trying to capture actually consists of not only features and functionalities, but functional fragments i.e. the details.
When we examine source code, a visible chunk of code with explicit function names, variable names, or explicit comments are hard to miss. Those are the “easy parts”, but what about those tiny functional fragments …
- Perhaps a short condition buried in a complicated if/while conditional
- Perhaps a seemingly useless catch block among many catches.
- Perhaps a break/continue statement that seems to serve no purpose
- Perhaps an intentional switch-case fall-through
- Perhaps a seemingly unnecessary sanity check? I tend to throw in lots of them
- Perhaps some corner case error handling module that look completely redundant and forgettable, esp. compared to other error handlers.
- Perhaps a variable initialization “soon” before an assignment
- Perhaps a missing curly brace after a for-loop header
( How about the equal sign in “>=” … Well, that’s actually a highly visible fragment, because we programmers have trained vision to spot that “=” buried therein. )
Let me stress again. The visibility, code size … of a functional fragment is not indication of its relative importance. The low-visibility, physically small functional fragments can be equally important as a more visible functional fragment.
To the computer, all of these functional fragments are equally significant. Each could have impact on a production request or real user.
Out of 900 such “functional fragments”, which ones deal with purely theoretical scenarios that would never arise (eg extraneous data) .. we really don’t know without analyzing tons of production data. One minor functional fragment might get activated by a real production data item. So the code gets executed unexpectedly, usually with immediate effect, but sometimes invisibly, because its effect is concealed by subsequent code.
I would say there are no fine-prints in executable source code. Conversely, every part of executable source code is fine print, including the most visible if/else. Every executable code has a real impact, unless we use real production data to prove otherwise.
A1: good enough if you have analyzed enough production data to know that every omitted functional fragment is truly unimportant.
keep learning 活到老学到老 