5

What is the correct way to name files and functions that are part of a C based code library/API?

Daniel Brose
  • 1,394
  • 10
  • 24
user773578
  • 1,161
  • 2
  • 13
  • 24
  • 1
    Well, in C you don't have methods so there is one less thing to worry about. Kidding. Just take a look on some open source C library and pick the one you like most. Regarding style, it is much better to be consistent than to be _correct_ (if there is such thing regarding coding style). – C2H5OH Apr 04 '12 at 23:04
  • File names must follow the rules of your file system. C function names must start with a non-number character and consist only of characters that form a valid identifier. – Kerrek SB Apr 04 '12 at 23:08
  • 1
    You're essentially asking for recommendations for a coding standard. That's a matter of taste, really. In any case, this is a dupe of http://stackoverflow.com/a/1262992/445525 – James Youngman Apr 04 '12 at 23:08

1 Answers1

8

What you can (but should not) do is be completely careless and use no systematic naming conventions at all. This 'works', but makes life uncomfortable for your customers; they have no easy way of knowing which names they can use in their own program. (I came across a library which defined a undocumented function for its internal use that was called error(). The name didn't match any part of the external documented namespaces. At the time, one of my own standard error reporting functions was also called error() — though it is now err_error(); that meant I couldn't use my own standard error reporting functions with that library. The upshot was I didn't use that library if I didn't have to; it was too much of a nuisance to use.)

So, you shouldn't be like that. You should be careful in the names you expose.

Your public header should use one (or a very few) systematic prefixes, which are documented. Typically, you'd choose a prefix such as PFX, and use that:

  • enumeration constants start PFX_.
  • macros start PFX_.
  • functions start pfx_.
  • global variables (you don't have any of those, do you) start pfx_.
  • type names and structure or union tags start pfx_.
  • Your private variables and functions that are visible outside their own source file have a systematic prefix (possibly pfx_ again, or maybe pfxp_ where the last p is for private, or perhaps pfx[A-Z] so that private names are camel-cased but start with pfx).

Only variables or functions that are strictly file scope (no external linkage) are not constrained by these rules, but even then, it is advisable to use the naming convention (so if a function needs to be used by two files later, you don't have to revise the calls in the code where the function was previously static).

This way, you can simply document that names starting PFX_ or pfx_ are reserved by your library. Users can still use names with the same prefix (you can't stop them), but they do so at their own risk because upgrades to the library might add names that are reserved. They can keep well clear of your names because you've documented them, and because the documentation is (relatively) easy to understand.

Note that the C standard and the POSIX standards both lay down rules for reserved names. However, the rules for the reserved POSIX and C names are considerably more complex than just a single prefix. They're also sweeping. For example, POSIX reserves all names ending _t for use as type names if any POSIX header is included.

Jonathan Leffler
  • 730,956
  • 141
  • 904
  • 1,278
  • Thank you. so pretty much replace the objc standard e.g ASIWebPageRequest method in objc could be asi_web_page_request in c? – user773578 Apr 04 '12 at 23:17
  • @user773578 ASIWebPageRequest is not a method, but a class. – Richard J. Ross III Apr 04 '12 at 23:19
  • Along those general lines, yes. Classically (look at the C standard) function names are lower-case. Macros tend to be upper-case. Types are mainly lower-case, etc. The most important things are to define a set of rules and then consistently apply them. Even to the extent of using `nm` to identify defined symbols in object files and making sure that they meet your rules. People don't often do that, but it is more difficult to use libraries without a coherent rule. – Jonathan Leffler Apr 04 '12 at 23:19