On 08/23/2020 04:27 PM, Carl Zwanzig wrote:
On 8/23/2020 12:30 PM, Mark Filipak wrote:
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.
I think we'll have to disagree on that, most of the basic logic should be fairly clear to someone
who knows the 'c' language.
That leaves me out. It's also not true even for 'C' programmers for many reasons involving poor
choices of variable names, undocumented structures, strange methods, misunderstandings, etc., but I
don't want to get into a debate. I'd rather submit some of what I've already done and see what folks
think.
In other words, I'd rather do documentation than talk about documentation. Let's decide what works
as we go, eh?
How do we start? Should I post stuff to this list? Or is there another, better
way?
OTOH, there will be some cases they -do- need to be explained; there are
always points in code which aren't obvious to the casual reader - could be some obscure part of the
encoding, could be that it fails on some architectures but not on others, could be that a certain
flag isn't appropriate, etc. But in general, most code out there isn't well commented, anyway. (Way
back when, code wasn't considered well-commented if less than maybe 20-25% of the non-blank lines
were comments.)
See also
https://ffmpeg.org/developer.html#Comments
That's written in Martian. I don't read Martian.
https://ffmpeg.org/developer.html#toc-Code-of-conduct
"Kumbaya". It's pertinence to writing documentation is what?
However that doesn't directly affect the user documentation.
Agreed.
- Mark.
_______________________________________________
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".
