[Ffmpeg-devel] Naming conventions

[Måns Rullgård]

Panagiotis Issaris said:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
> Hi,
>
> I want to start a discussion regarding possible FFmpeg naming
> conventions. I think the current situation is suboptimal and would like
> to send some patches to enchance the situation. That's why I want some
> input from others.
>
> Currently, some public API functions are prefixed with avcodec_, some
> with av_, some with avpicture_ some are not prefixed (such as
> register_avcodec, dump_format, parse_image_size, parse_frame_rate,
> parse_date, find_info_tag, video_grab_init, audio_init, dv1394_init,
> dc1394_init), some with ffm_, some with avpicture_, ...
>
> I think consistently named APIs are not only a pleasure to look at, but
> really make a library much easier to use. With a truly consistently
> named API you can nearly guess the name of the function you need to use,
> when thinking of some stuff you need to do.
>
> So, I'd like write some patches making the API more (hopefully fully)
> consistent and therefore want to know what kind of naming conventions
> libav* developers and users prefer.
>
> In a previous thread [1] on this mailinglist, Michael Niedermayer and
> Baptiste Coudurier made some remarks regarding naming conventions.
>
>
> I think all agree that all public API functions should be prefixed with
> at least "av" and possibly "av_".
>
> Personally, I see various possibilities for structuring function names.
>
> The names could in some way include:
>
> * The name of the library: So, a prefix such as avc, avu and avf. It has
> the disadvantage that if functions are migrated to another library,
> they'll have to be renamed and thus cause ABI breakage. Libavcodec in
> some way seems to use this convention: avcodec_thread_init,
> avcodec_version, ... Libavformat and libavutil do not.

There is a historical reason for some of the current names.  Way back in the
Dark Ages, libavformat was called libav.  Most of the public API functions
in libavcodec were given an avcodec_ prefix, and the libav functions got an
av_ prefix.

Most functions only intended for internal use, albeit with extern linkage,
were not adorned with prefixes.  They should have been, but they were not.

> * The name of the type "it works on". Libavformat uses this for some of
> its functions: av_parser_init, av_parser_parse, av_parser_change,
> av_bitstream_filter_init, avpicture_alloc, avpicture_free, ...

Those functions are actually in lavc...

> * And of course the actual description of what the function does, the
> action.
>
> How should these possibly included parts be ordered? The previously
> mentioned functionnames used the "type_action" order, but there also
> appear functions which do not use this order:
> av_init_packet, av_new_packet, av_get_packet, av_dup_packet,
> av_free_packet, ...
>
> _Personally_, I prefer the "type_action" type of names, and having all
> of them prefixed with some FFmpeg specific part, so that the chance of
> namecollisions is greatly reduced.

I agree with you about what makes good names.  I am, however, reluctant to
change names just for the sake of it, at least without giving it proper
consideration first.  If we want to do a naming cleanup, we should make
sure to cover all of the public API, so we only need to break compatibility
once.

While we ponder this, we can start out by cleaning up the names of internal
functions (and other symbols).

-- 
M?ns Rullg?rd
mans at mansr.com