[FFmpeg-devel] [PATCH 4/6] doc/developer: add a code behaviour section to development policy

[Stefano Sabatini]

On date Tuesday 2023-08-29 10:34:45 +0200, Anton Khirnov wrote:
> Quoting Stefano Sabatini (2023-08-27 14:38:44)
> > Il sab 26 ago 2023, 20:08 Anton Khirnov <anton at khirnov.net> ha scritto:
> > 
> > > Document our longstanding de facto policies on things like correctness,
> > > thread-safety, UB, etc.
> > >
> > 
> > UB?
> 
> undefined behavior

yes, let's avoid acronyms

> 
> > 
> > ---
> > >  doc/developer.texi | 50 +++++++++++++++++++++++++++++++++-------------
> > >  1 file changed, 36 insertions(+), 14 deletions(-)
> > >
> > > diff --git a/doc/developer.texi b/doc/developer.texi
> > > index df43119f98..afa0148137 100644
> > > --- a/doc/developer.texi
> > > +++ b/doc/developer.texi
> > > @@ -274,10 +274,6 @@ symbols. If in doubt, just avoid names starting with
> > > @code{_} altogether.
> > >  @section Miscellaneous conventions
> > >
> > >  @itemize @bullet
> > > - at item
> > > -fprintf and printf are forbidden in libavformat and libavcodec,
> > > -please use av_log() instead.
> > > -
> > >  @item
> > >  Casts should be used only when necessary. Unneeded parentheses
> > >  should also be avoided if they don't make the code easier to understand.
> > > @@ -286,6 +282,42 @@ should also be avoided if they don't make the code
> > > easier to understand.
> > >  @anchor{Development Policy}
> > >  @chapter Development Policy
> > >
> > > + at section Code behaviour
> > > +
> > > + at subheading Correctness
> > > +The code must be valid. It must not crash, abort, access invalid
> > > pointers, leak
> > > +memory, cause data races or signed integer overflow, or otherwise invoke
> > > +undefined behaviour.
> > 
> > 
> > Invoke => assume?
> 

> No, 'assume' would mean something else. 'cause' maybe.

"cause" sounds good.

> 
> > 
> > Error codes should be checked and, when applicable,
> > > +forwarded to the caller.
> > > +
> > > + at subheading Thread- and library-safety
> > > +Our libraries may be called by multiple independent callers in the same
> > > process.
> > > +These calls may happen from any number of threads and the different call
> > > sites
> > > +may not be aware of each other - e.g. a user program may be calling us
> > > directly,
> > >
> > 
> > Calling us -> calling the/our libraries
> 

> I wanted to avoid using the word 'libraries' multiple times, to avoid
> possible confusion of which library is being talked about - whether ours
> or some external one.

But using "us" is even more confusing (who/what is "us"?), I have no
better ideas than repeating "our/the FFmpeg libraries".