+
+- When exposing public C APIs, be careful what function parameters you make
+ "const". For example, a parameter taking a context object should probably not
+ be "const", even if you are writing an other-wise read-only accessor function
+ for it. The reason is that making it "const" fixates the contract that your
+ call won't alter the object ever, as part of the API. However, that's often
+ quite a promise, given that this even prohibits object-internal caching or
+ lazy initialization of object variables. Moreover it's usually not too useful
+ for client applications. Hence: please be careful and avoid "const" on object
+ parameters, unless you are very sure "const" is appropriate.
+
+- Make sure to enforce limits on every user controllable resource. If the user
+ can allocate resources in your code, your code must enforce some form of
+ limits after which it will refuse operation. It's fine if it is hardcoded (at
+ least initially), but it needs to be there. This is particularly important
+ for objects that unprivileged users may allocate, but also matters for
+ everything else any user may allocated.
+
+- htonl()/ntohl() and htons()/ntohs() are weird. Please use htobe32() and
+ htobe16() instead, it's much more descriptive, and actually says what really
+ is happening, after all htonl() and htons() don't operation on longs and
+ shorts as their name would suggest, but on uint32_t and uint16_t. Also,
+ "network byte order" is just a weird name for "big endian", hence we might
+ want to call it "big endian" right-away.
+
+- You might wonder what kind of common code belongs in src/shared/ and what
+ belongs in src/basic/. The split is like this: anything that uses public APIs
+ we expose (i.e. any of the sd-bus, sd-login, sd-id128, ... APIs) must be
+ located in src/shared/. All stuff that only uses external libraries from
+ other projects (such as glibc's APIs), or APIs from src/basic/ itself should
+ be placed in src/basic/. Conversely, src/libsystemd/ may only use symbols
+ from src/basic, but not from src/shared/. To summarize:
+
+ src/basic/ → may be used by all code in the tree
+ → may not use any code outside of src/basic/
+
+ src/libsystemd/ → may be used by all code in the tree, except for code in src/basic/
+ → may not use any code outside of src/basic/, src/libsystemd/
+
+ src/shared/ → may be used by all code in the tree, except for code in src/basic/, src/libsystemd/
+ → may not use any code outside of src/basic/, src/libsystemd/, src/shared/
+
+- Our focus is on the GNU libc (glibc), not any other libcs. If other libcs are
+ incompatible with glibc it's on them. However, if there are equivalent POSIX
+ and Linux/GNU-specific APIs, we generally prefer the POSIX APIs. If there
+ aren't, we are happy to use GNU or Linux APIs, and expect non-GNU
+ implementations of libc to catch up with glibc.