On 08/23/2020 02:07 PM, Carl Zwanzig wrote:
-snip-
Charlie's Rule of Technical Reading
It doesn't say what you think it says, nor what you remember it to have said, nor what you were told
that it says, and certainly not what you want it to say, and if by chance you are its author, it
doesn't say what you intended it to say. Then what does it say? It says what it says. So if you want
to know what it says, stop trying to remember what it says, and don't ask anyone else. Go back and
read it, and pay attention as though you were reading it for the first time.
--Charles E. Beck, P.E., Seattle, WA c2005
I like it!
I also like: "Don't tell, show!"
Lots of examples. Examples of increasing complexity that are selected to progressively illustrate a
single principle without explicitly preaching.
Lots of pictures and diagrams.
Emphasis of scanability and hackability as much as on readability.
Only one idea per sentence, one subject per paragraph. Favor separate short sentences over compound
sentences. Favor repeating names over using pronouns: "that", "this", "it", etc. If pronouns are
used, employ references within the same sentence, not to previous sentences, not to future
sentences, and certainly not to other paragraphs. Try hard to make the subject of a sentence a named
item instead of a pronoun -- reserve pronouns for objects or object clauses.
Developer preparation: Kindly add comments to the source code. The comments don't need to teach or
explain. They just need to repeat the code's logic, but in English instead of Martian.
_______________________________________________
ffmpeg-user mailing list
ffmpeg-user@ffmpeg.org
https://ffmpeg.org/mailman/listinfo/ffmpeg-user
To unsubscribe, visit link above, or email
ffmpeg-user-requ...@ffmpeg.org with subject "unsubscribe".
